gst/rtsp/README: Added rtsp server implementation docs.

Original commit message from CVS:
* gst/rtsp/README:
Added rtsp server implementation docs.

1 files changed, 216 insertions, 1 deletions

diff --git a/gst/rtsp/README b/gst/rtsp/README
index 2f7fde89..820c17d3 100644
--- a/gst/rtsp/README
+++ b/gst/rtsp/README
@@ -105,6 +105,7 @@ An RTSP session is created as follows:
 
     >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
     >> CSeq: 2
+    >> Session: 5d5cb94413288ccd
     >>
     << RTSP/1.0 200 OK
     << CSeq: 2
@@ -153,4 +154,218 @@ An RTSP session is created as follows:
 
     $<1 byte channel><2 bytes length, big endian><length bytes of data>
 
-  
+
+RTSP server
+-----------
+
+An RTSP server listen on a port (default 554) for client connections. The client
+typically keeps this channel open during the RTSP session to instruct the server
+to pause/play/stop the stream.
+
+The server exposes a stream consisting of one or more media streams using an
+URL. The media streams are typically audio and video.
+
+  ex:
+     rtsp://thread:5454/alien-rtsp.mpeg
+
+     exposes an audio/video stream. The video is mpeg packetized in RTP and
+     the audio is mp3 in RTP.
+
+The streaming server typically uses a different channel to send the media
+data to clients, typically using RTP over UDP. It is also possible to stream
+the data to the client using the initial RTSP TCP session (the interleaved
+mode). This last mode is usufull when the client is behind a firewall but
+does not take advantage of the RTP/UDP features.
+
+In both cases, media data is send to the clients in an unmultiplexed format
+packetized as RTP packets.
+
+The streaming server has to negotiate a connection protocol for each of the
+media streams with the client.
+
+Minimal server requirements:
+
+- The server should copy the CSeq header field in a client request to the
+  response so that the client can match the response to the request.
+
+- The server should keep a session for each client after the client issued
+  a SETUP command. The client should use the same session id for all future
+  request to this server.
+
+- the server must support an OPTIONS request send over the RTSP connection.
+
+    >> OPTIONS * RTSP/1.0
+    >> CSeq: 1
+    >>
+    << RTSP/1.0 200 OK
+    << CSeq: 1
+    << Date: Wed May 11 13:21:43 2005 GMT
+    << Session: 5d5cb94413288ccd
+    << Public: DESCRIBE, SETUP, TEARDOWN, PLAY
+    <<
+
+   The OPTIONS request should list all supported methods on the server.
+ 
+ - The server should support the DESCRIBE method.
+
+    >> DESCRIBE rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
+    >> Accept: application/sdp
+    >> CSeq: 2
+    >>
+    << RTSP/1.0 200 OK
+    << Content-Length: 84
+    << Content-Type: application/sdp
+    << CSeq: 2
+    << Date: Wed May 11 13:09:37 2005 GMT
+    <<
+    << v=0
+    << o=- 0 0 IN IP4 192.168.1.1
+    << s=No Title
+    << m=audio 0 RTP/AVP 14
+    << a=control:streamid=0
+
+    The client issues a DESCRIBE command for a specific URL that corresponds
+    to an available stream. The client will also send an Accept header to
+    list its supported formats. 
+
+    The server answers this request with a reply in one of the client supported
+    formats (application/sdp is the most common). The server typically sends a
+    fixed reply to all clients for each configured stream.
+
+ - The server must support the SETUP command to configure the media streams 
+   that were listed in the DESCRIBE command.
+
+    >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
+    >> CSeq: 3
+    >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
+    >>
+    << RTSP/1.0 200 OK
+    << Transport: RTP/AVP/UDP;unicast;client_port=5000-5001;server_port=6000-6001
+    << CSeq: 3
+    << Date: Wed May 11 13:21:43 2005 GMT
+    << Session: 5d5cb94413288ccd
+
+    The client will send a SETUP command for each of the streams listed in the 
+    DESCRIBE reply. For sdp will use a URL as listed in the a=control: property.
+
+    The client will list the supported transports in the Transport: header field.
+    Each transport is separated with a comma (,) and listed in order of preference.
+    The server has to select the first supported transport.
+ 
+    In the above example 3 transport are listed:
+
+       RTP/AVP/UDP;unicast;client_port=5000-5001
+
+         The client will accept RTP over UDP on the port pair 5000-5001. Port
+	 5000 will accept the RTP packets, 5001 the RTSP packets send by the
+	 server.
+       
+       RTP/AVP/UDP;multicast
+
+         The client can join a multicast group for the specific media stream.
+	 The port numbers of the multicast group it will connect to have to
+	 be specified by the server in the reply.
+       
+       RTP/AVP/TCP
+
+         the client can accept RTP packets interleaved on the RTSP connection.
+
+    The server selects a supported transport an allocates an RTP port pair to
+    receive RTP and RTSP data from the client. This last step is optional when
+    the server does not accept RTP data.
+
+    The server should allocate a session for the client and should send the
+    sessionId to the client. The client should use this session id for all
+    future requests.
+
+    The server may refuse a client that does not use the same transport method
+    for all media streams.
+
+    The server stores all client port pairs in the server client session along
+    with the transport method.
+
+    ex:
+
+      For an on-demand stream the server could construct a (minimal) RTP GStreamer 
+      pipeline for the client as follows (for an mp3 stream):
+    
+      +---------+    +-----------+    +------------+    +-------------+
+      | filesrc |    | rtpmp3enc |    | rtpsession |    | udpsink     |
+      |         |    |           |    |            |    |   host=XXX  |
+      |         |    |           |    |            |    |   port=5000 |
+      |        src--sink        src--rtpsink   rtpsrc--sink           |
+      +---------+    +-----------+    |            |    +-------------+
+                                      |            |    +-------------+
+                                      |            |    | udpsink     |
+                                      |            |    |   host=XXX  |
+                                      |            |    |   port=5001 |
+                                      |       rtspsrc--sink           |
+                                      +------------+    +-------------+
+
+      The server would set the above pipeline to PAUSE to make sure no data
+      is send to the client yet.
+
+      optionally udpsrc elements can be configured to receive client RTP and
+      RTSP messages.
+
+    ex:
+
+      For a live stream the server could construct a (minimal) RTP GStreamer 
+      pipeline for the clients as follows (for an mp3 stream):
+    
+      +---------+    +--------+    +-----------+    +------------+    +--------------+
+      | source  |    | mp3enc |    | rtpmp3enc |    | rtpsession |    | multiudpsink |
+      |         |    |        |    |           |    |            |    |   host=...   |
+      |         |    |        |    |           |    |            |    |   port=...   |
+      |        src--sink     src--sink        src--rtpsink   rtpsrc--sink            |
+      +---------+    +--------+    +-----------+    |            |    +--------------+
+                                                    |            |    +--------------+
+                                                    |            |    | multiudpsink |
+                                                    |            |    |   host=...   |
+                                                    |            |    |   port=...   |
+                                                    |       rtspsrc--sink            |
+                                                    +------------+    +--------------+
+
+      Media data is streamed to clients by adding the client host and port numbers
+      to the multiudpsinks.
+
+      optionally udpsrc elements can be configured to receive client RTP and
+      RTSP messages.
+     
+ - The server must support the PLAY command to start playback of the configured
+   media streams.
+
+    >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
+    >> CSeq: 2
+    >> Session: 5d5cb94413288ccd
+    >>
+    << RTSP/1.0 200 OK
+    << CSeq: 2
+    << Date: Wed May 11 13:21:43 2005 GMT
+    << Session: 5d5cb94413288ccd
+    <<
+
+    Using the Session: header field, the server finds the pipeline of the session
+    to PLAY and sets the pipeline to PLAYING at which point the client receives
+    the media stream data.
+
+    In case of a live stream, the server adds the port numbers to a multiudpsink
+    element.
+
+ - The server must support the TEARDOWN command to stop playback and free the
+   session of a client.
+
+    >> TEARDOWN rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
+    >> CSeq: 4
+    >> Session: 5d5cb94413288ccd
+    >>
+    << RTSP/1.0 200 OK
+    << CSeq: 4
+    << Date: Wed May 11 13:21:43 2005 GMT
+    <<
+
+    The server destroys the client pipeline in case of an on-demand stream or
+    removes the client ports from the multiudpsinks. This effectively stops
+    streaming to the client.
+
+