diff --git a/ChangeLog b/ChangeLog index 08090354d3..752ab50dfd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2005-08-15 Wim Taymans + + * gst/rtsp/README: + Added rtsp server implementation docs. + 2005-08-14 Thomas Vander Stichele * ext/aalib/gstaasink.c: diff --git a/gst/rtsp/README b/gst/rtsp/README index 2f7fde89aa..820c17d327 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> - + +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. + +