XEP-xxxx: Jingle RTMP Transport

This specification defines a Jingle transport method for Real Time Messaging Protocol (RTMP) a proprietary protocol owned by Adobe Systems that is primarily used with a Flash media server to stream audio and video over the internet to the Adobe Flash Player clients.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Informational
Version: 0.0.1
Last Updated: 2007-02-06
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0166
Supersedes: None
Superseded By: None
Short Name:

Author Information

Dele Olajide

Email: dele@uk2.net
JID: dele@4ng.net

Matt Tucker

Email: matt@jivesoftware.com
JID: matt@jivesoftware.com

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Table of Contents

1. Introduction
2. Requirements
3. Protocol Description
3.1. Transport Initiation
3.2. Target Entity Response
3.2.1. Checking the Initiating Entity's Candidates
3.2.2. Accepting a Candidate
3.2.3. Intitiating RTMP Media Streams
3.3. Informational Messages
4. RTMP Service Discovery
5. Deployment Notes
6. Security Considerations
7. IANA Considerations
8. XMPP Registrar Considerations
8.1. Protocol Namespaces
8.2. Jingle Transport Methods
9. XML Schema
9.1. Transport method
9.2. Transport method
Notes
Revision History


1. Introduction

Jingle [1] defines a framework for negotiating and managing out-of-band multimedia sessions over XMPP. In order to provide a flexible framework, the base Jingle specification omits data transport methods and media session types, requiring separate specifications.

Typical peer-to-peer session types include voice chat (see Jingle Audio Content Description Format [2]) and video chat (see Jingle Video Content Description Format [3]) which are based on the Real-time Transport Protocol (RTP) and will be suitable for specifying RTMP.

Unfortunately, none of the existing transport mechanisms such as Jingle RTP-ICE Transport Method [4], Jingle Raw UDP Transport Method [5], and Jingle IAX Transport Method [6] can support the Adobe Flash Player client. Therefore, this document defines a new Jingle transport method for establishing and managing RTMP streams via a media server.

2. Requirements

The Jingle transport method defined herein is designed to meet the following requirements:

  1. Make it possible to establish and manage out-of-band RTMP connections between two XMPP entities via a server-side media server using the protocol and port that the parties consider most likely to succeed.
  2. Make it relatively easy to implement support for XMPP clients embedded in a web browser.
  3. Where communication with non-XMPP entities is needed, push as much complexity as possible onto server-side gateways between the XMPP network and the non-XMPP network.

3. Protocol Description

3.1 Transport Initiation

In order for the initiating entity in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in XEP-0166. This stanza MUST include at least one transport method. If the initiating entity wishes to negotiate the RTMP transport, it MUST include a <transport/> child element qualified by the http://www.xmpp.org/extensions/xep-xxxx.html#ns' namespace.

This <transport/> element MUST include at least one <candidate/> element specifying the route to a media server application that will publish the audio and/or video media of the initiating entity. See http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_16631 for more details about the RTMP protocol.

Example 1. Initiation Example



<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='jingle1' type='set'>
  <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
	action='session-initiate' 
	initiator='romeo@montague.net/orchard' 
	sid='a73sjjvkla37jfea'>
	
	<content creator='romeo@montague.net' name='this-is-the-audio-content'>
	  <description ...>
	  <transport xmlns='http://www.xmpp.org/extensions/xep-xxxx.html#ns'>
	  	<candidate name='Red5' 
                           url='rtmp://red5.jivesoftware.org/jingle' 
                           generation='0' 
                           stream='romeoaudiovideo23456'/>
		<candidate name='Red5HTTPTunnel' 
                           url='rtmpt://red5.jivesoftware.org:9090/jingle' 
                           generation='0' 
                           stream='romeoaudiovideo23456'/>
		<candidate name='Red5Secure' 
                           url='rtmpts://red5.jivesoftware.org:9091/jingle' 
                           generation='0' 
                           stream='romeoaudiovideo23456'/>
	  </transport>
	</content>
   </jingle>
</iq>

	

The attributes of the elements are as follows:

The'url', 'name', 'generation' and 'stream' attributes are all REQUIRED.The 'generation' attribute provides a tracking mechanism for determining which version of this candidate is in force (this is useful if the candidate is redefined mid-stream, for example if the port is changed). The stream attribute is the unique session media stream name that the initiating entity is requesting the media server to use for publishing its media. Stream names can be any valid string with no special characters. The 'url'attribute provides the fully qualified RTMP connection name of an application running on the media server with support for Jingle.

In order to determine the candidates, the requesting entity would perform a service discovery of the RTMP media server obtainingthe fully qualified RTMP connection names of applications that will support a Jingle session. (See RTMPService Discovery)

3.2 Target Entity Response

As described in XEP-0166, to provisionally accept the session initiation request, the target entity returns an IQ-result:

Example 2. Target Entity Provisionally Accepts the Session Request


<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='result' id='jingle1'/>

	

Once the target entity provisionally accepts the session, it:

  1. MUST check the candidates by performing a handshake with the specified media server applications until it is sucessfull.
  2. SHOULD generate its own unique session stream name that will be used for publishing it own media stream.
  3. MAY send one or more information messages.

3.2.1 Checking the Initiating Entity's Candidates

The target entity MUST immediately attempta handshake between its Flash Player client and the media server by:

  1. Making a connection to the candidate application by using the fully qualified RTMP connection name specified in the 'url' attribute.
  2. Invoke a remote function in the candidate's media server application called 'ping'. If the function is sucessfully invoked, it should in return call a function in the Flash Player client called 'pong'. Once the pong function in Flash Player client has been sucessfully invoked, the handshake should be considered sucessful.

As soon as a sucessful handshake occurs between the Flash Player client anda media server application,then the application should be considered a suitable candidate.

3.2.2 Accepting a Candidate

To definitively accept the RTMP transport method, the target entity MUST send a element with an action of 'transport-accept', specifying the candidate name desired and the media stream name that it has generated for publishing it own media. The stream name can be any valid string with no special characters.

Example 3. Target Entity Accepts the RTMP Transport Method


<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='set' id='accept1'>
    <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
	action='transport-accept'
	initiator='romeo@montague.net/orchalient'
	sid='a73sjjvkla37jfea'>
	
	<content creator='romeo@montague.net' name='this-is-the-audio-content'>
	    <transport xmlns='http://www.xmpp.org/extensions/xep-xxxx.html#ns'>
		<candidate name='Red5' stream='julietaudiovideo5678543' />
	    </transport>
	</content>
    </jingle>
</iq>

	  

The initiating entity then acknowledges the target entity's acceptance:

Example 4. Initiating Entity Acknowledges Definitive Acceptance


 <iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' type='result' id='accept1'/>

	  

3.2.3 Intitiating RTMP Media Streams

Now the initiating entity and target entity can initiate their Flash Player clients to publish the appropriate media over the negotiated RTMP stream names to the candidate media server application. In this example, the application's RTMP connection name is rtmp://red5.jivesoftware.org/jingle and Romeo will publish to stream romeoaudiovideo23456 while Juliet will publish to stream julietaudiovideo5678543.

In the event that the Flash Player client of the target or initiating entity cannot publish or subscribe to each other'smedia stream, they SHOULD terminate the session (see XEP-0176 or XEP-0177 for examples).

3.3 Informational Messages

While checking the initiating entity's RTMP candidates with a handshake, the target entity MAY send an informational message to communicate the status of transport checking. The informational message MUST be an IQ-set containing a element of type "transport-info", where the informational message is payload element qualified by the 'http://www.xmpp.org/extensions/xep-xxxx.html#ns-info' namespace. The following payload elements can be used

Table 1: Information Payload Elements

Element Meaning
<failed/> Transport check failed.
<succeeded/> Transport check succeeded.
<trying/> Transport check in progress.

Example 5. Target entity reports on candidates checking


<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jingle2' type='set'>
    <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
	 action='transport-info'
	 initiator='romeo@montague.net/orchard'
	 sid='a73sjjvkla37jfea'>
	 
	 <trying xmlns='http://www.xmpp.org/extensions/xep-xxxx.html#ns-info'>
	     <candidate name='Red5' status='ping' />
	 </trying>
    </jingle>
</iq>

	  

4. RTMP Service Discovery

To discover an RTMP media server, an entity needs to send a normal disco query to the XMPP server.

Example 6. Entity queries for RTMP Service Discovery


<iq type='get'
	from=' romeo@montague.net/orchard '
	to='jivesoftware.org'
	id='items1'>
	
	<query xmlns='http/jabber.org/protocol/disco#items'/>
</iq>

	  

If the server supports an RTMP media server component (external or internal), then a 'jid' item with the name 'RTMP' should be returned. If there is no item named 'RTMP', the server does not support this feature.

Example 7. Entity receives response for RTMP Service Discovery


<iq from="jivesoftware.org" type="result" to=" romeo@montague.net/orchard" id="items1" >
	<query xmlns="http/jabber.org/protocol/disco#items">
		<item name="Public Chatrooms" jid="conference.jivesoftware.org" />
		<item name="RTMP" jid="red5.jivesoftware.org" />
		<item name="User Search" jid="search.jivesoftware.org" />
	</query>
</iq>

	  

To determine which applications on the media server supports Jingle, the entity should send an info disco query to the media server component. The node attribute on the query MUST be set to 'jingle'.

Example 8. Entity queries RTMP media server component


<iq type='get'
	 from=' romeo@montague.net/orchard '
	 to='red5.jivesoftware.org'
	 id='info1'>
	 
	<query xmlns='http/jabber.org/protocol/disco#info' node='jingle' />
</iq>

	  

The media server component should respond with the fully qualified RTMP connection names of media server applicationsthat will support Jingle.

Example 9. Entity receives response for RTMP media server component


 <iq type='result'
     from='red5.jivesoftware.org'
     to=' romeo@montague.net/orchard '
     id='info1'>
	
     <query xmlns='http://jabber.org/protocol/disco#info' node='jingle' >
	<identity category='server' type='media' name='rtmp://red5.jivesoftware.org/jingle'>
	<identity category='server' type='media' name='rtmpt://red5.jivesoftware.org:9090/jingle'>
	<identity category='server' type='media' name='rtmpts://red5.jivesoftware.org:9091/jingle'>
	<identity category='server' type='media' name='rtmp://red5.jivesoftware.org/jingle2'>
	<identity category='server' type='media' name='rtmpt://red5.jivesoftware.org:9090/jingle2'>
	<identity category='server' type='media' name='rtmpts://red5.jivesoftware.org:9091/jingle2'>
	<feature var='http://jabber.org/protocol/disco#info'/>
	<feature var='http://www.xmpp.org/extensions/xep-xxxx.html#ns' />
    </query>
</iq>

	  

There SHOULD be an entry for each application, RTMP protocol and optional port number supported by the media serverspecified as afully qualified RTMP connection name using the 'name' attribute.

5. Deployment Notes

This specification applies to both XMPP clients and servers. However, service administrators may wish to deploy an external gateway or internal plugin to the media server in order to simplify the channel or negotiation process. The specifics are outside the scope of this document.

6. Security Considerations

In order to secure the media streams, implementations SHOULD use the rtmpts protocol to tunnel their media streams through an encrypted SSL session.

7. IANA Considerations

This document requires no interaction with IANA;.

8. XMPP Registrar Considerations

8.1 Protocol Namespaces

Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-xxxx.html#ns" and "http://www.xmpp.org/extensions/xep-xxxx.html#ns-info"; upon advancement of this specification, the XMPP Registrar [7] shall issue more permanent namespaces in accordance with the process defined in Section 4 of XMPP Registrar Function [8].

8.2 Jingle Transport Methods

The XMPP Registrar shall include "http://www.xmpp.org/extensions/xep-xxxx.html#ns" (see Protocol Namespaces) in its registry of Jingle transport methods. The registry submission is as follows:


	<transport>
	  <name>RTMP</name>
	  <desc> A method for exchanging media between Adobe Flash clients.</desc>
	  <doc>XEP-xxxx</doc>
	</transport>

9. XML Schema

9.1 Transport method



<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-xxxx.html#ns'
    xmlns='http://www.xmpp.org/extensions/xep-xxxx.html#ns'
    elementFormDefault='qualified'>

  <xs:element name='transport'>
    <xs:complexType>
      <xs:sequence minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='candidate'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='candidate'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='generation' type='xs:unsignedByte' use='required'/>
          <xs:attribute name='name' type='xs:string' use='required'/>
          <xs:attribute name='stream' type='xs:string' use='required'/>
          <xs:attribute name='url' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>


  

9.2 Transport method


<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-xxxx.html#ns-info'
    xmlns='http://www.xmpp.org/extensions/xep-xxxx.html#ns-info'
    elementFormDefault='qualified'>

  <xs:element name='failed'>
    <xs:complexType>
      <xs:sequence minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='candidate'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='succeeded'>
    <xs:complexType>
      <xs:sequence minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='candidate'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='trying'>
    <xs:complexType>
      <xs:sequence minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='candidate'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='candidate'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='generation' type='xs:unsignedByte' use='required'/>
          <xs:attribute name='name' type='xs:string' use='required'/>
          <xs:attribute name='stream' type='xs:string' use='required'/>
          <xs:attribute name='url' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>

  


Notes

1. XEP-0166: Jingle <http://www.xmpp.org/extensions/xep-0166.html>.

2. XEP-0167: Jingle Audio Content Description Format <http://www.xmpp.org/extensions/xep-0167.html>.

3. XEP-0180: Jingle Video Content Description Format <http://www.xmpp.org/extensions/xep-0180.html>.

4. XEP-0176: Jingle RTP-ICE Transport Method <http://www.xmpp.org/extensions/xep-0176.html>.

5. XEP-0177: Jingle Raw UDP Transport Method <http://www.xmpp.org/extensions/xep-0177.html>.

6. XEP-0179: Jingle IAX Transport Method <http://www.xmpp.org/extensions/xep-0179.html>.

7. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.

8. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.


Revision History

Version 0.0.1 (2007-02-06)

First draft. (mt/do)


END