RecordingControl.xml

<?xml version="1.0"?>
<?xml-stylesheet href="docbook.xsl" type="text/xsl" ?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
  <info>
    <title>ONVIF Recording Control Service Specification</title>
    <titleabbrev>RecordingControl</titleabbrev>
    <releaseinfo>24.12</releaseinfo>
    <author>
      <orgname>ONVIF™</orgname>
      <uri>www.onvif.org</uri>
    </author>
    <pubdate>December, 2024</pubdate>
    <mediaobject>
      <imageobject>
        <imagedata fileref="media/logo.png" contentwidth="60mm"/>
      </imageobject>
    </mediaobject>
    <copyright>
      <year>2008-2024</year>
      <holder>ONVIF™ All rights reserved.</holder>
    </copyright>
    <legalnotice>
      <para>Recipients of this document may copy, distribute, publish, or display this document so long as this copyright notice, license and disclaimer are retained with all copies of the document. No license is granted to modify this document.</para>
      <para>THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIR AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT ARE SUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.</para>
      <para>IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT, WHETHER OR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT.  THE FOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR RESPECTIVE AFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF THE CORPORATION.</para>
    </legalnotice>
    <revhistory>
      <revision>
        <revnumber>2.1</revnumber>
        <date>Jul-2011</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Split from Core 2.0 without change of content.</revremark>
      </revision>
      <revision>
        <revnumber>2.1.1</revnumber>
        <date>Jan-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Requests 293, 297, 535</revremark>
      </revision>
      <revision>
        <revnumber>2.2</revnumber>
        <date>Apr-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Requests 608, 625, 636, 673</revremark>
      </revision>
      <revision>
        <revnumber>2.2.1</revnumber>
        <date>Dec-2012</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Requests 708, 709, 719, 759, 827, 845, 852, 866, 867, 870, 862, 872, 861</revremark>
      </revision>
      <revision>
        <revnumber>2.3</revnumber>
        <date>May-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 934</revremark>
      </revision>
      <revision>
        <revnumber>2.4</revnumber>
        <date>Aug-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1073, 1086</revremark>
      </revision>
      <revision>
        <revnumber>2.4.1</revnumber>
        <date>Dec-2013</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1148, 1189</revremark>
      </revision>
      <revision>
        <revnumber>2.4.2</revnumber>
        <date>Jun-2014</date>
        <author>
          <personname>Michio Hirai</personname>
        </author>
        <revremark>Change Request 1292, 1298, 1304, 1412</revremark>
      </revision>
      <revision>
        <revnumber>2.5</revnumber>
        <date>Dec-2014</date>
        <author>
          <personname>Hasan Timucin Ozdemir</personname>
        </author>
        <revremark>Added 5.21 ExportRecordedData command and corresponding capability flag in 5.24 Capabilitites 
Added 5.22 StopExportRecordedData
Added 5.23 GetExportRecordedDataStatus</revremark>
      </revision>
      <revision>
        <revnumber>16.12</revnumber>
        <date>Dec-2016</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Change Request 1991</revremark>
      </revision>
      <revision>
        <revnumber>17.06</revnumber>
        <date>Jun-2017</date>
        <author>
          <personname>Stefan Andersson</personname>
        </author>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Update method layouts
Change Request 1843, 2060, 2062
Change Request 2061, 2063, 2065, 2109</revremark>
      </revision>
      <revision>
        <revnumber>17.12</revnumber>
        <date>Dec-2017</date>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Change Request 2178, 2179, 2185</revremark>
      </revision>
      <revision>
        <revnumber>18.06</revnumber>
        <date>Jun-2018</date>
        <author>
          <personname>Hiroyuki Sano</personname>
        </author>
        <revremark>Change Request 2230, 2258</revremark>
      </revision>
      <revision>
        <revnumber>19.06</revnumber>
        <date>Jun-2019</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Added Scheduled Recording</revremark>
      </revision>
      <revision>
        <revnumber>21.12</revnumber>
        <date>Dec-2021</date>
        <author>
          <personname>Sergey Bogdanov</personname>
        </author>
        <revremark>Change the "role" attribute for request access class.</revremark>
      </revision>
      <revision>
        <revnumber>22.12</revnumber>
        <date>Dec-2022</date>
        <author>
          <personname>Hans Busch</personname>
        </author>
        <revremark>Add support for event recording.</revremark>
      </revision>
      <revision>
        <revnumber>23.06</revnumber>
        <date>Jun-2023</date>
        <author>
          <personname>Felix Schuetz</personname>
        </author>
        <revremark>Add annex on object storage recording.</revremark>
      </revision>
      <revision>
        <revnumber>24.12</revnumber>
        <date>Dec-2024</date>
        <author>
          <personname>Sriram Bhetanabottla</personname>
        </author>
        <revremark>Clarify delete interfaces for object storage.</revremark>
      </revision>
    </revhistory>
  </info>
  <chapter>
    <title>Scope </title>
    <para>This document defines the web service interface for the configuration of recording of Video, Audio and Metadata. Additionally associated events are defined.</para>
    <para>The overview section provides a definition of the ONVIF storage model. This is common for all ONVIF storage related services.</para>
    <para>Web service usage is outside of the scope of this document. Please refer to the ONVIF core specification.</para>
  </chapter>
  <chapter>
    <title>Normative references</title>
    <para role="reference">ISO/IEC 14496-12:2022 — Information technology — Coding of audio-visual objects — Part 12: ISO base media file format &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iso.org/standard/83102.html" />&gt;</para>
    <para role="reference">ISO/IEC 14496-14:2020 — Information technology — Coding of audio-visual objects — Part 14: MP4 file format &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iso.org/standard/79110.html" />&gt;</para>
    <para role="reference">ISO/IEC 23000-19:2020 — Information technology — Multimedia application format (MPEG-A) — Part 19: Common media application format (CMAF) for segmented media &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iso.org/standard/79106.html" />&gt;</para>
    <para role="reference">ISO/IEC 23001-7:2016 — Information technology — MPEG systems technologies — Part 7: Common encryption in ISO base media file format files &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iso.org/standard/68042.html" />&gt;</para>
    <para role="reference">ISO 8601-1:2019 — Date and time — Representations for information interchange — Part 1: Basic rules &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iso.org/standard/70907.html" />&gt;</para>
    <para role="reference">RFC 5234 — Augmented BNF for Syntax Specifications: ABNF &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ietf.org/rfc/rfc5234.txt" />&gt;</para>
    <para role="reference">RFC 6381 — The 'Codecs' and 'Profiles' Parameters for "Bucket" Media Types &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ietf.org/rfc/rfc6381.txt" />&gt;</para>
    <para role="reference">ONVIF Core Specification &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/specs/core/ONVIF-Core-Specification.pdf"></link>&gt;</para>
    <para role="reference">ONVIF Schedule Service Specification &lt;<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.onvif.org/specs/srv/sched/ONVIF-Scheduler-Service-Spec.pdf"></link>&gt; </para>
  </chapter>
  <chapter>
    <title>Terms and Definitions</title>
    <section>
      <title>Definitions</title>
      <informaltable>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="24*"/>
          <colspec colname="c2" colwidth="76*"/>
          <tbody valign="top">
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Metadata</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>All streaming data except video and audio, including video analytics results, PTZ position data and other <phrase>metadata (such as textual data from POS applications)</phrase>.</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>A container for a set of audio, video and metadata tracks. A recording can hold one or more tracks. A track is viewed as an infinite timeline that holds data at certain times.</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording Event</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>An event associated with a Recording, represented by a notification message in the APIs</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Recording Job</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>A job performs the transfer of data from a data source to a particular recording using a particular configuration</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Track</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>An individual data channel consisting of video, audio, or metadata. This definition is consistent with the definition of track in [RFC 2326]</para>
              </entry>
            </row>
            <row>
              <entry align="left">
                <para>
                  <emphasis role="bold">Video Analytics</emphasis>
                </para>
              </entry>
              <entry align="left">
                <para>Algorithms or programs used to analyze video data and to generate data describing object location and behaviour.</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
  </chapter>
  <chapter>
    <title>Overview</title>
    <section>
      <title>Storage</title>
      <para>This standard provides a set of interfaces that enable the support of interoperable network storage devices, such as network video recorders (NVR), digital video recorders (DVR) and cameras with embedded storage.</para>
      <para>The following functions are supported:</para>
      <itemizedlist>
        <listitem>
          <para>Recording Control</para>
        </listitem>
        <listitem>
          <para>Search</para>
        </listitem>
        <listitem>
          <para>Replay</para>
        </listitem>
      </itemizedlist>
      <para>These functions are provided by three interrelated services:</para>
      <para>
        <emphasis role="bold">Recording service </emphasis>enables a client to manage recordings, and to configure the transfer of data from data sources to recordings. Managing recordings includes creation and deletion of recordings and tracks.</para>
      <para>
        <emphasis role="bold">Search service</emphasis> enables a client to find information about the recordings on the storage device, for example to construct a “timeline” view, and to find data of interest within a set of recordings. The latter is achieved by searching for events that are included in the metadata track recording,</para>
      <para>
        <emphasis role="bold">Replay service</emphasis> enables a client to play back recorded data, including video, audio and metadata. Functions are provided to start and stop playback and to change speed and direction of the replayed stream. It also enables a client to download data from the storage device so that export functionality can be provided.</para>
      <para>WSDL for this service is specified in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.onvif.org/onvif/ver10/recording.wsdl">http://www.onvif.org/onvif/ver10/recording.wsdl</link>.</para>
      <table>
        <title>Referenced namespaces (with prefix)</title>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="13*" />
          <colspec colname="c2" colwidth="87*" />
          <thead>
            <row>
              <entry>
                <para>Prefix</para>
              </entry>
              <entry>
                <para>Namespace URI</para>
              </entry>
            </row>
          </thead>
          <tbody valign="top">
            <row>
              <entry>
                <para>env</para>
              </entry>
              <entry>
                <para>http://www.w3.org/2003/05/soap-envelope</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>ter</para>
              </entry>
              <entry>
                <para>http://www.onvif.org/ver10/error</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>xs </para>
              </entry>
              <entry>
                <para>http://www.w3.org/2001/XMLSchema </para>
              </entry>
            </row>
            <row>
              <entry>
                <para>tt</para>
              </entry>
              <entry>
                <para>http://www.onvif.org/ver10/schema</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>trc</para>
              </entry>
              <entry>
                <para>http://www.onvif.org/ver10/recording/wsdl</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <section>
        <title>Storage Model</title>
        <para>The storage interfaces in this standard present a logical view of the data on the storage device. This view is completely independent of the way data might be physically stored on disk.</para>
        <para>The key concept in the storage model is that of a <emphasis>recording</emphasis>. The term <emphasis>recording</emphasis> is used in this specification to denote a container for a set of related audio, video and metadata <emphasis>tracks</emphasis>, typically from the same data source e.g. a camera. A <emphasis>recording</emphasis> could hold any number of tracks. A <emphasis>track</emphasis> is viewed as an infinite timeline that holds data at certain times. </para>
        <para>At a minimum, a recording is capable of holding three tracks, one for audio, one for video and one for metadata. Some implementations of the recording service may support multiple tracks of each type. For example the same recording could hold two video tracks, one containing a low resolution or low frame rate stream and one containing a high resolution or high frame rate stream.</para>
        <figure>
          <title>Storage Model with Tracks</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="media/RecordingControl/image2.svg" contentwidth="131.41mm" contentdepth="47.33mm" />
            </imageobject>
          </mediaobject>
        </figure>
        <para>It is important to note that the storage interfaces do not expose the internal storage structures on the device. In particular, a recording is not intended to represent a single file on disk although in many storage device implementations a recording is physically stored in a series of files. For instance, some camera implementations realise alarm recording by creating a distinct file for each alarm that occurs. Although each file could be represented as a different <emphasis>recording</emphasis>, the intent of the model in this standard is that all these files are aggregated into a single recording.</para>
        <para>Within a recording the regions where data is actually recorded are represented by pairs of events, where each pair comprises an event when recording started and an event when recording stopped. A client can construct the logical view of the recordings by using the FindRecordings and FindEvents methods of the search service.</para>
        <para>If metadata is recorded, the metadata track can hold all the events generated by the data source (see the chapter on event handling and the MetadataConfiguration object). In addition, a device also conceptually records ONVIF defined historical events (see Recording Event Descriptions in the search service), this includes information like start and end of a recorded data range. A device may also conceptually record vendor specific historical events. Events generated by the device are not inserted in existing metadata tracks of recordings. The FindEvents method in the search service can find all the recorded events.</para>
      </section>
      <section>
        <title>Recording</title>
        <para>The recording service enables a client to manage recordings, and to configure the transfer of data from data sources to recordings. Managing recordings includes creation and deletion of recordings and tracks.</para>
        <para>Recording jobs transfer data from a recording source to a recording. A recording source can be a receiver object created with the receiver service, or it can be a media profile that encodes data on a local device. The media profile could be used as a source on a camera with embedded storage.</para>
        <para>To save data to a recording, a client first creates a recording and ensures that the recording has the necessary tracks. Then the client creates a recording job that pulls data from one or more sources and stores the data to the tracks in the recording. </para>
        <para>Clients may set up multiple recording jobs that all record into the same recording. If multiple recording jobs are active, the device uses a priority scheme to select between the tracks defined in the recording jobs. Clients may change the mode of recording jobs at any time, thereby providing means to implement features like alarm recording or manual recording.</para>
        <para>If a device supports scheduled recording, clients may configure scheduled recording by adding a scheduler token to the recording job. A recording job with a scheduler token will only record when the associated schedule is active. If the associated schedule of a recording job is inactive a job with lower recording priority may record.</para>
        <para>By default a recording job is continuously recording. Devices supporting the
          EventFilter can be configured such that they only record events. To provide some context
          time intervals before and after the event may be captured.</para>
        <para>The recording job relies on the receiver service for receiving the data from other devices through receiver objects identified by ReceiverTokens</para>
      </section>
      <section>
        <title>External targets</title>
        <para>
          The target interface allows configuration for devices that support recording to external storage targets. 
          For authentication configuration see the related storage configuration APIs of the core specification.
        </para>
        <para>
          The target API defines for each recording a path on the storage device where the related recordings should be stored.
          In order to keep reasonably sized files the recordings are split into segments.
          This specification defines a date and time based index.
          Indexing according to events and video content is outside of the scope of this specification.
        </para>
        <para>An encryption configuration interface allows to encrypt the content according to well defined standards.</para>
      </section>
    </section>
  </chapter>
  <chapter>
    <title>
      <emphasis role="highlight" />Recording control</title>
    <section>
      <title>Introduction</title>
      <para>The recording service enables a client to manage recordings, and to configure the transfer of data from data sources to recordings. Managing recordings includes creation and deletion of recordings and tracks, as well as locking and unlocking ranges of recordings and deletion of recorded data.</para>
      <para>Recording jobs transfer data from a recording source to a recording. A recording source can be a receiver object created with the receiver service, or it can be a media profile that encodes data on a local device. The media profile could be used as a source on a camera with embedded storage.</para>
      <para>The term <emphasis>recording</emphasis> is used in this specification to denote a container for a set of audio, video and metadata tracks. A recording could hold any number of tracks. A track is viewed as an infinite timeline that holds data at certain times.</para>
      <figure>
        <title>Example of recordings and tracks</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/image2.svg" contentwidth="131.41mm" contentdepth="47.33mm" />
          </imageobject>
        </mediaobject>
      </figure>
      <para>The figure shows three recordings, each with a video, a metadata and two audio tracks. Here second audio track is used for storing the audio backchannel.</para>
      <para>At a minimum, a recording shall be capable of holding three tracks, one for audio, one for video and one for metadata. Some implementations of the recording service may support multiple tracks of each type. All recorded data of a track shall have the same encoding.</para>
      <para>To save data to a recording, a client first creates a recording and ensures that the recording has the necessary tracks. Then the client creates a recording job that pulls data from one or more sources and stores the data to the tracks in the recording. </para>
      <para>Clients may set up multiple recording jobs that all record into the same recording. If multiple recording jobs are active, the device uses a priority scheme to select between the tracks defined in the recording jobs. Clients may change the mode of recording jobs at any time, thereby providing means to implement features like alarm recording or manual recording. A recording job with schedule token shall only be recording when the associated schedule is active.</para>
      <para>For the cases where media attributes of a source are changed for an active recording job, the recording state is outside the scope of this specification.</para>
      <para>The recording job relies on the receiver service for receiving the data from other devices through receiver objects identified by ReceiverTokens</para>
      <para>For the cases where a client uses a receiver object with a single recording job, the recording service can auto create and auto delete receiver objects. Autocreation is signalled with the AutoCreateReceiver flag in the recording job configuration structure. Receiver objects created this way shall be automatically deleted when no recording job uses them anymore. A receiver object that is automatically created shall have all its fields set to empty values. The client should configure the receiver object after it has created the recording job.</para>
      <para>The ONVIF view of recordings is a logical one which is independent of the way recordings are physically stored on disk. For instance, some camera implementations realise alarm recording by creating a distinct file on a FAT file system for each alarm that occurs. Although each file could be represented as a different ONVIF recording, the intent of the model in this standard is that all these files are aggregated into a single recording. By searching for the “DataPresent” event with the FindEvents method of the search service, a client can locate the times at which video started to be recorded and where video stopped being recorded.</para>
      <para>If Metadata is recorded, the metadata can also hold all the events generated by the data source (see section event handling of the ONVIF Core Specification and section on Metadata configuration in the ONVIF Media Service Specification). In addition, a device also conceptually record ONVIF defined historical events (see Recording Event Descriptions in the search service), this includes information like start and end of a recorded data range. A device may also conceptually record vendor specific historical events. Events generated by the device are not inserted in existing metadata tracks of recordings. The FindEvents method in the search service can find all the recorded events. Many device implementations will automatically delete the oldest recorded data from storage in order to free up space for new recordings. Locks provide a mechanism to allow a user to select ranges of data. A range of data that is locked does not get deleted automatically. Support for locks is reserved for future versions of the specification.</para>
    </section>
    <section>
      <title>General Requirements</title>
      <para>All the objects created within the recording service shall be persistent – i.e. they shall survive a power cycle. Likewise, all the configuration data in the objects shall be persistent.</para>
    </section>
    <section xml:id="_Toc247178839">
      <title>Data structures</title>
      <section>
        <title>RecordingConfiguration</title>
        <para>The RecordingConfiguration structure shall be used to configure recordings through CreateRecordings and Get/SetRecordingConfiguration.</para>
        <para>
          <emphasis role="bold">MaximumRetentionTime</emphasis> specifies the maximum time that data in any track within the recording shall be stored. The device shall delete any data older than the maximum retention time. Such data shall not be accessible anymore. If the MaximumRetentionPeriod is set to 0, the device shall not limit the retention time of stored data, except by resource constraints. Whatever the value of MaximumRetentionTime, the device may automatically delete recordings to free up storage space for new recordings.</para>
        <para>
          None of the other fields defined in this structure shall be used by the device.
          Instead, it simply stores this information, and it shall return it through the <emphasis>GetRecordingConfiguration</emphasis> and <emphasis>GetRecordingInformation</emphasis> (see ONVIF Recording Search Service Specification) methods.</para>
        <para>
          A device may truncate any descriptive string without causing a fault if it exceeds the supported length.
          Descriptive strings are Location, Description and Content.
        </para>
        <para>
          A device signaling support for recording to external targets via the SupportedTargetFormats capability shall support the target configuration with the following parameters:
        </para>
        <variablelist>
          <varlistentry>
            <term>Storage</term>
            <listitem>
              <para>Token of a storage configuration.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Format</term>
            <listitem>
              <para>
                Format of the recording.
                Examples are <literal>MP4</literal> and <literal>CMAF</literal>.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Prefix</term>
            <listitem>
              <para>Path prefix to be inserted in the object key.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Postfix</term>
            <listitem>
              <para>Path postfix to be inserted in the object key.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>SpanDuration</term>
            <listitem>
              <para>Maximum duration of a span.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>SegmentDuration</term>
            <listitem>
              <para>Maximum duration of a segment.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Encryption</term>
            <listitem>
              <para>Optional encryption configuration.</para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para> See <xref linkend="_refCloudRecording"/> for ONVIF defined recording formats.</para>
      </section>
      <section>
        <title>TrackConfiguration</title>
        <para>The TrackConfiguration structure shall be used to configure tracks using CreateTrack and Get/SetTrackConfiguration</para>
        <para>The TrackConfiguration contains the following fields:</para>
        <para>The <emphasis role="bold">TrackType</emphasis> defines the data type of the track. It shall be equal to the strings “Video”, “Audio” or “Metadata”. The track shall only be able to hold data of that type.</para>
        <para>None of the other fields defined in this structure shall be used by the device. Instead, it simply stores this information, and it shall return it through the <emphasis>GetTrackConfiguration</emphasis> and <emphasis>GetRecordingInformation</emphasis> (see ONVIF Recording Search Service Specification) methods.</para>
      </section>
      <section>
        <title>RecordingJobConfiguration</title>
        <para>The RecordingJobConfiguration structure shall hold the configuration for a recording job. Its UML diagram is hown in <xref linkend="image3"/>.</para>
        <figure xml:id="image3">
          <title>UML diagram of the RecordingJobConfiguration</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="media/RecordingControl/image3.svg" contentdepth="75.89mm" />
            </imageobject>
          </mediaobject>
        </figure>
        <para>The RecordingJobConfiguration holds the following fields:</para>
        <para>
          <emphasis role="bold">RecordingToken</emphasis>: Identifies the recording to which this job shall store the received data.</para>
        <para>
          <emphasis role="bold">Mode</emphasis>: If it is idle, nothing shall happen. If it is active and the recording job has the highest priority, the device shall try to obtain data from the receivers. A client shall use GetRecordingJobState to determine if data transfer is really taking place. The only valid values for Mode shall be “Idle” and “Active”.</para>
        <para>
          <emphasis role="bold">Priority</emphasis>: This shall be a non-negative number. If there
          are multiple recording jobs that store data to the same track, the device shall only store
          data for the recording job with the highest priority. The priority is specified per
          recording job, but the device shall determine the priority of each track individually. If
          there are multiple recording jobs with the same highest priority it is undefind which of
          them is activated.</para>
        <para>The value 0 indicates the lowest priority. Higher values shall indicate a higher priority.</para>
        <para>
          <emphasis role="bold">ScheduleToken:</emphasis> This attribute adds an additional requirement for activating the recording job. If this optional field is provided the job shall only record if the schedule exists and is active.</para>
        <para>
          <emphasis role="bold">EventFilter:</emphasis> This set of parameters allows to control recording depending on a given set of event condititions.</para>
        <para>
          <emphasis role="bold">SourceToken</emphasis>: This field shall be a reference to the source of the data. The type of the source is determined by the attribute Type in the SourceToken structure. If Type is http://www.onvif.org/ver10/schema/Receiver, the token is a ReceiverReference. In this case the device shall receive the data over the network. If Type is http://www.onvif.org/ver10/schema/Profile, the token identifies a media profile, instructing the device to obtain data from a profile that exists on the local device. </para>
        <para>A device that includes the ONVIF Media Service shall support a Media Profile token and a device that includes the ONVIF Receiver Service shall support a Receiver token.</para>
        <para>
          <emphasis role="bold">AutoCreateReceiver</emphasis>: If a request includes this field set to true and no source token is provided, the device shall create a
          receiver object (through the receiver service) and assign the ReceiverReference to the
          <emphasis role="bold">SourceToken</emphasis> field. A device shall never report this parameter in a 
          RecordingJobConfiguration. A device may reject a request that neither contains a SourceToken nor AutoCreateRecevier set to true.</para>
        <para>
          <emphasis role="bold">SourceTag</emphasis>: If the received RTSP stream contains multiple tracks of the same type, the <emphasis role="bold">SourceTag</emphasis> differentiates between those Tracks.</para>
        <para>
          <emphasis role="bold">Destination</emphasis>: The destination is the track token of the track to which the device shall store the received data. All tracks must belong to the recording identified by the RecordingToken.</para>
        <para>The TrackInformation field for a Track holds a single Source. In case multiple RecordingJobs with differing Source are recording to the same Track it is undefined which of them is reported in the corresponding TrackInformation of the the RecordingSearch API.</para>
      </section>
      <section>
        <title>Event recording</title>
        <para>A device signalling support for EventRecording via its capabilities shall support
          controling recording job activity via the EventFilter with the following set of
          parameters: 
          </para>
        <variablelist>
          <varlistentry>
            <term>Filter</term>
            <listitem>
              <para>One or more filter pairs containing a mandatory topic filter as defined in section 9.6.3 of the ONVIF Core Specification. It may be associated with an optional message content filter as defined in section 9.4.4 of the ONVIF Core
                Specification. </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Before</term>
            <listitem>
              <para>Optional timespan to record before the actual event condition became active.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>After</term>
            <listitem>
              <para>Optional timespan to record after the actual event condition becomes
                inactive.</para>
            </listitem>
          </varlistentry>
        </variablelist>
        <para>A device shall support filtering on topics and message source parameters. Filtering on message data values doesn't need to be supported since it may cause malfunctions.</para>
        <para>A device shall support Before and After durations when their limit is signalled via
          the respective capability. A device may adapt the Before and After duration values to internal
          quantization. </para>
        <para>A device shall at least record the event duration and the specified before and after
          timesspans. Due to the nature of GOP structures it may record more.</para>
        <para>Note that non-property events result in an infinite short timespan. In such cases at least one I-Frame shall be recorded, optionally
          extended by before and after timespans. </para>
        <para>A recording job of a device supporting both EventFilter and ScheduledRecording shall
          become active if both conditions are met.</para>
      </section>
    </section>
    <section>
      <title>CreateRecording</title>
      <para>CreateRecording shall create a new recording.</para>
      <para>This method is optional. It shall be available if the Recording/DynamicRecordings capability is TRUE.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingConfiguration [tt:RecordingConfiguration]</para>
            <para role="text">Contains the initial configuration for the recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="text">The reference to the created recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Receiver - ter:Action - ter:MaxRecordings</para>
            <para role="text">The device cannot create a new recording because it already has the maximum number of recordings that it supports.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
            <para role="text">The RecordConfiguration is invalid.</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">This optional method is not implemented.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>When successfully completed, the device shall have created one or more tracks with the following configurations:</para>
      <table>
        <title>Track configurations</title>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="50*" />
          <colspec colname="c2" colwidth="50*" />
          <tbody valign="top">
            <row>
              <entry>
                <para>
                  <emphasis role="bold">TrackToken</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">TrackType</emphasis>
                </para>
              </entry>
            </row>
            <row>
              <entry>
                <para>VIDEO001</para>
              </entry>
              <entry>
                <para>Video</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>AUDIO001</para>
              </entry>
              <entry>
                <para>Audio</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>META001</para>
              </entry>
              <entry>
                <para>Metadata</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>The RecordingConfiguration shall have the MaximumRetentionTime set to 0 (unlimited) and all TrackConfigurations shall have the Description set to the empty string.</para>
    </section>
    <section>
      <title>DeleteRecording</title>
      <para>DeleteRecording shall delete a recording object. Whenever a recording is deleted, the device shall delete all the tracks that are part of the recording, and it shall delete all the Recording Jobs that record into the recording. For each deleted recording job, the device shall also delete all the receiver objects associated with the recording job that are automatically created using the AutoCreateReceiver field of the recording job configuration structure and are not used in any other recording job.</para>
      <para>This method is optional. It shall be available if the Recording/DynamicRecordings capability is TRUE.</para>
      <para>This method has no effect on the data stored in external targets for e.g. Object Storage
        S3. </para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="text">Identifies the recording that shall be deleted.</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:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">The device cannot delete recordings.</para>
            <para role="param">env:Receiver - ter:Action - ter:CannotDelete</para>
            <para role="text">This specific recording cannot be deleted.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordings</title>
      <para>GetRecordings shall return a description of all the recordings in the device. This description shall include a list of all the tracks for each recording.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">RecordingItem – optional, unbounded [tt:GetRecordingsResponseItem]</para>
            <para role="text">Identifies a recording and its current configuration</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">None</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>SetRecordingConfiguration</title>
      <para>SetRecordingConfiguration shall change the configuration of a recording</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [RecordingToken ]</para>
            <para role="text">Identifies the recording that shall be changed.</para>
            <para role="param">RecordingConfiguration [RecordingConfiguration]</para>
            <para role="text">The new configuration for the recording.</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: BadConfiguration</para>
            <para role="text">The configuration is invalid.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordingConfiguration</title>
      <para>GetRecordingConfiguration shall retrieve the recording configuration for a recording</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="text">Identifies the recording for which the configuration shall be retrieved.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">RecordingConfiguration [tt:RecordingConfiguration]</para>
            <para role="text">The current configuration for the requested recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>CreateTrack</title>
      <para>This method shall create a new track within a recording if the method GetRecordingOptions signals spare tracks for the recording. For a track to be created the SpareXXX (where XXX is the track type) needs to be set.</para>
      <para>This method is optional. It shall be available if the Recording/DynamicTracks capability is TRUE.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="text">Identifies the recording to which a track shall be added.</para>
            <para role="param">TrackConfiguration [tt:TrackConfiguration]</para>
            <para role="text">The configuration for the new track.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">TrackToken [tt:TrackReference]</para>
            <para role="text">Identifies the newly created track. A device shall ensure that the TrackToken is unique within the recoding to which the new track belongs.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
            <para role="param">env:Receiver - ter:Action - ter:MaxTracks</para>
            <para role="text">The new track cannot be created because the maximum number of tracks that the device supports for this recording has been reached.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
            <para role="text">The TrackConfiguration is invalid.</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">This optional method is not implemented.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>A TrackToken in itself does not uniquely identify a specific track. Tracks within different recordings may have the same TrackToken.</para>
    </section>
    <section>
      <title>DeleteTrack</title>
      <para>DeleteTrack shall remove a track from a recording. All the data in the track shall be deleted.</para>
      <para>This method is optional. It shall be available if the Recording/DynamicTracks capability is TRUE.</para>
      <para>This method has no effect on the data stored in external targets for e.g. Object Storage
        S3. </para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference ]</para>
            <para role="text">Identifies the recording from which to delete the track.</para>
            <para role="param">TrackToken [tt:TrackReference]</para>
            <para role="text">Identifies the track to delete.</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:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoTrack</para>
            <para role="text">The TrackToken does not reference an existing track of the recording.</para>
            <para role="param">env:Receiver - ter:Action - ter:CannotDelete</para>
            <para role="text">This specific track cannot be deleted.</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">This optional method is not implemented.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetTrackConfiguration</title>
      <para>GetTrackConfiguration shall retrieve the configuration for a specific track.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference ]</para>
            <para role="text">Identifies the recording.</para>
            <para role="param">TrackToken [tt:TrackReference]</para>
            <para role="text">Identifies the track within the recording from which to get the track configuration</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">TrackConfiguration [tt:TrackConfiguration]</para>
            <para role="text">The current configuration for the track.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoTrack</para>
            <para role="text">The TrackToken does not reference an existing track of the recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>SetTrackConfiguration</title>
      <para>SetTrackConfiguration shall change the configuration of a track. TrackType shall be ignored by the device as it can’t be changed. The TrackConfiguration is the new configuration for the track.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference ]</para>
            <para role="text">Identifies the recording.</para>
            <para role="param">TrackToken [tt:TrackReference]</para>
            <para role="text">Identifies the recording within the recording from which to set the track configuration</para>
            <para role="param">TrackConfiguration [tt:TrackConfiguration]</para>
            <para role="text">The new configurartion for the track.</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:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoTrack</para>
            <para role="text">The TrackToken does not reference an existing track of the recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
            <para role="text">The contents of the configuration object are invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>CreateRecordingJob</title>
      <para>CreateRecordingJob shall create a new recording job. A device shall support adding a RecordingJob to a recording for which it signals Spare jobs via GetRecordingOptions.</para>
      <para>A device should reject a configuration that neither includes a source with a source token nor AutoCreateReceiver set to true.</para>
      <para>If the configuration doesn not include any tracks a device should assign all tracks of the corresponding recording.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobConfiguration [tt:RecordingJobConfiguration]</para>
            <para role="text">The configuration of the new recording job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference ]</para>
            <para role="text">Identifies the created recording job.</para>
            <para role="param">JobConfiguration [tt:RecordingJobConfiguration]</para>
            <para role="text">The configuration as it used by the device. This may be different from the JobConfiguration passed to CreateRecordingJob.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken given in the JobConfiguration does not reference an existing recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
            <para role="text">The contents of the JobConfiguration are invalid.</para>
            <para role="param">env:Receiver - ter:Action - ter:MaxRecordingJobs</para>
            <para role="text">The maximum number of recording jobs that the device can handle has been reached.</para>
            <para role="param">env:Receiver - ter:Action - ter:MaxReceivers</para>
            <para role="text">If the AutoCreateReceivers flag is TRUE, this error can be returned if the receiver service cannot create a new receiver.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>If a request with AutoCreateReceiver is accepted the response shall provide the attached
        receiver token and the AutoCreateReceiver field shall be omitted.</para>
      <para>The device response shall include the complete JobConfiguration including the associated
        job token and the resulting recording track configuration.</para>
    </section>
    <section xml:id="_Toc246137491">
      <title>DeleteRecordingJob</title>
      <para>DeleteRecordingJob removes a recording job. It shall also implicitly delete all the receiver objects associated with the recording job that are automatically created using the AutoCreateReceiver field of the recording job configuration structure and are not used in any other recording job.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference]</para>
            <para role="text">Identifies the recording job that shall be deleted.</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:NoRecordingJob</para>
            <para role="text">The JobToken does not reference an existing job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordingJobs</title>
      <para>GetRecordingJobs shall return a list of all the recording jobs in the device.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">JobItem– optional, unbounded [tt:GetRecordingJobsResponseItem]</para>
            <para role="text">Identifies a job in the device and holds its current configuration.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">None</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>SetRecordingJobConfiguration</title>
      <para>SetRecordingJobConfiguration shall change the configuration for a recording job. A device shall reject a request that tries to modify the RecordingToken.</para>
      <para>The JobConfiguration returned from SetRecordingJobConfiguration by a device shall be identical to the JobConfiguration passed into SetRecordingJobConfiguration, except for the ReceiverToken and the AutoCreateReceiver. In the returned structure, the ReceiverToken shall be present and valid and the AutoCreateReceiver field shall be omitted.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference]</para>
            <para role="text">Identifies the recording job to update.</para>
            <para role="param">JobConfiguration [tt:RecordingJobConfiguration ]</para>
            <para role="text">The configuration to apply to the recording job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">JobConfiguration [tt:RecordingJobConfiguration ]</para>
            <para role="text">The JobConfiguration structure shall be the configuration as it is used by the device. This may be different from the JobConfiguration passed to SetRecordingJobConfiguration.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecordingJob</para>
            <para role="text">The JobToken does not reference an existing job.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
            <para role="text">The contents of the JobConfiguration are invalid.</para>
            <para role="param">env:Receiver - ter:Action - ter:MaxReceivers</para>
            <para role="text">If the AutoCreateReceivers flag is TRUE, this error can be returned if the receiver service cannot create a new receiver.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>SetRecordingJobConfiguration shall implicitly delete any receiver objects that were created automatically if they are no longer used as a result of changing the recording job configuration.</para>
    </section>
    <section>
      <title>GetRecordingJobConfiguration</title>
      <para>GetRecordingJobConfiguration shall return the current configuration for a recording job.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference]</para>
            <para role="text">Identifies the recording job for which to retrieve the configuration.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">JobConfiguration [tt:RecordingJobConfiguration}</para>
            <para role="text">The current configuration of the recording job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecordingJob</para>
            <para role="text">The JobToken does not reference an existing job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>SetRecordingJobMode</title>
      <para>SetRecordingJobMode shall change the mode of the recording job. Using this method shall be equivalent to retrieving the recording job configuration, and writing it back with a different mode.</para>
      <para>Note that the state of a recording job will only become active if the recording job has the highest priority of all active jobs of a recording.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference]</para>
            <para role="text">Identifies the recording job for which to change the recording mode.</para>
            <para role="param">
              <phrase>Mode [tt:</phrase>RecordingJobMode]</para>
            <para role="text">The new mode for the recording job.</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:NoRecordingJob</para>
            <para role="text">The JobToken does not reference an existing job.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadMode</para>
            <para role="text">The Mode is invalid.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetRecordingJobState</title>
      <para>GetRecordingJobState returns the state of a recording job. It includes an aggregated state, and state for each track of the recording job. The RecordingJogState may change due to</para>
      <itemizedlist>
        <listitem>
          <para>calls that effect the RecordingJobMode, e.g. SetRecordingJobMode,</para>
        </listitem>
        <listitem>
          <para>internal recording engine state changes,</para>
        </listitem>
        <listitem>
          <para>changes in the recorded local media profile or</para>
          <itemizedlist>
            <listitem>
              <para>changes to the RTSP connection defined by the associated Receiver.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">JobToken [tt:RecordingJobReference]</para>
            <para role="text">Identifies the recording job for which to get the state.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">State [tt:RecordingJobReference]</para>
            <para role="text">The state of the recording job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecordingJob</para>
            <para role="text">The JobToken does not reference an existing job.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The UML representation of the RecordingJobStateInformation structure is:</para>
      <figure>
        <title>RecordingToken shall be the identification of the recording that the recording job records to.</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/image4.svg" contentwidth="42.31mm" contentdepth="75.62mm" />
          </imageobject>
        </mediaobject>
      </figure>
      <para>
        <emphasis role="bold">State</emphasis> (as part of RecordingJobStateInformation) shall hold the aggregated state over the whole RecordingJobInformation structure.</para>
      <para>
        <emphasis role="bold">SourceToken</emphasis> shall identify the data source of the recording job.</para>
      <para>
        <emphasis role="bold">State</emphasis> (as part of RecordingJobStateSource) shall hold the aggregated state over all substructures of RecordingJobStateSource.</para>
      <para>
        <emphasis role="bold">SourceTag</emphasis> shall identify the track of the data source that provides the data.</para>
      <para>
        <emphasis role="bold">Destination</emphasis> shall indicate the destination track</para>
      <para>
        <emphasis role="bold">State</emphasis> (as part of RecordingJobTrackState) shall provide the job state of the track. The valid values of state shall be “Idle”, “Active” and “Error”. If state equals “Error”, the Error field may be filled in with an implementation defined value.</para>
      <para>
        <emphasis role="bold">Error</emphasis>, optional string describing the error state. The string should be in English. The following values are predefined:</para>
      <para>
        <emphasis role="bold">“Incompatible Stream”</emphasis> – The stream cannot be recorded because the encoding does not match to previously recorded data.</para>
      <para>A device shall apply the following rules to compute aggregate state</para>
      <table>
        <title>state rules</title>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="21*" />
          <colspec colname="c2" colwidth="79*" />
          <tbody valign="top">
            <row>
              <entry>
                <para>Idle</para>
              </entry>
              <entry>
                <para>All state values in sub-nodes are “idle”</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>PartiallyActive</para>
              </entry>
              <entry>
                <para>The state of some sub-nodes are “active” and some sub-nodes are “idle”</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Active</para>
              </entry>
              <entry>
                <para>The state of all sub-nodes is “Active”</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Error</para>
              </entry>
              <entry>
                <para>At least one of the sub-nodes has state “Error”</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <section>
      <title>GetRecordingOptions</title>
      <para>GetRecordingOptions returns information for a recording identified by the RecordingToken. The information includes the number of additional tracks as well as recording jobs that can be configured.</para>
      <para>This method shall be supported if the Options support is signaled via the capabilities.</para>
      <para>Note that this information is not static and is only guaranteed to be valid until the next modification of any recording jobs or tracks.</para>
      <para>The track options shall be supported if the device signals support for dynamic tracks.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="text">Identifies the recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">JobOptions [trc:JobOptions ]</para>
            <para role="text">Contains two attributes:</para>
            <para role="text">Spare: Number of spare jobs that can be created for the recording. By setting none of
              the Spare attribute the device signals that no job can be created.</para>
            <para role="text">CompatibleSources: A device that supports recording of a restricted set of
              Media/Media2 Service Profiles shall return the list of profiles that can be recorded on
              the given Recording.
            </para>
            <para role="param">TrackOptions [trc:TrackOptions]</para>
            <para role="text">Contains four attributes:</para>
            <para role="text">SpareTotal: Total spare number of tracks that can be added to this recording.</para>
              <para role="text">SpareVideo: Number of spare video tracks for this recording</para>
            <para role="text">SpareAudio: Number of spare audio tracks for this recording</para>
            <para role="text">SpareMetadata: Number of spare metadata tracks for this recording</para>
            <para role="text">By setting none of the spare attributes the device signals that no
              track can be added.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:NoRecording</para>
            <para role="text">The RecordingToken does not reference an existing recording.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>ExportRecordedData</title>
      <para>ExportRecordedData exports the selected recordings to the given storage target.</para>
      <para>A device that indicates a capability of SupportedExportFileFormats shall support this command. For the parameter FileFormat it shall accept any format that it advertises via the SupportedExportFileFormats capability.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">StartPoint – optional [xs:dateTime]</para>
            <para role="text">Specifies start time for the exporting.</para>
            <para role="param">EndPoint – optional [xs:dateTime]</para>
            <para role="text">Specifies end time for the exporting.</para>
            <para role="param">SearchScope [tt:SearchScope]</para>
            <para role="text">Defines the selection criterion for the existing recordings.</para>
            <para role="param">FileFormat [xs:string]</para>
            <para role="text">Indicates which export file format to be used.</para>
            <para role="param">StorageDestination [tt:StorageReferencePath]</para>
            <para role="text">Indicates the target storage and relative directory path.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken}</para>
            <para role="text">The asynchronous operation token for associating the received event with this invocation.</para>
            <para role="param">FileNames - optional, unbounded [xs:string]</para>
            <para role="text">List of exported file names. A client can also use AsyncronousOperationStatus event to monitor the progress of ExportRecordedData operation.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadConfiguration:</para>
            <para role="text">The device cannot support the selected FileFormat for exported files.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>A device should return the resulting list of file names in the response. In cases where the retrieval of the file names is a longer lasting operation these file names may be reported only via the AsyncronousOperationStatus.</para>
      <para>The ExportRecordedDataResponse returns the unique operation token that is used by client to monitor the progress of this invocation. The progress of export recordings operation is obtained via an event (Core Spec, Monitoring/AsynchronousOperationStatus). A device can notify progress of exported files via optional FileProgressStatus (tt:ArrayOfFileProgress) element, containining an array of file name and completion percentage of file upload from device’s point of view. The value of completion percentage is normalized between 0.0 and 1.0 where 1.0 indicates 100% completion of file upload. The optional FileProgressStatus elemet is sent in Data section of a Message.</para>
      <para>If a delete recording request is issued during an export of recordings and there are common recordings, the device shall delete the relevant recording after completing the export of these relavant recordings.</para>
    </section>
    <section>
      <title>StopExportRecordedData</title>
      <para>Stops the ExportRecordedData operation that is started before. The response message lists the status of the exported files.</para>
      <para>A device that indicates a capability of SupportedExportFileFormats shall support this command.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken]</para>
            <para role="text">Identifies the ExportRecordedData operation to stop.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Progress [xs:float]</para>
            <para role="text">Completion percentage of total file upload from device’s point of view. The value of completion percentage is normalized between 0.0 and 1.0 where 1.0 indicates 100% completion of total file upload.</para>
            <para role="param">FileProgressStatus [tt:ArrayOfFileProgress]</para>
            <para role="text">An array of file names and an individual progress for each file. The value of completion percentage is normalized between 0.0 and 1.0 where 1.0 indicates 100% completion of the file upload.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The requested operation does not exist.</para>
    </section>
    <section>
      <title>GetExportRecordedDataState</title>
      <para>GetExportRecordedDataState returns the status of export operations. This interface allows client to poll the status information from the device.</para>
      <para>A device that indicates a capability of SupportedExportFileFormats shall support this command.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken]</para>
            <para role="text">Identifies the ExportRecordedData operation from which to get status.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Progress [xs:float]</para>
            <para role="text">Completion percentage of total file upload from device’s point of view. The value of completion percentage is normalized between 0.0 and 1.0 where 1.0 indicates 100% completion of total file upload.</para>
            <para role="param">FileProgressStatus [tt:ArrayOfFileProgress]</para>
            <para role="text">An array of file names and an individual progress for each file. The value of completion percentage is normalized between 0.0 and 1.0 where 1.0 indicates 100% completion of the file upload.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">env:Sender - ter:InvalidArgVal - ter:BadConfiguration</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The requested operation does not exist.</para>
    </section>
    <section>
      <title>OverrideSegmentDuration</title>
      <para>OverrideSegmentDuration dynamically updates a RecordingConfiguration to produce smaller
        recording segments for a limited time. This allows for a client to request faster access to recorded data while
        reducing the overall storage costs during normal operation.
      </para>
      <para>
        When the temporary override is active, the device should attempt to close its currently recording segment and then
        shall record further segments with the new duration provided in this command. The override shall be active for the
        duration specified in the command, once the command expires the device shall resume recording with the original segment
        duration on its next segment. The override duration shall not exceed 1 hour.
      </para>
      <para>
        When a new override request is sent before the previous override has expired, the new override shall replace the 
        previous override and the new expiration shall apply.
      </para>
      <para>
        The active override value, if any exists, shall be shown in the corresponding <literal>RecordingConfiguration</literal> and may not persist after a device restart.
        If the recording configuration is modified while an override is active, the override shall be removed.
      </para>
      <para>
        A device that indicates support for OverrideSegmentDuration shall support this command.
      </para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">TargetSegmentDuration [xs:duration]</para>
            <para role="text">The new segment duration to be used for the duration of the override request.</para>
            <para role="param">Expiration [xs:duration]</para>
            <para role="text">The duration for which the override request shall be active.</para>
            <para role="param">RecordingConfiguration [tt:RecordingReference]</para>
            <para role="text">The recording configuration that needs to use the new segment duration.</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:NoRecording</para>
            <para role="text">The RecordingConfiguration does not reference an existing recording.</para>
            <para role="param">env:Sender - ter:InvalidArgVal - ter:BadDuration</para>
            <para role="text">The value of the duration parameter is invalid.</para>
            <para role="param">env:Receiver - ter:ActionNotSupported - ter:NotImplemented</para>
            <para role="text">This optional method is not implemented.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">ACTUATE</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <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>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Capabilities [trc:Capabilities]</para>
            <para role="text">List of capabilities as defined below.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>faults</term>
          <listitem>
            <para role="text">None</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">PRE_AUTH</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following capabilities are available:</para>
      <variablelist>
        <varlistentry>
          <term>DynamicRecordings</term>
          <listitem><para>Indication if the device supports dynamic creation and deletion of recordings. </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>DynamicTracks</term>
          <listitem><para>Indication if the device supports dynamic creation and deletion of tracks. </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Encoding</term>
          <listitem><para>Indication which encodings are supported for recording. The list may contain
            one or more enumeration values of tt:VideoEncoding and tt:AudioEncoding. For encodings that
            are neither defined in tt:VideoEncoding nor tt:AudioEncoding the device shall use the IANA
            defintions http://www.iana.org/assignments/media-types/media-types.xhtml. Note, that a
            device without audio support shall not return audio encodings.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>MaxRate</term>
          <listitem><para>Maximum supported bit rate for all tracks of a recording in kBit/s.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>MaxTotalRate</term>
          <listitem><para>Maximum supported bit rate for all recordings in kBit/s.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>MaxRecordings</term>
          <listitem><para>Maximum number of recordings supported.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>MaxRecordingJobs</term>
          <listitem><para>Maximum total number of supported recording jobs by the device.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>Options</term>
          <listitem><para>Indication if the device supports the GetRecordingOptions command.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>MetadataRecording</term>
          <listitem><para>Indication if the device supports recording metadata.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>SupportedExportFileFormats</term>
          <listitem><para>Indication that the device supports ExportRecordedData
            command for the listed export file formats. A device shall ony return this capability if it
            contains at least one export file format value. The value of ‘ONVIF’ refers to ONVIF Export
            File Format Specification.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>ScheduledRecording</term>
          <listitem><para>Indication that the device supports scheduled recording.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>EventRecording</term>
          <listitem><para>Indication that the device supports event triggered recording.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>BeforeEventLimit</term>
          <listitem><para>Indicates that the device supports before event durations up to the given value.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>AfterEventLimit</term>
          <listitem><para>Indicates that the device supports after event durations up to the given value.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>SupportedTargetFormats</term>
          <listitem>
            <para>
              List of formats supported by the device for recording to an external target.
              See tt:TargetFormat for a list of definitions.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>EncryptionEntryLimit</term>
          <listitem>
            <para>
              Number of encryption entries supported per recording.
              By specifying multiple encryption entries per recording, different tracks can be encrypted with different configurations.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>SupportedEncryptionModes</term>
          <listitem>
            <para>
              Supported encryption modes.
              See tt:EncryptionMode for a list of definitions.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>OverrideSegmentDurationSupported</term>
          <listitem>
            <para>Indicates that the device supports the OverrideSegmentDuration command.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>ListRecordedSegments</title>
      <para>Lists available recorded segments related to the specified RecordingToken.</para>
      <para>
        The device shall provide results in StartTime ascending order.
        The device can decide to send less results if it needs to. 
        The device shall indicate if there are more segments available in the time range by having the HasMoreResults field set to True.
      </para>
      <para>
        When the HasMoreResults field is set to True in the response, the client shall adapt its next query by changing the From field
        to the last EndTime received from the previous request. The client should continue until the HasMoreResults field is set to False.
      </para>
      <para>The listed segments shall have a stable start and end time as defined in Annex Stable Recordings.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">Time [tt:DateTimeRange]</para>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="param">MaxResults - optional [xs:int]</para>
            <para role="text">The maximum number of results to return in one response.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Segment</para>
            <para role="text">Contains a collection of segments with some basic metadata associated with the recording.</para>
            <para role="param">HasMoreResults [xs:boolean]</para>
            <para role="text">A flag indicating that more segments are available in the specified time range.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>ExportRecordedSegments</title>
      <para>Exports the selected recorded segments (from existing recorded data) to the storage attached to the given recording job.</para>
      <para>The StoragePath shall be the path as defined in the Object Storage annex appended to the StorageUri from the StorageConfiguration.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">Time [tt:DateTimeRange]</para>
            <para role="param">RecordingToken [tt:RecordingReference]</para>
            <para role="param">StorageToken - optional [tt:ReferenceToken]</para>
            <para role="text">If provided, overrides the Target's storage configuration.</para>
            <para role="param">Track - optional [tt:TrackType]</para>
            <para role="text">An optional field if specified indicates which track is to be exported.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken]</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GetExportRecordedSegmentState</title>
      <para>Retrieves the status of selected ExportRecordedSegments operation.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken]</para>
            <para role="param">StartTime [xs:dateTime]</para>
            <para role="text">The start index for the segment results.</para>
            <para role="param">MaxResults - optional [xs:int]</para>
            <para role="text">The maximum number of segment results to be provided in the response.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="param">Segment [tt:UploadSegmentResult]</para>
            <para role="param">HasMoreSegments [xs:boolean]</para>
            <para role="text">A value indicating that the export has reached the maximum count and a new request must be sent to query the export state of further segments.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>StopExportRecordedSegments</title>
      <para>Stops the selected ExportRecordedSegments operation.</para>
      <variablelist role="op">
        <varlistentry>
          <term>request</term>
          <listitem>
            <para role="param">OperationToken [tt:ReferenceToken]</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>response</term>
          <listitem>
            <para role="text">This is an empty message.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>access class</term>
          <listitem>
            <para role="access">READ_MEDIA</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
    <section>
      <title>Events</title>
      <para>Some of these events are similar to the automatically generated events that can be searched for by the FindEvents method in the search service. See ONVIF Recording Search Service Specification.</para>
      <section>
        <title>Recording job state changes</title>
        <para>If the state field of the RecordingJobStateInformation structure changes, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>JobState</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="true"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingJobToken" Type="tt:RecordingJobReference"/> 
  </tt:Source> 
  <tt:Data> 
    <tt:SimpleItemDescription Name="State" Type="xs:String"/> 
    <tt:ElementItemDescription Name="Information" Type="tt:RecordingJobStateInformation"/> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
        <para>The ElementItem Information shall be provided whenever the state of the different tracks is not unique. It can be omitted when the state of all tracks of a recording is consistent.</para>
</section>
      <section>
        <title>Configuration changes</title>
        <para>If the configuration of a recording is changed, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>RecordingConfiguration</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
  </tt:Source> 
  <tt:Data> 
    <tt:ElementItemDescription Name="Configuration" Type="tt:RecordingConfiguration"/> 
  </tt:Data> 
</tt:MessageDescription>]]></programlisting>
        <para>If the configuration of a track is changed, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>TrackConfiguration</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
    <tt:SimpleItemDescription Name="TrackToken" Type="tt:TrackReference"/> 
  </tt:Source> 
  <tt:Data> 
    <tt:ElementItemDescription Name="Configuration" Type="tt:TrackConfiguration"/> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
        <para>If the configuration of a recording job is changed, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>RecordingJobConfiguration</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingJobToken" Type="tt:RecordingJobReference"/> 
  </tt:Source> 
  <tt:Data> 
    <tt:ElementItemDescription Name="Configuration" Type="tt:RecordingJobConfiguration"/> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
      </section>
      <section>
        <title>Data deletion</title>
        <para>Whenever data is deleted, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>DeleteTrackData</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
    <tt:SimpleItemDescription Name="TrackToken" Type="tt:TrackReference"/> 
  </tt:Source> 
  <tt:Data> 
    <tt:SimpleItemDescription Name="StartTime" Type="xsDateTime"/> 
    <tt:SimpleItemDescription Name="EndTime" Type="xsDateTime"/> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
      </section>
      <section>
        <title>Recording and track creation and deletion</title>
        <para>Whenever a recording is created, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/<phrase>CreateRecording</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
  </tt:Source> 
  <tt:Data> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
        <para>Whenever a recording is deleted, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/Delete<phrase>Recording</phrase></para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
  </tt:Source> 
  <tt:Data> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
        <para>Whenever a track is created, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/CreateTrack</para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
    <tt:SimpleItemDescription Name="TrackToken" Type="tt:TrackReference"/> 
  </tt:Source> 
  <tt:Data> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
        <para>Whenever a track is deleted, a device shall provide the following event:</para>
        <para>Topic: tns1:RecordingConfig/DeleteTrack</para>
        <programlisting><![CDATA[<tt:MessageDescription IsProperty="false"> 
  <tt:Source> 
    <tt:SimpleItemDescription Name="RecordingToken" Type="tt:RecordingReference"/> 
    <tt:SimpleItemDescription Name="TrackToken" Type="tt:TrackReference"/> 
  </tt:Source> 
  <tt:Data> 
  </tt:Data> 
</tt:MessageDescription>
]]></programlisting>
      </section>
    </section>
    <section>
      <title>Examples</title>
      <section>
        <title>Example 1: setup recording of a single camera</title>
        <para>There are two steps involved. The first step is to configure the NVS</para>
        <programlisting><![CDATA[; Create recording (this implicitly creates an A, V and M track)
RecordToken = CreateRecording(RecordConfiguration)

; The tracktokens are predefined. We don’t have to find them on the device
TrackToken1 = “VIDEO001”
TrackToken2 = “AUDIO001”
TrackToken3 = “META001”

; Create a recording job, assume that we set mode to idle, auto create receiver
JobToken, ActualJobConfig = CreateRecordingJob(JobConfiguration)

; Configure the receiver
ConfigureReceiver(ActualJobConfiguration.ReceiverToken, ReceiverConfiguration)
]]></programlisting>
        <para>This completes the configuration step.</para>
        <para>Finally, to really start recording, some entity calls</para>
        <programlisting><![CDATA[; Activate the recording job
SetRecordingJobMode(JobToken, Active)
]]></programlisting>
        <para>to make the job active. This will cause the NVS to set up an RTSP connection with the device.</para>
        <para>Therefore, to start and stop recording, all that is needed is to call SetRecordingJobMode on pre-configured recording jobs. And since the embedded configuration objects are persistent, the configuration cycle only needs to be done once.</para>
      </section>
      <section>
        <title>Example 2: Record multiple streams from one camera to a single recording</title>
        <para>This example is very similar to example 1. The jobconfiguration will hold references to two receiver objects. Each receiver object is configured to receive from the same device, but from a different stream.</para>
        <programlisting><![CDATA[; Create recording (this implicitly creates an A, V and M track)
RecordToken = CreateRecording(RecordConfiguration)

; The tracktokens are predefined. We don’t have to find them on the device
TrackToken1 = “VIDEO001”
TrackToken2 = “AUDIO001”
TrackToken3 = “META001”

; Create three additional tracks
TrackToken4 = CreateTrack(RecordToken, AudioConfig)
TrackToken5 = CreateTrack(RecordToken, VideoConfig)
TrackToken6 = CreateTrack(RecordToken, MetadataConfig)

; Create a recording job, assume that we set mode to idle,auto create two receivers
JobToken, ActualJobConfiguration = CreateRecordingJob(JobConfiguration)

; Configure the receivers
ConfigureReceiver(ActualJobConfiguration.ReceiverToken[1], Receiver1Configuration)
ConfigureReceiver(ActualJobConfiguration.ReceiverToken[2], Receiver2Configuration)
]]></programlisting>
        <para>To really start recording, some entity calls</para>
        <programlisting><![CDATA[; Activate the recording job
SetRecordingJobMode(JobToken, Active)
]]></programlisting>
      </section>
    </section>
  </chapter>
  <appendix>
    <title>Example scenario for Recording Job Priority (Informative)</title>
    <para>This annex describes a scenario for Multiple Recording Jobs configured to record data into a single recording.</para>
    <para>Accordingly, a device supporting Multiple Recording Jobs is required to change the Job Modes of Recording Jobs with respect to Priority, as described below :</para>
    <variablelist>
      <varlistentry>
        <term>Step&#8199;1</term> <!-- inhibit line break -->
        <listitem>
          <para>A Recording Job ‘J1’ with Priority ‘2’ is created in 'Active' mode</para>
          <para>Job State of Recording Jobs after Step 1:</para>
          <para>Recording Job ‘J1’ = ACTIVE</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Step 2</term>
        <listitem>
          <para>A new Recording Job ‘J2’ with Priority ‘4’ is now created in 'IDLE' mode</para>
          <para>Job States of Recording Jobs after Step 2:</para>
          <para>Recording Job ‘J1’ = ACTIVE</para>
          <para>Recording Job ‘J2’ = IDLE</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Step 3</term>
        <listitem>
          <para>Another Recording Job ‘J3’ with higher Priority ‘3’ is now created in 'Active' mode. Because it has a higher priority than J1, it takes precedence.</para>
          <para>Job States of Recording Jobs after Step 3:</para>
          <para>Recording Job ‘J1’ = IDLE</para>
          <para>Recording Job ‘J2’ = IDLE</para>
          <para>Recording Job ‘J3’ = ACTIVE</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Step 4</term>
        <listitem>
          <para>Job States of Recording Jobs after Step 4:</para>
          <para>Recording Job ‘J3’ is now deleted. 'J1' becomes active again since it is the active job with the highest priority.</para>
          <para>Recording Job ‘J1’ = ACTIVE</para>
          <para>Recording Job ‘J2’ = IDLE</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </appendix>
  <appendix xml:id="_refCloudRecording">
    <title>Object storage recording format (Normative)</title>
    <section xml:id="_refCloudRecordingOverview">
      <title>Overview</title>
      <para>
        This annex describes the requirements for recording from a device to an object storage for later use by a receiver.
        The device could be a camera, the receiver could be a video player.
        <xref linkend="_refCloudRecordingDataFlow" /> shows the data flow for object storage recording.
      </para>
      <figure xml:id="_refCloudRecordingDataFlow">
        <title>Data flow for object storage recording</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/cloudRecordingDataFlow.svg" contentwidth="140mm" />
          </imageobject>
        </mediaobject>
      </figure>
      <para>
        The device uploads recorded media as objects containing fragmented MP4 data according to ISO/IEC 14496-12, the ISO base media file format.
        In this annex, a media object containing fragmented MP4 data is called a segment.
        Each segment starts with a header containing initialization data, usually consisting of a <literal>FileTypeBox</literal> and a <literal>MovieBox</literal>.
        Each segment contains one or more fragments with recorded media, usually consisting of a <literal>MovieFragmentBox</literal> and a <literal>MediaDataBox</literal>.
        Each segment contains recorded media of a continuous period of time.
      </para>
      <para>
        Multiple successive segments without a time gap in between form a span.
        In this way, the size of segments can be limited when recording continuously for a longer period of time.
      </para>
      <para>
        For a single span, only a single segment contains recorded media of one point in time.
        Depending on the recording format, video, audio, and metadata are written into separate segments.
        In this case, the segments of each media type form separate spans.
        <xref linkend="_refCloudRecordingLogicalModel" /> shows the logical model for object storage recording.
      </para>
      <figure xml:id="_refCloudRecordingLogicalModel">
        <title>Logical model for object storage recording</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/cloudRecordingLogicalModel.svg" contentwidth="79mm" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
    <section xml:id="_refCloudRecordingSpans">
      <title>Spans</title>
      <para>
        When a recording is activated, the device shall open new spans for this recording according to the rules of the configured <literal>Format</literal>.
        Inversely, when a recording is deactivated, the device shall close all open spans of this recording.
        When a <literal>SpanDuration</literal> is configured for a recording, the recording is active, and the duration of a span of this recording reaches the configured <literal>SpanDuration</literal>, the device shall close all open spans of the recording and open new spans according to the rules of the configured <literal>Format</literal>.
      </para>
      <para>
        All fragments of a span shall be independently processable and presentable with the information of a <literal>MovieBox</literal> in any of the segments of the span.
        If the information in the <literal>MovieBox</literal> required to process the fragments needs to change while the recording is active, the device shall close all open spans of the recording and start new spans according to the rules of the configured <literal>Format</literal>.
      </para>
    </section>
    <section xml:id="_refCloudRecordingSegments">
      <title>Segments</title>
      <para> When a span is opened, the device shall also open a new segment for this span.
        Inversely, when a span is closed, the device shall close the open segment of this span. When
        a span is open and the duration of the open segment of this span reaches the
          <literal>SegmentDuration</literal> configured for the recording, the device shall close
        the open segment of this span and open a new segment for this span. When closing the open
        segment of a span and opening a new segment for this span, there shall be no time gap
        between the two segments. Note that the actual segment duration may vary and can be plus or 
		minus one GOP size from the configured duration because a segment must start with an I-Frame.</para>
      <para>
        The device shall generate each segment as a fragmented MP4 file according to ISO/IEC 14496-12, the ISO base media file format.
        A segment shall contain recorded media for the time it was open.
        The recording formats provide specification about segment types, their contents, and restrictions on the ISO base media file format in the following sections.
      </para>
    </section>
    <section xml:id="_refCloudRecordingSegmentObjects">
      <title>Segment objects</title>
      <para>
        The device shall upload each segment as one object, identified by its object key, to the object storage.
        The device shall generate the object key for a segment according to the following ABNF <literal>key</literal> rule (according to RFC 5234):
      </para>
      <programlisting>key      = lead "/" time "." counter "." extension
lead    = [prefix "/"] date ["/" postfix]
counter = 1*DIGIT
date    = year "-" month "-" day
time    = hour "/" minute "-" second [secfrac] "Z"
year    = 4DIGIT
month   = 2DIGIT ; 01-12
day     = 2DIGIT ; 01-31
hour    = 2DIGIT ; 00-23
minute  = 2DIGIT ; 00-59
second  = 2DIGIT ; 00-60 (due to leap second rules)
secfrac = "." 1*6DIGIT</programlisting>
      <para>
        If a <literal>Prefix</literal> is configured for the recording, the device shall include <literal>prefix</literal> in <literal>lead</literal> and replace it with the configured <literal>Prefix</literal>.
        If a <literal>Postfix</literal> is configured for the recording, the device shall include <literal>postfix</literal> in <literal>lead</literal> and replace it with the configured <literal>Postfix</literal>.
        The device shall replace <literal>date</literal> and <literal>time</literal> respectively with the date and time portion of the first sample contained in the segment in Universal Coordinated Time (UTC), following the ABNF rules:
        <itemizedlist>
          <listitem>
            <para><literal>year</literal> represents the 4-digit year</para>
          </listitem>
          <listitem>
            <para><literal>month</literal> represents the 2-digit month (01 to 12)</para>
          </listitem>
          <listitem>
            <para><literal>day</literal> represents the 2-digit day of the month (01 to 31)</para>
          </listitem>
          <listitem>
            <para><literal>hour</literal> represents the 2-digit hour (00 to 23)</para>
          </listitem>
          <listitem>
            <para><literal>minute</literal> represents the 2-digit minute (00 to 59)</para>
          </listitem>
          <listitem>
            <para><literal>second</literal> represents the 2-digit second (00 to 60, due to leap second rules)</para>
          </listitem>
          <listitem>
            <para><literal>secfrac</literal> represents the optional fractional seconds with a precision of up to 6 digits</para>
          </listitem>
        </itemizedlist>
        The device shall replace <literal>counter</literal> with a span-dependant counter set to 0 for a new span and incremented by 1 when closing a segment of this span.
        The device shall replace <literal>extension</literal> with the extension defined by the type of span the segment belongs to.
      </para>
      <para>
        Note: <literal>date</literal> is conformant to the extended date format defined in ISO 8601-1.
        <literal>time</literal> is <emphasis role="bold">not</emphasis> conformant to the extended time format defined in ISO 8601-1.
      </para>
    </section>
    <section xml:id="_refCloudRecordingSpanEndObjects">
      <title>Span end objects</title>
      <para>
        To store the end time of a span, the device should store an additional empty object when closing a span.
        The device shall generate the object key for this object according to the ABNF <literal>key</literal> rule and replacement rules defined in <xref linkend="_refCloudRecordingSegmentObjects" />.
        The device shall replace <literal>date</literal> and <literal>time</literal> respectively with the date and time portion of the end of the last sample contained in the span in Universal Coordinated Time (UTC), following the ABNF rules.
        The device shall replace <literal>counter</literal> by a value equal to the counter of the last segment of the span plus 1.
        The device shall replace <literal>extension</literal> according to the following ABNF <literal>extension</literal> rule (according to RFC 5234):
      </para>
      <programlisting>extension = span-extension "_end"</programlisting>
      <para>
        The device shall replace <literal>span-extension</literal> with the extension defined by the span type.
      </para>
    </section>
    <section xml:id="_refCloudRecordingRecordingFormatMP4">
      <title>Recording format MP4</title>
      <para>
        If the <literal>Format</literal> configured for a recording is <literal>MP4</literal>, the device shall follow the rules given in this section.
      </para>
      <para>
        The device shall open a single span for an active recording containing all tracks of the recording.
        The device shall use <literal>mp4</literal> as the extension for this span type.
        The device shall upload each segment object belonging to a span of this type with the content type <literal>video/mp4</literal>.
        The device should include the <literal>codecs</literal> parameter in the content type according to RFC 6381.
      </para>
      <para>
        The <literal>MovieBox</literal> contained in a segment shall not reference any samples.
        A segment shall contain a <literal>MovieFragmentRandomAccessBox</literal> as the last box.
        The <literal>MovieFragmentRandomAccessBox</literal> shall provide references for all tracks and their applicable <literal>MovieFragmentBox</literal> instances.
      </para>
    </section>
    <section xml:id="_refCloudRecordingRecordingFormatCMAF">
      <title>Recording format CMAF</title>
      <para>
        If the <literal>Format</literal> configured for a recording is <literal>CMAF</literal>, the device shall follow the rules given in this section.
      </para>
      <para>
        The device shall open up to three spans for an active recording, each containing a single track of the recording.
      </para>
      <para>
        If the recording contains a video track, the device shall open a video span containing this track.
        The device shall use <literal>m4v</literal> as the extension for this span type.
        The device shall upload each segment object belonging to a span of this type with the content type <literal>video/mp4</literal>.
      </para>
      <para>
        If the recording contains an audio track, the device shall open an audio span containing this track.
        The device shall use <literal>m4a</literal> as the extension for this span type.
        The device shall upload each segment object belonging to a span of this type with the content type <literal>audio/mp4</literal>.
      </para>
      <para>
        If the recording contains a metadata track, the device shall open a metadata span containing this track.
        The device shall use <literal>m4m</literal> as the extension for this span type.
        The device shall upload each segment object belonging to a span of this type with the content type <literal>application/mp4</literal>.
      </para>
      <para>
        The device should include the <literal>codecs</literal> parameter in the content type according to RFC 6381 for all span types defined in this section.
      </para>
      <para>
        The device shall generate each segment according to ISO/IEC 23000-19, the common media application format (CMAF) for segmented media, with one CMAF header and one or more CMAF fragments.
        A segment may contain a <literal>MovieFragmentRandomAccessBox</literal> as the last box.
        If a segment contains a <literal>MovieFragmentRandomAccessBox</literal>, every CMAF fragment shall be referenced in the <literal>MovieFragmentRandomAccessBox</literal>.
      </para>
      <para>
        Note: As the different tracks are contained in different spans, the segments do not necessarily align.
        This is illustrated in <xref linkend="_refCloudRecordingCMAFSegments" />.
      </para>
      <figure xml:id="_refCloudRecordingCMAFSegments">
        <title>Alignment of different segment types</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/cloudRecordingCMAFSegments.svg" contentwidth="104mm" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
    <section xml:id="_refCloudRecordingEncryption">
      <title>Encryption</title>
      <para>
        A device signaling support for recording to an external target with encryption shall support writing encrypted files according to ISO/IEC 23001-7 (common encryption in ISO base media file format files).
        Each <literal>Encryption</literal> entry configured for a recording covers a distinct set of tracks for which to apply the encryption, identified by the <literal>Track</literal> element.
        If an encryption entry contains no <literal>Track</literal> elements, it covers all tracks of the recording.
        If an encryption entry contains one or more <literal>Track</literal> elements, it covers the tracks indicated by the track tokens contained in these elements.
        The device shall encrypt the covered tracks with the scheme given by the <literal>Mode</literal> configured for the encryption entry:
      </para>
      <para>
        <variablelist>
          <varlistentry>
            <term>CENC</term>
            <listitem>
              <para>
                AES-CTR mode full sample and video NAL Subsample encryption, defined in ISO/IEC 23001-7.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>CBCS</term>
            <listitem>
              <para>
                AES-CBC mode partial video NAL pattern encryption, defined in ISO/IEC 23001-7.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
      <para>
        The device shall create an individual initialization vector for each segment.
        The device shall encrypt with the <literal>Key</literal> configured for the encryption entry as the encryption key.
        The device shall interpret the <literal>KID</literal> configured for the encryption entry as a 16-byte hexadecimal value and use this value as the key identifier.
      </para>
      <para>
        If an encryption entry is reconfigured for an active recording, the device shall continue to use the old configuration for any open segments and shall start to use the new configuration for new segments.
      </para>
    </section>
    <section xml:id="_refCloudRecordingObjectAttributes">
      <title>Object attributes</title>
      <para>
        The device may store additional attributes defined in <xref linkend="_refCloudRecordingObjectAttributesTable" /> as object metadata when uploading segment objects.
      </para>
      <para>
        Note: When sending attributes as metadata HTTP headers, the attribute keys need to be prefixed with a value determined by the type of storage configured for the recording.
        If the storage is of type <literal>ObjectStorageS3</literal>, the attribute keys need to be prefixed with <literal>x-amz-meta-</literal> (for example <literal>x-amz-meta-Version: 1.0</literal>).
        If the storage is of type <literal>ObjectStorageAzure</literal>, the attribute keys need to be prefixed with <literal>x-ms-meta-</literal> (for example <literal>x-ms-meta-Version: 1.0</literal>).
        Audio-related attributes may be stored for segment objects containing only a video track and video-related attributes may be stored for segment objects containing only an audio track.
      </para>
      <table xml:id="_refCloudRecordingObjectAttributesTable">
        <title>Object attributes</title>
        <tgroup cols="3">
          <colspec colwidth="20*" />
          <colspec colwidth="60*" />
          <colspec colwidth="50*" />
          <thead>
            <row>
              <entry>
                <para>Key</para>
              </entry>
              <entry>
                <para>Value</para>
              </entry>
              <entry>
                <para>Format</para>
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
                <para><literal>Version</literal></para>
              </entry>
              <entry>
                <para><literal>1.0</literal></para>
              </entry>
              <entry>
                <para><literal>major "." minor</literal></para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>Source</literal></para>
              </entry>
              <entry>
                <para>Identifier of the physical device</para>
              </entry>
              <entry>
                <para>String</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>EventTopic</literal></para>
              </entry>
              <entry>
                <para>Topic of the event that triggered the recording job</para>
              </entry>
              <entry>
                <para>String</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>Duration</literal></para>
              </entry>
              <entry>
                <para>Duration of the segment</para>
              </entry>
              <entry>
                <para>ISO 8601-1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>FullContentType</literal></para>
              </entry>
              <entry>
                <para>Combined content type of all media types contained in the recording</para>
              </entry>
              <entry>
                <para><literal>video/mp4</literal> content type with <literal>codecs</literal> parameter according to RFC 6381</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>VideoChannel</literal></para>
              </entry>
              <entry>
                <para>Video channel identifier</para>
              </entry>
              <entry>
                <para>String</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>VideoBitrate</literal></para>
              </entry>
              <entry>
                <para>Video bitrate in kilobits per second</para>
              </entry>
              <entry>
                <para>Integer</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>VideoWidth</literal></para>
              </entry>
              <entry>
                <para>Video width in pixels from <literal>VisualSampleEntry</literal></para>
              </entry>
              <entry>
                <para>Integer</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>VideoHeight</literal></para>
              </entry>
              <entry>
                <para>Video height in pixels from <literal>VisualSampleEntry</literal></para>
              </entry>
              <entry>
                <para>Integer</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>VideoFramerate</literal></para>
              </entry>
              <entry>
                <para>Average video framerate in frames per second</para>
              </entry>
              <entry>
                <para>Float</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>AudioChannel</literal></para>
              </entry>
              <entry>
                <para>Audio channel identifier</para>
              </entry>
              <entry>
                <para>String</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>AudioBitrate</literal></para>
              </entry>
              <entry>
                <para>Audio bitrate in kilobits per second</para>
              </entry>
              <entry>
                <para>Integer</para>
              </entry>
            </row>
            <row>
              <entry>
                <para><literal>AudioSampleRate</literal></para>
              </entry>
              <entry>
                <para>Audio sample rate in kilohertz</para>
              </entry>
              <entry>
                <para>Integer</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>For storage target systems that do not allow attribute changes during write the
        attribute Duration should be omitted when the total duration of the file may change while it
        is written e.g. due to an override segment duration request.</para>
    </section>
    <section xml:id="_refCloudRecordingObjectExamples">
      <title>Examples</title>
      <para>
        Given the following storage configuration in a recording configuration:
      </para>
      <programlisting><![CDATA[<tt:Target>
  <tt:Storage>1</tt:Storage>
  <tt:Format>MP4</tt:Format>
  <tt:Prefix>site-2</tt:Prefix>
  <tt:Postfix>camera-5</tt:Postfix>
  <tt:SegmentDuration>PT60S</tt:SegmentDuration>
</tt:Target>]]></programlisting>
      <para>
        The key of a segment object starting on 2022-11-08 at 15:08:23.547 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/15/08-23.547Z.0.mp4</programlisting>
      <para>
        The key of a span end object for a span consisting of 85 segments and ending on 2022-11-08 at 16:34:11.421 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/16/34-11.421Z.85.mp4_end</programlisting>
      <para>
        Given the following storage configuration in a recording configuration:
      </para>
      <programlisting><![CDATA[<tt:Target>
  <tt:Storage>1</tt:Storage>
  <tt:Format>CMAF</tt:Format>
  <tt:Prefix>site-2</tt:Prefix>
  <tt:Postfix>camera-5</tt:Postfix>
  <tt:SegmentDuration>PT5S</tt:SegmentDuration>
</tt:Target>]]></programlisting>
      <para>
        The key of a video segment object containing starting on 2022-11-08 at 15:08:23.547 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/15/08-23.547Z.0.m4v</programlisting>
      <para>
        The key of a span end object for a video span consisting of 1020 segments and ending on 2022-11-08 at 16:34:11.421 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/16/34-11.421Z.1020.m4v_end</programlisting>
      <para>
        The key of an audio segment object starting on 2022-11-08 at 15:08:23.989 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/15/08-23.989Z.0.m4a</programlisting>
      <para>
        The key of a span end object for an audio span consisting of 1020 segments and ending on 2022-11-08 at 16:34:11.779 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/16/34-11.779Z.1020.m4a_end</programlisting>
      <para>
        The key of a metadata segment object starting on 2022-11-08 at 15:08:23.692 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/15/08-23.692Z.0.m4m</programlisting>
      <para>
        The key of a span end object for a metadata span consisting of 1020 segments and ending on 2022-11-08 at 16:34:11.871 (UTC) is:
      </para>
      <programlisting>site-2/2022-11-08/camera-5/16/34-11.871Z.1020.m4m_end</programlisting>
    </section>
  </appendix>
  <appendix xml:id="_refSegmentExport">
    <title>Segment export (Normative)</title>
    <section xml:id="_refSegmentExportOverview">
      <title>Overview</title>
      <para>
        This annex describes the requirements for recording and exporting media streams in a cloud-friendly format.
        Device will need to record on their local storage when a <literal>RecordingTargetConfiguration</literal> has its strategy set to "Local" or "Both".
        While the device can record locally using any format, segments can be queried at any time and the resulting list of segments MUST be stable.
        "Stable" here is defined in the sense that each frame will always be part of the same segment and the available segments are immutable.
      </para>
      <para>
        Specific recorded segments can then be exported to the cloud on request and each exported segment MUST yield the same result (a CMAF or MP4 file 
        containing all its frames) on a successful export operation.
      </para>
      <para>
        The deterministic properties of the segments (when queried or exported) facilitate features like HLS or MPEG-DASH playback from the device,
        and also a simple way to implement on-demand video trickling from the local storage for a device to the cloud.
      </para>
    </section>
    <section xml:id="_refSegmentExportRecording">
      <title>Recording segments</title>
      <para>
        There are three possible recording strategies as defined for <literal>RecordingTargetConfiguration</literal>:
        <variablelist>
          <varlistentry>
            <term>Cloud (default)</term>
            <listitem>
              <para>
                The device will automatically upload each recorded segment to the Cloud location as soon as possible. After completion or on error the data won't be kept locally on the device. 
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Local</term>
            <listitem>
              <para>
                The device will record the segments on its local storage and respect the MaximumRetentionTime of the RecordingConfiguration.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Both</term>
            <listitem>
              <para>
                The device will record the segments on its local storage and respect the MaximumRetentionTime of the RecordingConfiguration. It will also attempt to automatically upload each segment to the Cloud location as they become available.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
      <para>
        When recording on its local storage, the device may need to delete the oldest recording segments if storage space is insufficient.
      </para>
      <para>
        When uploading to the configured Cloud location, if an error occurs the device can retry but should abandon if the operation took too long and the next segment is ready to be uploaded.
        Only whole segments should be uploaded and committed to the cloud storage (no incomplete segment should be made available on failure).
      </para>
    </section>
    <section xml:id="_refSegmentExportCommands">
      <title>Segment export commands</title>
      <para>
        The <literal>ListRecordedSegments</literal> command lists the segments currently available for export from the device local storage.
        For a given time range, this command shall always return the same segments with two exceptions: the newly recorded segments are added as they become
        available, and the deleted segments are removed from it (for example if the device had to delete them to make room for the new ones).
      </para>
      <para>
        The <literal>ExportRecordedSegments</literal> command starts an export operation for all segment (partially or entirely) contained in the 
        specified time range. Multiple operations at the same time can be queued and processed sequentially. While the operation is being executed 
        the segments must not be deleted until they are uploaded (but the following ones can be). Segments should be uploaded in chronological order.
        Progression can be tracked with <literal>GetExportRecordedSegmentState</literal>. Operations can be cancelled at any time with <literal>StopExportRecordedSegments</literal>.
        The segment names used shall follow <xref linkend="_refCloudRecordingSegmentObjects"/>, with <literal>counter</literal> starting 
        at zero for the first segment of each export operation, unless the OmitSequenceNumber is set to True.
      </para>
      <para>
        Note: it is possible that the segments listed with <literal>ListRecordedSegments</literal> are not exactly the ones exported with <literal>ExportRecordedSegments</literal>
        as some segments could be deleted/added in-between the two commands being executed.
      </para>
    </section>
    <section xml:id="_refSegmentExportStability">
      <title>Segment stability</title>
      <para>
        Segment stability is essential for this feature: each frame must be part of exactly one segment and each segment must always be immutable in time.
        Additionnally, each segment must start with a keyframe to make it independent from the previous one. Some devices may record frames in a proprietary 
        format, so the segments won't exist until exported to the cloud storage. Since the device must be able to list them beforehand, we suggest a simple
        algorithm to determine how many segments will be in each time range and which frames will be part of them.
      </para>
      <para>
        The figure <xref linkend="_refSegmentExportStabilityExample" /> illustrates how a global real time clock timestamp (that doesn't reset on device reboot 
        or resync on NTP) could be segmented in time ranges for the target segment duration with a modulus operation. Then each boundary of these ranges are 
        adjusted to match the time of the next keyframe. The result is the list of segment boundaries that overlap with the original time range of the query. 
        Care should be taken not to return the most recent segment if it is incomplete (when more frames may be appended to it later, i.e.: it overlaps with the current time).
      </para>
      <figure xml:id="_refSegmentExportStabilityExample">
        <title>Example of possible algorithm to ensure segment stability</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="media/RecordingControl/segmentExportStabilityExample 1.svg" contentwidth="120mm" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </appendix>
  <appendix role="revhistory">
    <title>Revision History</title>
    <para/>
  </appendix>
</book>