"Fossies" - the Fresh Open Source Software Archive

Member "gst-plugins-good-1.20.3/gst/rtsp/README" (15 Jun 2022, 14396 Bytes) of package /linux/misc/gst-plugins-good-1.20.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 RTSP source 
    2 -----------
    3 
    4 The RTSP source establishes a connection to an RTSP server and sets up
    5 the UDP sources and RTP session handlers.
    6 
    7 An RTSP session is created as follows:
    8 
    9 - Parse RTSP URL:
   10 
   11    ex:
   12      rtsp://thread:5454/south-rtsp.mp3
   13 
   14 - Open a connection to the server with the url. All further conversation with
   15   the server should be done with this connection. Each request/reply has
   16   a CSeq number added to the header.
   17 
   18 - Send a DESCRIBE request for the url. We currently support a response in
   19   SDP.
   20 
   21   ex:
   22 
   23     >> DESCRIBE rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
   24     >> Accept: application/sdp
   25     >> CSeq: 0
   26     >>
   27     << RTSP/1.0 200 OK
   28     << Content-Length: 84
   29     << Content-Type: application/sdp
   30     << CSeq: 0
   31     << Date: Wed May 11 13:09:37 2005 GMT
   32     <<
   33     << v=0
   34     << o=- 0 0 IN IP4 192.168.1.1
   35     << s=No Title
   36     << m=audio 0 RTP/AVP 14
   37     << a=control:streamid=0
   38 
   39 - Parse the SDP message, for each stream (m=) we create an GstRTPStream. We need
   40   to allocate two local UDP ports for receiving the RTP and RTCP data because we
   41   need to send the port numbers to the server in the next request.
   42 
   43   In RTSPSrc we first create an element that can handle the udp://0.0.0.0:0 uri. This
   44   will create an udp source element with a random port number. We get the port
   45   number by getting the "port" property of the element after setting the element to 
   46   PAUSED. This element is used for the RTP packets and has to be an even number. If
   47   the random port number is not an even number we retry to allocate a new udp source.
   48 
   49   We then create another UDP source element with the next (uneven) port number to 
   50   receive the RTCP packet on. After this step we have two udp ports we can use to
   51   accept RTP packets.
   52 
   53     +-----------------+
   54     | +------------+  |
   55     | | udpsrc0    |  |
   56     | |  port=5000 |  |
   57     | +------------+  |
   58     | +------------+  |
   59     | | udpsrc1    |  |
   60     | |  port=5001 |  |
   61     | +------------+  |
   62     +-----------------+
   63 
   64 - Send a SETUP message to the server with the RTP ports. We get the setup URI from
   65   the a= attribute in the SDP message. This can be an absolute URL or a relative
   66   url.
   67 
   68   ex:
   69 
   70     >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
   71     >> CSeq: 1
   72     >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
   73     >>
   74     << RTSP/1.0 200 OK
   75     << Transport: RTP/AVP/UDP;unicast;client_port=5000-5001;server_port=6000-6001
   76     << CSeq: 1
   77     << Date: Wed May 11 13:21:43 2005 GMT
   78     << Session: 5d5cb94413288ccd
   79     <<
   80 
   81   The client needs to send the local ports to the server along with the supported 
   82   transport types. The server selects the final transport which it returns in the
   83   Transport header field. The server also includes its ports where RTP and RTCP
   84   messages can be sent to.
   85 
   86   In the above example UDP was chosen as a transport. At this point the RTSPSrc element
   87   will further configure its elements to process this stream.
   88 
   89   The RTSPSrc will create and connect an RTP session manager element and will
   90   connect it to the src pads of the udp element. The data pad from the RTP session 
   91   manager is ghostpadded to RTPSrc.
   92   The RTCP pad of the rtpdec is routed to a new udpsink that sends data to the RTCP
   93   port of the server as returned in the Transport: header field.
   94 
   95     +---------------------------------------------+
   96     | +------------+                              |
   97     | | udpsrc0    |   +--------+                 |
   98     | |  port=5000 ----- rtpdec --------------------
   99     | +------------+   |        |                 |
  100     | +------------+   |        |  +------------+ |
  101     | | udpsrc1    ----- RTCP   ---- udpsink    | |
  102     | |  port=5001 |   +--------+  |  port=6001 | |
  103     | +------------+               +------------+ |
  104     +---------------------------------------------+
  105 
  106   The output type of rtpdec is configured as the media type specified in the SDP
  107   message. 
  108 
  109 - All the elements are set to PAUSED/PLAYING and the PLAY RTSP message is
  110   sent.
  111 
  112     >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
  113     >> CSeq: 2
  114     >> Session: 5d5cb94413288ccd
  115     >>
  116     << RTSP/1.0 200 OK
  117     << CSeq: 2
  118     << Date: Wed May 11 13:21:43 2005 GMT
  119     << Session: 5d5cb94413288ccd
  120     <<
  121 
  122 - The udp source elements receive data from that point and the RTP/RTCP messages
  123   are processed by the elements.
  124 
  125 - In the case of interleaved mode, the SETUP method yields:
  126 
  127     >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
  128     >> CSeq: 1
  129     >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
  130     >>
  131     << RTSP/1.0 200 OK
  132     << Transport: RTP/AVP/TCP;interleaved=0-1
  133     << CSeq: 1
  134     << Date: Wed May 11 13:21:43 2005 GMT
  135     << Session: 5d5cb94413288ccd
  136     <<
  137 
  138   This means that RTP/RTCP messages will be sent on channel 0/1 respectively and that
  139   the data will be received on the same connection as the RTSP connection.
  140 
  141   At this point, we remove the UDP source elements as we don't need them anymore. We
  142   set up the rtpsess session manager element though as follows:
  143 
  144     +---------------------------------------------+
  145     | +------------+                              |
  146     | | _loop()    |   +--------+                 |
  147     | |            ----- rtpses --------------------
  148     | |            |   |        |                 |
  149     | |            |   |        |  +------------+ |
  150     | |            ----- RTCP   ---- udpsink    | |
  151     | |            |   +--------+  |  port=6001 | |
  152     | +------------+               +------------+ |
  153     +---------------------------------------------+
  154 
  155   We start an interal task to start reading from the RTSP connection waiting
  156   for data. The received data is then pushed to the rtpdec element.
  157 
  158   When reading from the RTSP connection we receive data packets in the
  159   following layout (see also RFC2326)
  160 
  161     $<1 byte channel><2 bytes length, big endian><length bytes of data>
  162 
  163 
  164 RTSP server
  165 -----------
  166 
  167 An RTSP server listen on a port (default 554) for client connections. The client
  168 typically keeps this channel open during the RTSP session to instruct the server
  169 to pause/play/stop the stream.
  170 
  171 The server exposes a stream consisting of one or more media streams using an
  172 URL. The media streams are typically audio and video.
  173 
  174   ex:
  175      rtsp://thread:5454/alien-rtsp.mpeg
  176 
  177      exposes an audio/video stream. The video is mpeg packetized in RTP and
  178      the audio is mp3 in RTP.
  179 
  180 The streaming server typically uses a different channel to send the media
  181 data to clients, typically using RTP over UDP. It is also possible to stream
  182 the data to the client using the initial RTSP TCP session (the interleaved
  183 mode). This last mode is useful when the client is behind a firewall but
  184 does not take advantage of the RTP/UDP features.
  185 
  186 In both cases, media data is send to the clients in an unmultiplexed format
  187 packetized as RTP packets.
  188 
  189 The streaming server has to negotiate a connection protocol for each of the
  190 media streams with the client.
  191 
  192 Minimal server requirements:
  193 
  194 - The server should copy the CSeq header field in a client request to the
  195   response so that the client can match the response to the request.
  196 
  197 - The server should keep a session for each client after the client issued
  198   a SETUP command. The client should use the same session id for all future
  199   request to this server.
  200 
  201 - the server must support an OPTIONS request send over the RTSP connection.
  202 
  203     >> OPTIONS * RTSP/1.0
  204     >> CSeq: 1
  205     >>
  206     << RTSP/1.0 200 OK
  207     << CSeq: 1
  208     << Date: Wed May 11 13:21:43 2005 GMT
  209     << Session: 5d5cb94413288ccd
  210     << Public: DESCRIBE, SETUP, TEARDOWN, PLAY
  211     <<
  212 
  213    The OPTIONS request should list all supported methods on the server.
  214  
  215  - The server should support the DESCRIBE method.
  216 
  217     >> DESCRIBE rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
  218     >> Accept: application/sdp
  219     >> CSeq: 2
  220     >>
  221     << RTSP/1.0 200 OK
  222     << Content-Length: 84
  223     << Content-Type: application/sdp
  224     << CSeq: 2
  225     << Date: Wed May 11 13:09:37 2005 GMT
  226     <<
  227     << v=0
  228     << o=- 0 0 IN IP4 192.168.1.1
  229     << s=No Title
  230     << m=audio 0 RTP/AVP 14
  231     << a=control:streamid=0
  232 
  233     The client issues a DESCRIBE command for a specific URL that corresponds
  234     to an available stream. The client will also send an Accept header to
  235     list its supported formats. 
  236 
  237     The server answers this request with a reply in one of the client supported
  238     formats (application/sdp is the most common). The server typically sends a
  239     fixed reply to all clients for each configured stream.
  240 
  241  - The server must support the SETUP command to configure the media streams 
  242    that were listed in the DESCRIBE command.
  243 
  244     >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
  245     >> CSeq: 3
  246     >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
  247     >>
  248     << RTSP/1.0 200 OK
  249     << Transport: RTP/AVP/UDP;unicast;client_port=5000-5001;server_port=6000-6001
  250     << CSeq: 3
  251     << Date: Wed May 11 13:21:43 2005 GMT
  252     << Session: 5d5cb94413288ccd
  253 
  254     The client will send a SETUP command for each of the streams listed in the 
  255     DESCRIBE reply. For sdp will use a URL as listed in the a=control: property.
  256 
  257     The client will list the supported transports in the Transport: header field.
  258     Each transport is separated with a comma (,) and listed in order of preference.
  259     The server has to select the first supported transport.
  260  
  261     In the above example 3 transport are listed:
  262 
  263        RTP/AVP/UDP;unicast;client_port=5000-5001
  264 
  265          The client will accept RTP over UDP on the port pair 5000-5001. Port
  266 	 5000 will accept the RTP packets, 5001 the RTSP packets send by the
  267 	 server.
  268        
  269        RTP/AVP/UDP;multicast
  270 
  271          The client can join a multicast group for the specific media stream.
  272 	 The port numbers of the multicast group it will connect to have to
  273 	 be specified by the server in the reply.
  274        
  275        RTP/AVP/TCP
  276 
  277          the client can accept RTP packets interleaved on the RTSP connection.
  278 
  279     The server selects a supported transport an allocates an RTP port pair to
  280     receive RTP and RTSP data from the client. This last step is optional when
  281     the server does not accept RTP data.
  282 
  283     The server should allocate a session for the client and should send the
  284     sessionId to the client. The client should use this session id for all
  285     future requests.
  286 
  287     The server may refuse a client that does not use the same transport method
  288     for all media streams.
  289 
  290     The server stores all client port pairs in the server client session along
  291     with the transport method.
  292 
  293     ex:
  294 
  295       For an on-demand stream the server could construct a (minimal) RTP GStreamer 
  296       pipeline for the client as follows (for an mp3 stream):
  297     
  298       +---------+    +-----------+    +------------+    +-------------+
  299       | filesrc |    | rtpmp3enc |    | rtpsession |    | udpsink     |
  300       |         |    |           |    |            |    |   host=XXX  |
  301       |         |    |           |    |            |    |   port=5000 |
  302       |        src--sink        src--rtpsink   rtpsrc--sink           |
  303       +---------+    +-----------+    |            |    +-------------+
  304                                       |            |    +-------------+
  305                                       |            |    | udpsink     |
  306                                       |            |    |   host=XXX  |
  307                                       |            |    |   port=5001 |
  308                                       |       rtspsrc--sink           |
  309                                       +------------+    +-------------+
  310 
  311       The server would set the above pipeline to PAUSE to make sure no data
  312       is sent to the client yet.
  313 
  314       optionally udpsrc elements can be configured to receive client RTP and
  315       RTSP messages.
  316 
  317     ex:
  318 
  319       For a live stream the server could construct a (minimal) RTP GStreamer 
  320       pipeline for the clients as follows (for an mp3 stream):
  321     
  322       +---------+    +--------+    +-----------+    +------------+    +--------------+
  323       | source  |    | mp3enc |    | rtpmp3enc |    | rtpsession |    | multiudpsink |
  324       |         |    |        |    |           |    |            |    |   host=...   |
  325       |         |    |        |    |           |    |            |    |   port=...   |
  326       |        src--sink     src--sink        src--rtpsink   rtpsrc--sink            |
  327       +---------+    +--------+    +-----------+    |            |    +--------------+
  328                                                     |            |    +--------------+
  329                                                     |            |    | multiudpsink |
  330                                                     |            |    |   host=...   |
  331                                                     |            |    |   port=...   |
  332                                                     |       rtspsrc--sink            |
  333                                                     +------------+    +--------------+
  334 
  335       Media data is streamed to clients by adding the client host and port numbers
  336       to the multiudpsinks.
  337 
  338       optionally udpsrc elements can be configured to receive client RTP and
  339       RTSP messages.
  340      
  341  - The server must support the PLAY command to start playback of the configured
  342    media streams.
  343 
  344     >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
  345     >> CSeq: 2
  346     >> Session: 5d5cb94413288ccd
  347     >>
  348     << RTSP/1.0 200 OK
  349     << CSeq: 2
  350     << Date: Wed May 11 13:21:43 2005 GMT
  351     << Session: 5d5cb94413288ccd
  352     <<
  353 
  354     Using the Session: header field, the server finds the pipeline of the session
  355     to PLAY and sets the pipeline to PLAYING at which point the client receives
  356     the media stream data.
  357 
  358     In case of a live stream, the server adds the port numbers to a multiudpsink
  359     element.
  360 
  361  - The server must support the TEARDOWN command to stop playback and free the
  362    session of a client.
  363 
  364     >> TEARDOWN rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
  365     >> CSeq: 4
  366     >> Session: 5d5cb94413288ccd
  367     >>
  368     << RTSP/1.0 200 OK
  369     << CSeq: 4
  370     << Date: Wed May 11 13:21:43 2005 GMT
  371     <<
  372 
  373     The server destroys the client pipeline in case of an on-demand stream or
  374     removes the client ports from the multiudpsinks. This effectively stops
  375     streaming to the client.
  376 
  377