RTP Streaming API
This XML-based RTP Streaming API allows applications to initiate and observe RTP audio streams. This API extends capabilities beyond the legacy RTP streaming URIs by providing support for stream start and stop event listeners and the ability to specify other extended stream attributes, such as codec type.
| Note | Support for the RTP Streaming API requires an updated XML Parser.
The Multiplatform phones doe not support the RTP Streaming API. |
The event handlers typically use the standard Notification framework, but they can also invoke most other URIs, with the exception of HTTP URLs.
Related References
Updated XML Parser and Schema Enforcement
Notify
Interaction Rules with Legacy RTP URI Streams
The RTP Streaming API allows a full-duplex stream (mode=sendReceive) to be set up as a single stream request, which simplifies the usage of the API. However, in some cases, this API creates some interoperability issues with the legacy RTP URIs because the legacy RTP URIs send and receive streams separately. The interaction rules between legacy RTP URI streams and the new RTP Streaming API are:
- If an RTP Stop URI is invoked, and an RTP Streaming API stream is currently streaming in that same direction, then the entire RTP Streaming API stream is stopped.
For example, if a full-duplex stream is set up through the RTP Streaming API (mode=sendReceive) and then an RTPTx:Stop URI is invoked, the stream will be stopped in both the send and receive directions (and the onStopped event handler will be called, if present).
- If the stopMedia request (from the RTP Streaming API) does not specify a stream ID, then the request will stop all services RTP streams, in any direction (send or receive) and of any type (multicast and unicast). This allows applications using the RTP Streaming API to stop media streams which may have been started by the legacy RTP URIs or by other applications for which a stream ID is not known.
Error Schema
XML:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="errorResponse">
<xs:complexType>
<xs:all>
<xs:element name="type">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="InvalidURL"/>
<xs:enumeration value="InvalidResource"/>
<xs:enumeration value="InvalidResourceID"/>
<xs:enumeration value="UnavailableResource"/>
<xs:enumeration value="InvalidXML"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="data" nillable="true">
<xs:simpleType>
<xs:restriction base="xs:string"/>
</xs:simpleType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:schema>
RTP Streaming API Examples
The following examples show how to work with the RTP Streaming API.
Start Media Example
Request
Code:
HTTP POST /CGI/Execute
<startMedia>
<mediaStream
onStopped=”Notify:http:server:80:path/page”
receiveVolume=”50”>
<type>audio</type>
<codec>G.729</codec>
<mode>sendReceive</mode>
<address>239.1.2.3</address>
<port>20480</port>
</mediaStream>
</startMedia>
Response
Code:
HTTP200 OK
<mediaStream id=”abc123”/>
Stop Media Example
Request
Code:
HTTP POST CGI/Execute
<stopMedia>
<mediaStream id=”abc123”/>
</stopMedia>
Response
If the user terminates the media stream by placing the active audio path on-hook, the following notification is sent:
Code:
HTTP POST /server/path/page
DATA=<notifyMediaEvent type=”stopped” origin=”user”>
<mediaStream id=”abc123”/>
</notifyMediaEvent>
