Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Media2 spec update for audio clip management feature #448

Open
wants to merge 14 commits into
base: development
Choose a base branch
from
+730 −1
Open

Media2 spec update for audio clip management feature #448

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
8af1a1e
Media2 spec update for audio clip management feature
venki5685 Aug 1, 2024
98bca07
Configuration Prefix removed from Audio Clip Management APIs
venki5685 Aug 23, 2024
119f412
AudioProfile WG feedback
venki5685 Sep 3, 2024
19c7c59
Audio Clip Management - Bangkok F2F review comments addressed
venki5685 Sep 19, 2024
a6f08cf
SupportedAudioClipFormat enumerations are defined
venki5685 Sep 25, 2024
0836953
Audio Clip Management - Optional Token in AddAudioClip, editorial cha…
venki5685 Sep 29, 2024
b35beb0
review comments addressed. Supported audio clip formats defined in me…
venki5685 Oct 28, 2024
3d71892
editorial changes review comments addressed
venki5685 Nov 6, 2024
0d7d078
editorial changes review comments addressed
venki5685 Nov 6, 2024
b08d354
Change 'a HTTP' to 'an HTTP' to match #492 (#495)
johado Nov 27, 2024
60471b3
Audio Clip start and stop event schema defined
Dec 4, 2024
4b62e0f
Audio Clip event schema update
Dec 5, 2024
a752411
Review comments addressed
Feb 1, 2025
40d92c1
supported audio clip format mime types update
Mar 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions doc/ActionEngine.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1251,6 +1251,20 @@
</tt:ElementItem>
</tt:Parameters>
</tae:Configuration>
&lt;/tae:Action&gt;</programlisting>
<para>Play the audio clip when line crossing event is triggered</para>
<programlisting>&lt;tae:Action Token=”5674751”&gt;
&lt;tae:Configuration Name=”AudioClip_Play” Type=”tae:CommandAction”&gt;
&lt;tt:Parameters&gt;
&lt;tt:SimpleItem Name=”XAddr” Value=”http://127.0.0.1/Onvif/media2_service”/&gt;
&lt;tt:SimpleItem Name=”Operation” Value=”tr2:PlayAudioClip”/&gt;
&lt;tt:ElementItem Name=”Parameters”&gt;
&lt;tt:Token&gt;Audio_Clip_1&lt;/tt:Token&gt;
&lt;tt:AudioOutputToken&gt;AudioOutput1&lt;/tt:AudioOutputToken&gt;
&lt;tt:Play&gt;true&lt;/tt:Play&gt;
&lt;/tt:ElementItem&gt;
&lt;/tt:Parameters&gt;
&lt;/tae:Configuration&gt;
&lt;/tae:Action&gt;</programlisting>
</section>
<section>
Expand Down
260 changes: 259 additions & 1 deletion doc/Media2.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2167,6 +2167,249 @@
</variablelist>
</section>
</section>
<section xml:id="section_k4m_bcd_yyz">
<title>Audio Clip Management</title>
<section>
<title>Audio Clip Configuration</title>
<para>This section is about uploading one or more pre-recorded audio clips to the device.
The uploaded audio clips can be played by the user on need basis or on configured schedule time or
when the associated event is triggered. Audio Clip configuration has the following parameters:</para>
<itemizedlist>
<listitem>
<para>Enabled [xs:boolean] – Enables/disables the audio clip.</para>
</listitem>
<listitem>
<para>Name [xs:string] – Name of the audio clip.</para>
</listitem>
<listitem>
<para>AudioOutputToken [tt:ReferenceToken] optional, unbounded – Optional Token list of physical Audio Outputs. If no AudioOutputToken is provided, device should play the audio clip in all physical Audio Outputs.</para>
</listitem>
<listitem>
<para>Type [xs:string] - Format of the audio clip. For definitions see tr2:SupportedAudioClipFormat parameter.</para>
</listitem>
<listitem>
<para>RepeatCycles [xs:int] - Number of times the audio clip can be repeated when it is played. The value 0 means no repeat i.e. play the audio clip, does not repeat after the first play. 1 means play the audio clip and repeat once after the first play. -1 means repeat the audio clip infinite after first play until the clip is stopped by the user operation.</para>
</listitem>
<listitem>
<para>RepeatInterval [xs:int] optional - Optional time interval between audio clips when audio clip is repeated in seconds.</para>
</listitem>
<listitem>
<para>AudioOutputLevel [xs:int] optional - Optional level to control volume of the audio clip when it is played.</para>
</listitem>
<listitem>
<para>ScheduleToken [tt:ReferenceToken] optional - Optional Schedule token associated with the audio clip. Audio clip can be played when configured schedule is triggered.</para>
</listitem>
</itemizedlist>
<para>The device should accept optional ScheduleToken from the client if it supports ONVIF Schedule service specification.</para>
</section>
<section xml:id="section_wys_czg_ryc">
<title>GetAudioClips</title>
<para>This operation gets audio clip configurations from the device.
If audio clip token is provided, the device shall return the audio clip configuration associated with the token.
If no token is provided, the device shall return all audio clip configurations exist in the device.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Token - optional
[tt:ReferenceToken]</para>
<para role="text">Token associated with the audio clip.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="param">AudioClipItem - optional, unbounded [tr2:GetAudioClipsResponseItem] </para>
<para role="text">List of Audio clip items.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoAudioClip</para>
<para role="text">The audio clip token does not exist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">READ_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="section_wvd_dzg_ryd">
<title>AddAudioClip</title>
<para>This operation adds audio clip configuration to the device and provides audio clip upload
URI to the client. The response to the command includes an HTTP URL to which the audio clip may
be uploaded with in the expiry time. If the client could not upload audio clip within the URL expiry time,
the associated audio clip configuration can be removed permanently from the device.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Configuration -
[tr2:AudioClip]</para>
<para role="text"> Audio Clip Configuration to add.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="param">Token - [tt:ReferenceToken]</para>
<para role="text">Token of the audio clip to be uploaded.</para>
<para role="param">UploadUri - [xs:anyURI]</para>
<para role="text">A URL to which the audio clip may be uploaded.</para>
<para role="param">ExpiryTime - [xsd:DateTime]</para>
<para role="text">Expiry time before which client should upload audio clip to the UploadUri.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Receiver - ter:Action - ter:MaxAudioClipLimit</para>
<para role="text">The maximum number of audio clip configurations supported by the device has been reached.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidConfig</para>
<para role="text">The configuration parameters are not possible to set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">WRITE_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
<para></para>
<para>Note: Audio clip upload to the device can fail in the following scenarios and specific HTTP error code should return to the client when upload fails.</para>
<itemizedlist>
<listitem>
<para>When the Upload Url is expired, device should return HTTP 410 error to the client.</para>
</listitem>
<listitem>
<para>When format of the audio clip upload does not match with Type parameter in the audio clip configuration, device should return HTTP 415 Unsupported Media Type error to the client.</para>
</listitem>
<listitem>
<para>When size of the audio clip upload exceeds MaxAudioClipSize parameter in KB, device should return HTTP 413 Request Too Large error to the client.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="section_wvd_dzg_rye">
<title>SetAudioClip</title>
<para>This operation modifies existing audio clip configuration in the device.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Token - [tt:ReferenceToken]</para>
<para role="text"> Unique Token associated with the audio clip.</para>
<para role="param">Configuration -
[tr2:AudioClip]</para>
<para role="text"> Audio Clip Configuration to modify.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">This is an empty message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoAudioClip</para>
<para role="text">The audio clip token does not exist.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:InvalidConfig</para>
<para role="text">The configuration parameters are not possible to set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">WRITE_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
<para> Note: Format of the audio clip cannot be changed during SetAudioClip operation.</para>
</section>
<section xml:id="section_wvd_dzg_ryf">
<title>DeleteAudioClip</title>
<para>This operation deletes audio clip configuration and associated audio clip in the device.
The audio clip should be de-associated with the event trigger if it is already associated before this operation.
This operation fails if the device is playing the audio clip same time due to user operation or schedule or event trigger.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Token -
[tt:ReferenceToken]</para>
<para role="text"> Token of the Audio Clip</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">This is an empty message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoAudioClip</para>
<para role="text">The audio clip token does not exist.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:AudioClipDeleteError</para>
<para role="text">The audio clip cannot be deleted due to device current usage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">WRITE_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="section_wvd_dzg_ryg">
<title>PlayAudioClip</title>
<para>This operation play or stop ongoing audio clip in the device.</para>
<variablelist role="op">
<varlistentry>
<term>request</term>
<listitem>
<para role="param">Token - [tt:ReferenceToken]</para>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For stop operation, token optional to be able to stop whatever active.

<para role="text"> Token of the Audio Clip to play or stop.</para>
<para role="param">AudioOutputToken - optional, unbounded [tt:ReferenceToken]</para>
<para role="text"> Optional Token list of physical Audio Outputs. If the AudioOutputToken is not provided in the API request, the AudioOutputToken in Audio Clip Configuration to be used.</para>
<para role="param">Play - [xs:boolean]</para>
<para role="text"> If it is true play the audio clip, if it is false stop ongoing audio clip.</para>
<para role="param">RepeatCycles - optional [xs:int]</para>
<para role="text"> Optional RepeatCycles used for the current play operation. If the RepeatCycles is not provided in the API request, the RepeatCycles in Audio Clip Configuration to be used for the current play operation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>response</term>
<listitem>
<para role="text">This is an empty message.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>faults</term>
<listitem>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoAudioClip</para>
<para role="text">The audio clip token does not exist.</para>
<para role="param">env:Sender - ter:InvalidArgVal - ter:NoAudioOutput</para>
<para role="text">The audio output token does not exist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access class</term>
<listitem>
<para role="access">READ_SYSTEM</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="_Ref484170228">
<title>GetServiceCapabilities</title>
<para>The capabilities reflect optional functions and functionality of a service. The information is static and does not change during device operation. </para>
Expand Down Expand Up @@ -2291,7 +2534,22 @@
</listitem>
</varlistentry>
</variablelist>
</section>
<para>The following audio clip capabilites are available:</para>
<variablelist>
<varlistentry>
<term>MaxAudioClipLimit</term>
<listitem><para>Indicates the supported Maximum number of audio clips can be uploaded.</para></listitem>
</varlistentry>
<varlistentry>
<term>MaxAudioClipSize</term>
<listitem><para>Indicates Maximum size of the audio clip can be uploaded in KB.</para></listitem>
</varlistentry>
<varlistentry>
<term>SupportedAudioClipFormat</term>
<listitem><para>A list of audio clip formats that is supported by the device,see tr2:SupportedAudioClipFormat for possible values.</para></listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Events</title>
<section>
Expand Down
Loading