\section{Method Definitions}
\label{sec:methods}

The {\tt method} token indicates the method to be performed on the
resource identified by the {\tt Request-URI}.  The method is
case-sensitive.  New methods may be defined in the future.  Method names
may not start with a \$ character (decimal 24) and must be a
\header{token}.  Methods are summarized in Table~\ref{tab:methods}.

\begin{table}[htpb]
\begin{center}
\begin{tabular}{llll}
method & direction & object & requirement\\
\hline
{\DESCRIBE}       & \CS      & P,S & recommended\\
{\ANNOUNCE}       & \CS, \SC & P,S & optional\\
{\GETPARAMETER}   & \CS, \SC & P,S & optional\\
{\OPTIONS}        & \CS, \SC & P,S & required (\SC: optional)\\
{\PAUSE}          & \CS      & P,S & recommended\\
{\PLAY}           & \CS      & P,S & required\\
{\RECORD}         & \CS      & P,S & optional\\
{\REDIRECT}       & \SC      & P,S & optional\\
{\SETUP}          & \CS      & S   & required\\
{\SETPARAMETER}   & \CS, \SC & P,S & optional\\
{\TEARDOWN}       & \CS      & P,S & required\\
\end{tabular}
\end{center}
\caption{Overview of RTSP methods, their direction, and what objects (P:
presentation, S: stream) they operate on}
\label{tab:methods}
\end{table}

Notes on Table~\ref{tab:methods}:  {\PAUSE} is recommended, but not
required in that a fully functional server can be built that does not
support this method, for example, for live feeds.  If a server does not
support a particular method, it {\MUST} return 501 (Not Implemented) and
a client {\SHOULD} not try this method again for this server.

\subsection{\OPTIONS}
\label{sec:OPTIONS}

The behavior is equivalent to that described in [H9.2].  An {\OPTIONS}
request may be issued at any time, e.g., if the client is about to try a
nonstandard request.  It does not influence server state.

Example:

\begin{verbatim}
  C->S:  OPTIONS * RTSP/1.0
         CSeq: 1
         Require: implicit-play
         Proxy-Require: gzipped-messages

  S->C:  RTSP/1.0 200 OK
         CSeq: 1
         Public: DESCRIBE, SETUP, TEARDOWN, PLAY, PAUSE
\end{verbatim}

Note that these are necessarily fictional features (one would hope that
we would not purposefully overlook a truly useful feature just so that
we could have a strong example in this section).

\subsection{\DESCRIBE}
\label{sec:DESCRIBE}

The {\DESCRIBE} method retrieves the description of a presentation or
media object identified by the request URL from a server.  It may use
the \header{Accept} header to specify the description formats that the
client understands.  The server responds with a {\em description} of the
requested resource.  The {\DESCRIBE} reply-response pair constitutes the
media initialization phase of RTSP.

Example:

\begin{verbatim}
  C->S: DESCRIBE rtsp://server.example.com/fizzle/foo RTSP/1.0
        CSeq: 312
        Accept: application/sdp, application/rtsl, application/mheg

  S->C: RTSP/1.0 200 OK
        CSeq: 312
        Date: 23 Jan 1997 15:35:06 GMT
        Content-Type: application/sdp
        Content-Length: 376

        v=0 
        o=mhandley 2890844526 2890842807 IN IP4 126.16.64.4 
        s=SDP Seminar 
        i=A Seminar on the session description protocol 
        u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps 
        e=mjh@isi.edu (Mark Handley) 
        c=IN IP4 224.2.17.12/127 
        t=2873397496 2873404696 
        a=recvonly 
        m=audio 3456 RTP/AVP 0 
        m=video 2232 RTP/AVP 31 
        m=whiteboard 32416 UDP WB 
        a=orient:portrait 
\end{verbatim}

The {\DESCRIBE} response {\MUST} contain all media initialization
information for the resource(s) that it describes.  If a media client
obtains a presentation description from a source other than {\DESCRIBE}
and that description contains a complete set of media initialization
parameters, the client {\SHOULD} use those parameters and not then
request a description for the same media via RTSP.

Additionally, servers {\SHOULDNOT} use the {\DESCRIBE} response as a
means of media indirection.

\motivation{By forcing a {\DESCRIBE} response to contain all media
initialization for the set of streams that it describes, and
discouraging use of {\DESCRIBE} for media indirection, we avoid looping
problems that might result from other approaches.

Media initialization is a requirement for any RTSP-based system, but the
RTSP specification does not dictate that this must be done via the
{\DESCRIBE} method.  There are three ways that an RTSP client may
receive initialization information:

\begin{itemize}

\item via RTSP's {\DESCRIBE} method;

\item via some other protocol (HTTP, email attachment, etc.);

\item via the command line or standard input (thus working as a browser
helper application launched with an SDP file or other media initialization
format).

\end{itemize}

It is {\RECOMMENDED} that minimal servers support the {\DESCRIBE}
method, and highly recommended that minimal clients support the ability
to act as a ``helper application'' that accepts a media initialization
file from standard input, command line, and/or other means that are
appropriate to the operating environment of the client.
}

\subsection{\ANNOUNCE}
\label{sec:ANNOUNCE}

The {\ANNOUNCE} method serves two purposes:

When sent from client to server, {\ANNOUNCE} posts the description of a
presentation or media object identified by the request URL to a server. 
When sent from server to client, {\ANNOUNCE} updates the session
description in real-time.

If a new media stream is added to a presentation (e.g., during a live
presentation), the whole presentation description should be sent again,
rather than just the additional components, so that components can be
deleted. 

Example:

\begin{verbatim}
  C->S: ANNOUNCE rtsp://server.example.com/fizzle/foo RTSP/1.0
        CSeq: 312
        Date: 23 Jan 1997 15:35:06 GMT
        Session: 47112344
        Content-Type: application/sdp
        Content-Length: 332

        v=0 
        o=mhandley 2890844526 2890845468 IN IP4 126.16.64.4 
        s=SDP Seminar 
        i=A Seminar on the session description protocol 
        u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps 
        e=mjh@isi.edu (Mark Handley) 
        c=IN IP4 224.2.17.12/127 
        t=2873397496 2873404696 
        a=recvonly 
        m=audio 3456 RTP/AVP 0 
        m=video 2232 RTP/AVP 31 

  S->C: RTSP/1.0 200 OK
        CSeq: 312
\end{verbatim}

\subsection{\SETUP}
\label{sec:SETUP}

The {\SETUP} request for a URI specifies the transport mechanism to be
used for the streamed media.  A client can issue a {\SETUP} request for
a stream that is already playing to change transport parameters, which a
server {\MAY} allow.  If it does not allow this, it {\MUST} respond with
error 455 (Method Not Valid In This State).  For the benefit of any
intervening firewalls, a client must indicate the transport parameters
even if it has no influence over these parameters, for example, where
the server advertises a fixed multicast address.

\motivation{Since {\SETUP} includes all transport initialization
information, firewalls and other intermediate network devices (which
need this information) are spared the more arduous task of parsing the
{\DESCRIBE} response, which has been reserved for media initialization.}

The \header{Transport} header specifies the transport parameters acceptable
to the client for data transmission; the response will contain the
transport parameters selected by the server.

\begin{verbatim}
  C->S: SETUP rtsp://example.com/foo/bar/baz.rm RTSP/1.0
        CSeq: 302
        Transport: RTP/AVP;unicast;client_port=4588-4589

  S->C: RTSP/1.0 200 OK
        CSeq: 302
        Date: 23 Jan 1997 15:35:06 GMT
        Session: 47112344
        Transport: RTP/AVP;unicast;
          client_port=4588-4589;server_port=6256-6257
\end{verbatim}

The server generates session identifiers in response to {\SETUP}
requests.  If a {\SETUP} request to a server includes a session
identifier, the server {\MUST} bundle this setup request into the
existing session or return error 459 (Aggregate Operation Not Allowed)
(see Section~\ref{sec:error459}).

\subsection{\PLAY}
\label{sec:PLAY}

The {\PLAY} method tells the server to start sending data via the
mechanism specified in {\SETUP}.  A client {\MUSTNOT} issue a {\PLAY}
request until any outstanding {\SETUP} requests have been acknowledged
as successful. 

The {\PLAY} request positions the normal play time to the
beginning of the range specified and delivers stream data until the end
of the range is reached.  {\PLAY} requests may be pipelined (queued); a
server {\MUST} queue {\PLAY} requests to be executed in order.  That is,
a {\PLAY} request arriving while a previous {\PLAY} request is still
active is delayed until the first has been completed.  \motivation{This
allows precise editing.} For example, regardless of how closely spaced
the two {\PLAY} requests in the example below arrive, the server will
first play seconds 10 through 15, then, immediately following, seconds
20 to 25, and finally seconds 30 through the end.

\begin{verbatim}
  C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0
        CSeq: 835
        Session: 12345678
        Range: npt=10-15

  C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0
        CSeq: 836
        Session: 12345678
        Range: npt=20-25

  C->S: PLAY rtsp://audio.example.com/audio RTSP/1.0
        CSeq: 837
        Session: 12345678
        Range: npt=30-
\end{verbatim}

See the description of the {\PAUSE} request for further examples.

A {\PLAY} request without a \header{Range} header is legal.  It starts
playing a stream from the beginning unless the stream has been paused. 
If a stream has been paused via {\PAUSE}, stream delivery resumes at the
pause point.  If a stream is playing, such a {\PLAY} request causes no
further action and can be used by the client to test server liveness.

The \header{Range} header may also contain a \header{time} parameter. 
This parameter specifies a time in UTC at which the playback should
start.  If the message is received after the specified time, playback is
started immediately.  The \header{time} parameter may be used to aid in
synchronization of streams obtained from different sources.

For a on-demand stream, the server replies with the actual range that
will be played back.  This may differ from the requested range if
alignment of the requested range to valid frame boundaries is required
for the media source.  If no range is specified in the request, the
current position is returned in the reply.  The unit of the range in the
reply is the same as that in the request.

After playing the desired range, the presentation is automatically
paused, as if a {\PAUSE} request had been issued.

The following example plays the whole presentation starting at SMPTE
time code 0:10:20 until the end of the clip.  The playback is to start
at 15:36 on 23 Jan 1997.

\begin{verbatim}
  C->S: PLAY rtsp://audio.example.com/twister.en RTSP/1.0
        CSeq: 833
        Session: 12345678
        Range: smpte=0:10:20-;time=19970123T153600Z

  S->C: RTSP/1.0 200 OK
        CSeq: 833
        Date: 23 Jan 1997 15:35:06 GMT
        Range: smpte=0:10:22-;time=19970123T153600Z
\end{verbatim}

For playing back a recording of a live presentation, it may be desirable
to use \header{clock} units:

\begin{verbatim}
  C->S: PLAY rtsp://audio.example.com/meeting.en RTSP/1.0
        CSeq: 835
        Session: 12345678
        Range: clock=19961108T142300Z-19961108T143520Z
	
  S->C: RTSP/1.0 200 OK
        CSeq: 835
        Date: 23 Jan 1997 15:35:06 GMT
	  
\end{verbatim}

A media server only supporting playback {\MUST} support the \header{npt}
format and {\MAY} support the \header{clock} and \header{smpte} formats.

\subsection{\PAUSE}
\label{sec:PAUSE}

The {\PAUSE} request causes the stream delivery to be interrupted
(halted) temporarily.  If the request URL names a stream, only playback
and recording of that stream is halted.  For example, for audio, this is
equivalent to muting.  If the request URL names a presentation or group
of streams, delivery of all currently active streams within the
presentation or group is halted.  After resuming playback or recording,
synchronization of the tracks {\MUST} be maintained.  Any server
resources are kept, though servers {\MAY} close the session and free
resources after being paused for the duration specified with the
\header{timeout} parameter of the \header{Session} header in the
{\SETUP} message.

Example:

\begin{verbatim}
  C->S: PAUSE rtsp://example.com/fizzle/foo RTSP/1.0
        CSeq: 834
        Session: 12345678

  S->C: RTSP/1.0 200 OK
        CSeq: 834
        Date: 23 Jan 1997 15:35:06 GMT
\end{verbatim}

The {\PAUSE} request may contain a \header{Range} header specifying when
the stream or presentation is to be halted.  We refer to this point as
the ``pause point''.  The header must contain exactly one value rather
than a time range.  The normal play time for the stream is set to the
pause point.  The pause request becomes effective the first time the
server is encountering the time point specified in any of the currently
pending {\PLAY} requests.  If the \header{Range} header specifies a time
outside any currently pending {\PLAY} requests, the error 457 (Invalid
Range) is returned.  If a media unit (such as an audio or video frame)
starts presentation at exactly the pause point, it is not played or
recorded.  If the \header{Range} header is missing, stream delivery is
interrupted immediately on receipt of the message and the pause point is
set to the current normal play time. 

A {\PAUSE} request discards all queued {\PLAY} requests.  However, the
pause point in the media stream {\MUST} be maintained.  A subsequent
{\PLAY} request without \header{Range} header resumes from the pause
point.

For example, if the server has play requests for ranges 10 to 15 and 20
to 29 pending and then receives a pause request for NPT 21, it would
start playing the second range and stop at NPT 21.  If the pause request
is for NPT 12 and the server is playing at NPT 13 serving the first play
request, the server stops immediately.  If the pause request is for NPT
16, the server stops after completing the first play request and
discards the second play request.

As another example, if a server has received requests to play ranges 10
to 15 and then 13 to 20 (that is, overlapping ranges), the {\PAUSE}
request for NPT=14 would take effect while the server plays the first
range, with the second {\PLAY} request effectively being ignored,
assuming the {\PAUSE} request arrives before the server has started
playing the second, overlapping range.  Regardless of when the PAUSE
request arrives, it sets the NPT to 14.

If the server has already sent data beyond the time specified in the
\header{Range} header, a {\PLAY} would still resume at that point
in time, as it is assumed that the client has discarded data after that
point.  This ensures continuous pause/play cycling without gaps.

\subsection{\TEARDOWN}
\label{sec:TEARDOWN}

The {\TEARDOWN} request stops the stream delivery for the given URI,
freeing the resources associated with it.  If the URI is the
presentation URI for this presentation, any RTSP session identifier
associated with the session is no longer valid.  Unless all transport
parameters are defined by the session description, a {\SETUP} request
has to be issued before the session can be played again.

Example:

\begin{verbatim}
  C->S: TEARDOWN rtsp://example.com/fizzle/foo RTSP/1.0
        CSeq: 892
        Session: 12345678

  S->C: RTSP/1.0 200 OK
        CSeq: 892
\end{verbatim}

\subsection{\GETPARAMETER}
\label{sec:GET_PARAMETER}

The {\GETPARAMETER} request retrieves the value of a parameter of a
presentation or stream specified in the URI.  The content of the reply
and response is left to the implementation.  {\GETPARAMETER} with no
entity body may be used to test client or server liveness (``ping'').

Example:

\begin{verbatim}
  S->C: GET_PARAMETER rtsp://example.com/fizzle/foo RTSP/1.0
        CSeq: 431
        Content-Type: text/parameters
        Session: 12345678
        Content-Length: 15

        packets_received
        jitter

  C->S: RTSP/1.0 200 OK
        CSeq: 431
        Content-Length: 46
        Content-Type: text/parameters
	
        packets_received: 10
        jitter: 0.3838
\end{verbatim}

\motivation{The ``text/parameters'' section is only an example type for
parameter.  This method is intentionally loosely defined with the
intention that the reply content and response content will be defined
after further experimentation.}

\subsection{\SETPARAMETER}
\label{sec:SET_PARAMETER}

This method requests to set the value of a parameter for a presentation
or stream specified by the URI.

A request {\SHOULD} only contain a single parameter to allow the client
to determine why a particular request failed.  If the request contains
several parameters, the server {\MUST} only act on the request if all of
the parameters can be set successfully.  A server MUST allow a parameter
to be set repeatedly to the same value, but it MAY disallow changing
parameter values. 

Note:  transport parameters for the media stream {\MUST} only be set
with the {\SETUP} command.  \motivation{Restricting setting transport
parameters to {\SETUP} is for the benefit of firewalls.}

\motivation{The parameters are split in a fine-grained fashion so that
there can be more meaningful error indications.  However, it may make
sense to allow the setting of several parameters if an atomic setting is
desirable.  Imagine device control where the client does not want the
camera to pan unless it can also tilt to the right angle at the same
time.}

Example:

\begin{verbatim}
  C->S: SET_PARAMETER rtsp://example.com/fizzle/foo RTSP/1.0
        CSeq: 421
	Content-length: 20
        Content-type: text/parameters

        barparam: barstuff

  S->C: RTSP/1.0 451 Parameter Not Understood
        CSeq: 421
        Content-length: 10
        Content-type: text/parameters

        barparam
\end{verbatim}

\motivation{The ``text/parameters'' section is only an example type for
parameter.  This method is intentionally loosely defined with the
intention that the reply content and response content will be defined
after further experimentation.}

\subsection{\REDIRECT}
\label{sec:REDIRECT}

A redirect request informs the client that it must connect to another
server location.  It contains the mandatory header \header{Location},
which indicates that the client should issue requests for that URL.  It
may contain the parameter \header{Range}, which indicates when the
redirection takes effect.  If the client wants to continue to send or
receive media for this URI, the client {\MUST} issue a {\TEARDOWN}
request for the current session and a {\SETUP} for the new session at
the designated host.

This example request redirects traffic for this URI to the new server at
the given play time:

\begin{verbatim}
  S->C: REDIRECT rtsp://example.com/fizzle/foo RTSP/1.0
        CSeq: 732
        Location: rtsp://bigserver.com:8001
        Range: clock=19960213T143205Z-
\end{verbatim}

\subsection{\RECORD}
\label{sec:RECORD}

This method initiates recording a range of media data according to the
presentation description.  The timestamp reflects start and end time
(UTC).  If no time range is given, use the start or end time provided in
the presentation description.  If the session has already started,
commence recording immediately.  

The server decides whether to store the recorded data under the
request-URI or another URI.  If the server does not use the request-URI,
the response SHOULD be 201 (Created) and contain an entity which
describes the status of the request and refers to the new resource, and
a \header{Location} header.

A media server supporting recording of live presentations {\MUST}
support the clock range format; the smpte format does not make sense.

In this example, the media server was previously invited to the
conference indicated.

\begin{verbatim}
  C->S: RECORD rtsp://example.com/meeting/audio.en RTSP/1.0
        CSeq: 954
        Session: 12345678
        Conference: 128.16.64.19/32492374
\end{verbatim}

\subsection{Embedded (Interleaved) Binary Data}
\label{sec:binary}

Certain firewall designs and other circumstances may force a server to
interleave RTSP methods and stream data.  This interleaving should
generally be avoided unless necessary since it complicates client and
server operation and imposes additional overhead. Interleaved binary
data SHOULD only be used if RTSP is carried over TCP.

Stream data such as RTP packets is encapsulated by an ASCII dollar sign
(24 decimal), followed by a one-byte channel identifier, followed by the
length of the encapsulated binary data as a binary, two-byte integer in
network byte order.  The stream data follows immediately afterwards,
without a CRLF, but including the upper-layer protocol headers.  Each \$
block contains exactly one upper-layer protocol data unit, e.g., one RTP
packet.

The channel identifier is defined in the \header{Transport} header with
the \header{interleaved} parameter(Section \ref{sec:Transport}). 

When the transport choice is RTP, RTCP messages are also interleaved by
the server over the TCP connection.  As a default, RTCP packets are sent
on the first available channel higher than the RTP channel.  The client
MAY explicitly request RTCP packets on another channel.  This is done by
specifying two channels in the \header{interleaved} parameter of the
\header{Transport} header(Section \ref{sec:Transport}).

\motivation {RTCP is needed for synchronization when two or more streams
are interleaved in such a fashion.  Also, this provides a convenient way
to tunnel RTP/RTCP packets through the TCP control connection when
required by the network configuration and transfer them onto UDP when
possible.}

\begin{verbatim}
  C->S: SETUP rtsp://foo.com/bar.file RTSP/1.0
        CSeq: 2
        Transport: RTP/AVP/TCP;interleaved=0-1

  S->C: RTSP/1.0 200 OK
        CSeq: 2
        Date: 05 Jun 1997 18:57:18 GMT
        Transport: RTP/AVP/TCP;interleaved=0-1
        Session: 12345678

  C->S: PLAY rtsp://foo.com/bar.file RTSP/1.0
        CSeq: 3
        Session: 12345678

  S->C: RTSP/1.0 200 OK
        CSeq: 3
        Session: 12345678
        Date: 05 Jun 1997 18:59:15 GMT
        RTP-Info: url=rtsp://foo.com/bar.file;
          seq=232433;rtptime=972948234
       
  S->C: $\000{2 byte length}{"length" bytes data, w/RTP header}
  S->C: $\000{2 byte length}{"length" bytes data, w/RTP header}
  S->C: $\001{2 byte length}{"length" bytes  RTCP packet}
\end{verbatim}
