Display 2.3 ONVIF™ www.onvif.org May, 2013 2008-2020 ONVIF™ All rights reserved. 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. 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. 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. 2.1 Jul-2011 Hans Busch Split from Core 2.0 Change Requests 187, 190, 191 2.1.1 Jan-2012 Hans Busch Change Request 535 2.2.1 Dec-2012 Hans Busch Change Request 708 2.3 May-2013 Michio Hirai Change Request 972 Change Request 1843 Scope This document defines the web service interface for configuration of the display of a Video rendering device with optional Audio support. Additionally the associated events are defined. Web service usage is outside of the scope of this document. Please refer to the ONVIF core specification. ONVIF Core Specification <> ONVIF Receiver Service Specification <> ONVIF DeviceIO Service Specification <>

Layout Defines the arrangement of display areas (panes) on a monitor Pane Defines an area on a physical display.

RTSP Real Time Streaming Protocol

The display service provides functions to enable a client to control and configure display devices. The service introduces panes, each of which occupies an area of the physical display. The configuration of the pane maps audio inputs and outputs to a video output. The configuration also references a Receiver Object which receives the data to be displayed. Functions to retrieve and configure the configuration of a pane are provided.

A layout defines how these panes are visible on the display (e.g single view or quad view). The service introduces commands to retrieve the current layout of a display and change the layout. The service also introduces commands to request the encoding and decoding capabilities of a video output as well as the layout options. WSDL for the display service is specified in http://www.onvif.org/ver10/display.wsdl. Prefix Namespace URI env http://www.w3.org/2003/05/soap-envelope ter http://www.onvif.org/ver10/error xs http://www.w3.org/2001/XMLSchema tt http://www.onvif.org/ver10/schema tls http://www.onvif.org/ver10/display/wsdl A display device has a fixed number of video outputs, each of which may be attached to a monitor. A client can request the video outputs of the device using the DeviceIO service. Each of these outputs is configured with a layout (e.g. single view or split screen). The layout defines a number of video panes, each of which occupies an area of the physical display. A network video display may also have fixed number of audio inputs and audio outputs. Each of these outputs may be associated with a pane. Associating an audio input or output with a pane maps the audio and video streams from a transmitter device automatically to the correct outputs. The pane also contains a pointer to a receiver where the necessary information to connect the display device to a transmitter is stored. The Display Service offers functions to configure the Panes and describe and change the layout of the display device. The possible layouts and coding capabilities of a video output can be requested. A display device shall support the Display Service as defined in [DisplayService.wsdl].

A Pane is a display area on the monitor that is attached to a video output. A pane has a PaneConfiguration that describes which entities are associated with the pane. The PaneConfiguration includes: Pane Token: A unique identifier in the display device. Pane Name: Configuration name. AudioOutputToken: A pointer to the audio output that is associated with the pane. A client can retrieve the available audio outputs of a device using the GetAudioOutputs command of the DeviceIO service. AudioSourceToken: A pointer to the audio source that is associated with this pane. The audio connection from a display device to a client is established using the backchannel mechanism. A client can retrieve the available audio sources of a device using the GetAudioSources command of the DeviceIO service. AudioEncoderConfiguration: The configuration of the audio encoder including codec, bitrate and sample rate. ReceiverToken: A pointer to a receiver as defined in the ONVIF Receiver Service Specification that has the necessary information to receive Data from a Transmitter. This Receiver can be connected and the network video display displays the received data on the specified outputs. A client can retrieve the available Receivers using the GetReceivers command of the Receiver Service. A client has to configure the pane according to the connection to be established by setting the AudioOutput and/or AudioSourceToken. If a Token is not set, the corresponding session will not be established. Changing the PaneConfiguration or the parameters of a referenced receiver shall not affect the RTSP connection. If a client intends to apply the new parameters it shall restart the RTSP connection. The pane layout (see ) of the video output defines if and where (position, size) a Pane is currently visible. The receiver should only establish an RTSP connection to receive data if the pane is visible. Layout changes shall not affect running streams.

This command lists all currently defined Panes of a device for a specified video output (regardless if this pane is visible at a moment). A display device shall support the retrieval of its configured panes through this command. request VideoOutput [tt:ReferenceToken] The VideoOutput element specifies the Video Output whose PaneConfigurations are requested. response PaneConfiguration - unbounded [tt:PaneConfiguration] Contains a list of defined Panes of the specified VideoOutput. Each VideoOutput has at least one PaneConfiguration. faults env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist access class READ_MEDIA

If the pane token is already known this command can be used to get the pane configuration. A display device shall support the retrieval of a specific pane configuration through this command. request VideoOutput [tt:ReferenceToken] This message contains the token of the pane whose configuration is requested. It also contains a VideoOutput token that specifies the Video Output that contains the requested pane. Pane [tt:ReferenceToken] response PaneConfiguration [tt:PaneConfiguration] Contains the requested PaneConfiguration faults env:Sender - ter:InvalidArgVal - ter:NoPane The requested pane does not exist env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist access class READ_MEDIA

This command changes the Configuration of all existing panes in one step. The message contains all PaneConfigurations (modified and not modified ones) of the video output. A display device shall support the modification of its panes configuration through this command. request VideoOutput [tt:ReferenceToken] This message contains the configuration of all panes of the specified VideoOutput. The PaneConfiguration element contains the modified configuration. PaneConfiguration - unbounded [tt:PaneConfiguration] response This is an empty message. faults env:Sender - ter:InvalidArgVal - ter:invalidConfig The configuration is not possible to set env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist access class ACTUATE

This command changes the Configuration of a single pane. A display device shall support the modification of a single pane configuration through this command. request VideoOutput [tt:ReferenceToken] This message contains the token of the video output and the new PaneConfiguration. PaneConfiguration [tt:PaneConfiguration] response This is an empty message. faults env:Sender - ter:InvalidArgVal - ter:NoPane The requested pane does not exist env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist env:Sender - ter:InvalidArgVal - ter:InvalidConfig The configuration is not possible to set access class ACTUATE

This command creates a pane configuration. A display device that supports dynamic creation of panes shall support the creation of a pane configuration through this command. A service implementation is free to choose any suitable token for the PaneConfiguration and may ignore the content of the token field. request VideoOutput [tt:ReferenceToken] This message contains the token of the video output and the new PaneConfiguration. PaneConfiguration [tt:PaneConfiguration] response PaneToken [tt:ReferenceToken] This message contains the token of the the new PaneConfiguration. faults env:Sender - ter:InvalidArgVal - ter:MaxNumberOfPane The maximum number of panes is reached env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist env:Sender - ter:InvalidArgVal - ter:InvalidConfig The configuration is not possible to set access class ACTUATE

This command deletes a pane configuration. A display device that supports dynamic deletion of panes shall support the deletion of a pane configuration through this command. request VideoOutput [tt:ReferenceToken] This message contains the token of the video output and the PaneConfiguration. PaneToken [tt:ReferenceToken] response This is an empty message. faults env:Sender - ter:InvalidArgVal - ter:FixedPane It is not possible to delete this pane configuration env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output does not exist env:Sender - ter:InvalidArgVal - ter:NoPane The requested pane configuration does not exist. access class ACTUATE

The Layout assigns a pane configuration to a certain area of the display. The layout settings directly affect a specific video output. The layout consists of a list of PaneConfigurations and their associated display areas. If the device supports overlapping panes then the order the panes are displayed on the monitor is defined by the order of the PaneConfigurations in the list. The first Pane in the list is the one that is displayed in the foreground. A device may either provide a fixed number of supported layouts or it is possible to configure the layout free.

This command returns the current layout of a video output. A display device shall support the retrieval of its layout through this command. request VideoOutput [tt:ReferenceToken] Contains the VideoOutputToken of the output the display is connected to. response Layout [tt:Layout] Contains the current layout of the VideoOutput. faults env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output indicated with VideoOutput does not exist. access class READ_MEDIA

The SetLayout operation can be used to change the layout of a display (e.g. change from single view to split screen view). A display device shall support the change of layout through this command. A device implementation shall be tolerant against rounding errors when matching a layout against its fixed set of layouts by accepting differences of at least one percent. request VideoOutput [tt:ReferenceToken] Contains the VideoOutputToken of the output the display is connected to. Layout [tt:Layout] Layout configuration to be applied. response This message is an empty message. faults env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested Video Output indicated with VideoOutput does not exist. env:Sender - ter:InvalidArgVal - ter:InvalidLayout It is not possible to set the layout. access class ACTUATE

The Display Options contain the supported layouts (LayoutOptions) and the decoding and encoding capabilities (CodingCapabilities) of the device. The GetDisplayOptions command returns both, Layout and Coding Capabilities, of a VideoOutput. LayoutOptions The LayoutOptions describe the fixed and predefined layouts of a device. If the device does not offer fixed layouts and allows setting the layout free this element is empty. Coding Capabilities The network video display is able to decode audio and video streams using suitable decoding algorithms. The network video display supports any audio and video decoders, bitrates and resolution according to the manufacturer‘s choice. In order to ensure interoperability between the different devices, this specification mandates the following decoder profiles: The NVD shall support JPEG QVGA. The NVD shall support G.711μ Law (if it supports audio) These are the same codecs that are mandatory for Profile S clients. There are no parameters to configure a decoder; a decoder shall decode all content (according to its capabilities) it receives. In case of decoding errors the decoder should try to request a synchronization point and try to continue decoding. It shall generate an event as defined in section . The CodingCapabilities Element gives an indication about the decoding and encoding capabilities of the device.

This command lists layout and coding capabilities of a video output. A display device shall support the retrieval of its DisplayOptions through this command. request VideoOutput [tt:ReferenceToken] This message contains the token of the video output for which the information is requested. response LayoutOptions optional [tt:LayoutOptions] Message containing the available layouts as well as codings for the VideoOutput. CodingCapabilities [tt:CodingCapabilities] faults env:Sender - ter:InvalidArgVal - ter:NoVideoOutput The requested VideoOutputToken does not exist access class READ_MEDIA

The display service shall dispatch events through the event service.

The device shall be capable of generating the following event whenever it receives a bitstream that it is not able to decode. There are several reasons why a decoder is not able to decode the bitstream. The following error codes are defined and shall be used by the device to inform the client about decoder errors: “unsupported codec or unsupported codec profile” – The device is not able to decode the bitstream, because the codec or the profile is not supported by the device. The client should the try to reconfigure the transmitter according to the CodingCapabilities of the device. “packet error” – there are missing or unexpected packets in the bitstream. Other vendor specific codes are also allowed. Topic: tns1:VideoDecoder/DecodingError <tt:MessageDescription IsProperty="false"> <tt:Source> <tt:SimpleItemDescription Name="VideoOutputToken" Type="tt:ReferenceToken"/> </tt:Source> <tt:Data> <tt:SimpleItemDescription Name="PaneReference" Type="tt:ReferenceToken"/> <tt:SimpleItemDescription Name=”Error” Type=”xs:string” minOccurs=”0”/> </tt:Data> </tt:MessageDescription>

This event shall be generated whenever a layout is changed. Typical reason is a call to SetLayout? resulting in an layout change. Topic: tns1:VideoOutput/Layout/LayoutChanged <tt:MessageDescription IsProperty="false"> <tt:Source> <tt:SimpleItemDescription Name="VideoOutputToken" Type="tt:ReferenceToken"/> </tt:Source> </tt:MessageDescription>

The capabilities reflect optional functions and functionality of a service. The information is static and does not change during device operation. The following capabilities are available: FixedLayout Indication that the SetLayout command supports only predefined layouts. request This is an empty message. response Capabilities [tls:Capabilities] The capability response message contains the requested service capabilities using a hierarchical XML capability structure. faults No command specific faults! access class PRE_AUTH