RFC 7826
Real-Time Streaming Protocol Version 2.0
18.34. Proxy-Authenticate
The Proxy-Authenticate response-header field MUST be included as part of a 407 (Proxy Authentication Required) response. The field-value consists of a challenge that indicates the authentication scheme and parameters applicable to the proxy for this Request-URI. The definition of the header is in [RFC7235], and any applicable HTTP authentication schemes appear in other RFCs, such as Digest [RFC7616] and Basic [RFC7617]. The HTTP access authentication process is described in [RFC7235]. This header MUST only be used in response messages related to client- to-server requests.18.35. Proxy-Authentication-Info
The Proxy-Authentication-Info response-header is used by the proxy to communicate some information regarding the successful authentication to the proxy in the message response in some authentication schemes, such as the Digest scheme [RFC7616]. The definition of the header is in [RFC7615], and any applicable HTTP authentication schemes appear in other RFCs. This header MUST only be used in response messages related to client-to-server requests. This header has hop-by-hop scope.18.36. Proxy-Authorization
The Proxy-Authorization request-header field allows the client to identify itself (or its user) to a proxy that requires authentication. The Proxy-Authorization field-value consists of credentials containing the authentication information of the user agent for the proxy or realm of the resource being requested. The definition of the header is in [RFC7235], and any applicable HTTP authentication schemes appear in other RFCs, such as Digest [RFC7616] and Basic [RFC7617].
The HTTP access authentication process is described in [RFC7235]. Unlike Authorization, the Proxy-Authorization header field applies only to the next-hop proxy. This header MUST only be used in client- to-server requests.18.37. Proxy-Require
The Proxy-Require request-header field is used to indicate proxy- sensitive features that MUST be supported by the proxy. Any Proxy- Require header features that are not supported by the proxy MUST be negatively acknowledged by the proxy to the client using the Unsupported header. The proxy MUST use the 551 (Option Not Supported) status code in the response. Any feature tag included in the Proxy-Require does not apply to the endpoint (server or client). To ensure that a feature is supported by both proxies and servers, the tag needs to be included in also a Require header. See Section 18.43 for more details on the mechanics of this message and a usage example. See discussion in the proxies section (Section 15.1) about when to consider that a feature requires proxy support. Example of use: Proxy-Require: play.basic18.38. Proxy-Supported
The Proxy-Supported general-header field enumerates all the extensions supported by the proxy using feature tags. The header carries the intersection of extensions supported by the forwarding proxies. The Proxy-Supported header MAY be included in any request by a proxy. It MUST be added by any proxy if the Supported header is present in a request. When present in a request, the receiver MUST copy the received Proxy-Supported header in the response. The Proxy-Supported header field contains a list of feature tags applicable to proxies, as described in Section 4.5. The list is the intersection of all feature tags understood by the proxies. To achieve an intersection, the proxy adding the Proxy-Supported header includes all proxy feature tags it understands. Any proxy receiving a request with the header MUST check the list and remove any feature tag(s) it does not support. A Proxy-Supported header present in the response MUST NOT be modified by the proxies. These feature tags are the ones the proxy chains support in general and are not specific to the request resource.
Example:
C->P1: OPTIONS rtsp://example.com/ RTSP/2.0
Supported: foo, bar, blech
User-Agent: PhonyClient/1.2
P1->P2: OPTIONS rtsp://example.com/ RTSP/2.0
Supported: foo, bar, blech
Proxy-Supported: proxy-foo, proxy-bar, proxy-blech
Via: 2.0 pro.example.com
P2->S: OPTIONS rtsp://example.com/ RTSP/2.0
Supported: foo, bar, blech
Proxy-Supported: proxy-foo, proxy-blech
Via: 2.0 pro.example.com, 2.0 prox2.example.com
S->C: RTSP/2.0 200 OK
Supported: foo, bar, baz
Proxy-Supported: proxy-foo, proxy-blech
Public: OPTIONS, SETUP, PLAY, PAUSE, TEARDOWN
Via: 2.0 pro.example.com, 2.0 prox2.example.com
18.39. Public
The Public response-header field lists the set of methods supported
by the response sender. This header applies to the general
capabilities of the sender, and its only purpose is to indicate the
sender's capabilities to the recipient. The methods listed may or
may not be applicable to the Request-URI; the Allow header field
(Section 18.6) MAY be used to indicate methods allowed for a
particular URI.
Example of use:
Public: OPTIONS, SETUP, PLAY, PAUSE, TEARDOWN
In the event that there are proxies between the sender and the
recipient of a response, each intervening proxy MUST modify the
Public header field to remove any methods that are not supported via
that proxy. The resulting Public header field will contain an
intersection of the sender's methods and the methods allowed through
by the intervening proxies.
In general, proxies should allow all methods to transparently pass
through from the sending RTSP agent to the receiving RTSP agent,
but there may be cases where this is not desirable for a given
proxy. Modification of the Public response-header field by the
intervening proxies ensures that the request sender gets an
accurate response indicating the methods that can be used on the
target agent via the proxy chain.
18.40. Range
The Range general-header specifies a time range in PLAY
(Section 13.4), PAUSE (Section 13.6), SETUP (Section 13.3), and
PLAY_NOTIFY (Section 13.5) requests and responses. It MAY be
included in GET_PARAMETER requests from the client to the server with
only a Range format and no value to request the current media
position, whether the session is in Play or Ready state in the
included format. The server SHALL, if supporting the range format,
respond with the current playing point or pause point as the start of
the range. If an explicit stop point was used in the previous PLAY
request, then that value shall be included as stop point. Note that
if the server is currently under any type of media playback
manipulation affecting the interpretation of the Range header, like
scale value other than 1, that fact is also required to be included
in any GET_PARAMETER response by including the Scale header to
provide complete information.
The range can be specified in a number of units. This specification
defines smpte (Section 4.4.1), npt (Section 4.4.2), and clock
(Section 4.4.3) range units. While octet ranges (Byte Ranges) (see
Section 2.1 of [RFC7233]) and other extended units MAY be used, their
behavior is unspecified since they are not normally meaningful in
RTSP. Servers supporting the Range header MUST understand the NPT
range format and SHOULD understand the SMPTE range format. If the
Range header is sent in a time format that is not understood, the
recipient SHOULD return 456 (Header Field Not Valid for Resource) and
include an Accept-Ranges header indicating the supported time formats
for the given resource.
Example:
Range: clock=19960213T143205Z-
The Range header contains a range of one single range format. A
range is a half-open interval with a start and an end point,
including the start point but excluding the end point. A range may
either be fully specified with explicit values for start point and
end point or have either the start or end point be implicit. An
implicit start point indicates the session's pause point, and if no
pause point is set, the start of the content. An implicit end point
indicates the end of the content. The usage of both implicit start
and end points is not allowed in the same Range header; however, the
omission of the Range header has that meaning, i.e., from pause point
(or start) until end of content.
As noted, Range headers define half-open intervals. A range of
A-B starts exactly at time A, but ends just before B. Only the
start time of a media unit such as a video or audio frame is
relevant. For example, assume that video frames are generated
every 40 ms. A range of 10.0-10.1 would include a video frame
starting at 10.0 or later time and would include a video frame
starting at 10.08, even though it lasted beyond the interval. A
range of 10.0-10.08, on the other hand, would exclude the frame at
10.08.
Please note the difference between NPT timescales' "now" and an
implicit start value. Implicit values reference the current
pause-point, while "now" is the current time. In a time-
progressing session with recording (retention for some or full
time), the pause point may be 2 min into the session while now
could be 1 hour into the session.
By default, range intervals increase, where the second point is
larger than the first point.
Example:
Range: npt=10-15
However, range intervals can also decrease if the Scale header (see
Section 18.46) indicates a negative scale value. For example, this
would be the case when a playback in reverse is desired.
Example:
Scale: -1
Range: npt=15-10
Decreasing ranges are still half-open intervals as described above.
Thus, for range A-B, A is closed and B is open. In the above
example, 15 is closed and 10 is open. An exception to this rule is
the case when B=0 is in a decreasing range. In this case, the range
is closed on both ends, as otherwise there would be no way to reach 0
on a reverse playback for formats that have such a notion, like NPT
and SMPTE.
Example:
Scale: -1
Range: npt=15-0
In this range, both 15 and 0 are closed.
A decreasing range interval without a corresponding negative value in
the Scale header is not valid.
18.41. Referrer
The Referrer request-header field allows the client to specify, for
the server's benefit, the address (URI) of the resource from which
the Request-URI was obtained. The URI refers to that of the
presentation description, typically retrieved via HTTP. The Referrer
request-header allows a server to generate lists of back-links to
resources for interest, logging, optimized caching, etc. It also
allows obsolete or mistyped links to be traced for maintenance. The
Referrer field MUST NOT be sent if the Request-URI was obtained from
a source that does not have its own URI, such as input from the user
keyboard.
If the field-value is a relative URI, it SHOULD be interpreted
relative to the Request-URI. The URI MUST NOT include a fragment
identifier.
Because the source of a link might be private information or might
reveal an otherwise private information source, it is strongly
recommended that the user be able to select whether or not the
Referrer field is sent. For example, a streaming client could have a
toggle switch for openly/anonymously, which would respectively
enable/disable the sending of Referrer and From information.
Clients SHOULD NOT include a Referrer header field in an (non-secure)
RTSP request if the referring page was transferred with a secure
protocol.
18.42. Request-Status
This request-header is used to indicate the end result for requests
that take time to complete, such as PLAY (Section 13.4). It is sent
in PLAY_NOTIFY (Section 13.5) with the end-of-stream reason to report
how the PLAY request concluded, either in success or in failure. The
header carries a reference to the request it reports on using the
CSeq number and the Session ID used in the request reported on. This
is not ensured to be unambiguous due to the fact that the CSeq number
is scoped by the transport connection. Agents originating requests
can reduce the issue by using a monotonically increasing counter across all sequential transports used. The header provides both a numerical status code (according to Section 8.1.1) and a human- readable reason phrase. Example: Request-Status: cseq=63 status=500 reason="Media data unavailable" Proxies that renumber the CSeq header need to perform corresponding remapping of the cseq parameter in this header when forwarding the request to the next-hop agent.18.43. Require
The Require request-header field is used by agents to ensure that the other endpoint supports features that are required in respect to this request. It can also be used to query if the other endpoint supports certain features; however, the use of the Supported general-header (Section 18.51) is much more effective in this purpose. In case any of the feature tags listed by the Require header are not supported by the server or client receiving the request, it MUST respond to the request using the error code 551 (Option Not Supported) and include the Unsupported header listing those feature tags that are NOT supported. This header does not apply to proxies; for the same functionality with respect to proxies, see the Proxy-Require header (Section 18.37) with the exception of media-modifying proxies. Media-modifying proxies, due to their nature of handling media in a way that is very similar to a server, do need to understand also the server's features to correctly serve the client. This is to make sure that the client-server interaction will proceed without delay when all features are understood by both sides and only slow down if features are not understood (as in the example below). For a well-matched client-server pair, the interaction proceeds quickly, saving a round trip often required by negotiation mechanisms. In addition, it also removes state ambiguity when the client requires features that the server does not understand.
Example (Not complete):
C->S: SETUP rtsp://server.com/foo/bar/baz.rm RTSP/2.0
CSeq: 302
Require: funky-feature
Funky-Parameter: funkystuff
S->C: RTSP/2.0 551 Option not supported
CSeq: 302
Unsupported: funky-feature
In this example, "funky-feature" is the feature tag that indicates to
the client that the fictional Funky-Parameter field is required. The
relationship between "funky-feature" and Funky-Parameter is not
communicated via the RTSP exchange, since that relationship is an
immutable property of "funky-feature" and thus should not be
transmitted with every exchange.
Proxies and other intermediary devices MUST ignore this header. If a
particular extension requires that intermediate devices support it,
the extension should be tagged in the Proxy-Require field instead
(see Section 18.37). See discussion in the proxies section
(Section 15.1) about when to consider that a feature requires proxy
support.
18.44. Retry-After
The Retry-After response-header field can be used with a 503 (Service
Unavailable) or 553 (Proxy Unavailable) response to indicate how long
the service is expected to be unavailable to the requesting client.
This field MAY also be used with any 3rr (Redirection) response to
indicate the minimum time the user agent is asked to wait before
issuing the redirected request. A response using 413 (Request
Message Body Too Large) when the restriction is temporary MAY also
include the Retry-After header. The value of this field can be
either an RTSP-date or an integer number of seconds (in decimal)
after the time of the response.
Example:
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120
In the latter example, the delay is 2 minutes.
18.45. RTP-Info
The RTP-Info general-header field is used to set RTP-specific parameters in the PLAY and GET_PARAMETER responses or PLAY_NOTIFY and GET_PARAMETER requests. For streams using RTP as transport protocol, the RTP-Info header SHOULD be part of a 200 response to PLAY. The exclusion of the RTP-Info in a PLAY response for RTP- transported media will result in a client needing to synchronize the media streams using RTCP. This may have negative impact as the RTCP can be lost and does not need to be particularly timely in its arrival. Also, functionality that informs the client from which packet a seek has occurred is affected. The RTP-Info MAY be included in SETUP responses to provide synchronization information when changing transport parameters, see Section 13.3. The RTP-Info header and the Range header MAY be included in a GET_PARAMETER request from client to server without any values to request the current playback point and corresponding RTP synchronization information. When the RTP-Info header is included in a Request, the Range header MUST also be included. The server response SHALL include both the Range header and the RTP-Info header. If the session is in Play state, then the value of the Range header SHALL be filled in with the current playback point and with the corresponding RTP-Info values. If the server is in another state, no values are included in the RTP-Info header. The header is included in PLAY_NOTIFY requests with the Notify-Reason of the end of stream to provide RTP information about the end of the stream. The header can carry the following parameters: url: Indicates the stream URI for which the following RTP parameters correspond; this URI MUST be the same as used in the SETUP request for this media stream. Any relative URI MUST use the Request-URI as base URI. This parameter MUST be present. ssrc: The SSRC to which the RTP timestamp and sequence number provided applies. This parameter MUST be present. seq: Indicates the sequence number of the first packet of the stream that is direct result of the request. This allows clients to gracefully deal with packets when seeking. The client uses this value to differentiate packets that originated before the seek from packets that originated after the seek. Note that a client may not receive the packet with the expressed sequence number and instead may receive packets with a higher sequence number due to packet loss or reordering. This parameter is RECOMMENDED to be present.
rtptime: MUST indicate the RTP timestamp value corresponding to the
start time value in the Range response-header or, if not
explicitly given, the implied start point. The client uses
this value to calculate the mapping of RTP time to NPT or other
media timescale. This parameter SHOULD be present to ensure
inter-media synchronization is achieved. There exists no
requirement that any received RTP packet will have the same RTP
timestamp value as the one in the parameter used to establish
synchronization.
A mapping from RTP timestamps to NTP format timestamps (wallclock)
is available via RTCP. However, this information is not
sufficient to generate a mapping from RTP timestamps to media
clock time (NPT, etc.). Furthermore, in order to ensure that this
information is available at the necessary time (immediately at
startup or after a seek), and that it is delivered reliably, this
mapping is placed in the RTSP control channel.
In order to compensate for drift for long, uninterrupted
presentations, RTSP clients should additionally map NPT to NTP,
using initial RTCP sender reports to do the mapping, and later
reports to check drift against the mapping.
Example:
Range:npt=3.25-15
RTP-Info:url="rtsp://example.com/foo/audio" ssrc=0A13C760:seq=45102;
rtptime=12345678,url="rtsp://example.com/foo/video"
ssrc=9A9DE123:seq=30211;rtptime=29567112
Lets assume that Audio uses a 16 kHz RTP timestamp clock and Video
a 90 kHz RTP timestamp clock. Then, the media synchronization is
depicted in the following way.
NPT 3.0---3.1---3.2-X-3.3---3.4---3.5---3.6
Audio PA A
Video V PV
X: NPT time value = 3.25, from Range header.
A: RTP timestamp value for Audio from RTP-Info header (12345678).
V: RTP timestamp value for Video from RTP-Info header (29567112).
PA: RTP audio packet carrying an RTP timestamp of 12344878, which
corresponds to NPT = (12344878 - A) / 16000 + 3.25 = 3.2
PV: RTP video packet carrying an RTP timestamp of 29573412, which
corresponds to NPT = (29573412 - V) / 90000 + 3.25 = 3.32
18.46. Scale
The Scale general-header indicates the requested or used view rate for the media resource being played back. A scale value of 1 indicates normal play at the normal forward viewing rate. If not 1, the value corresponds to the rate with respect to normal viewing rate. For example, a value of 2 indicates twice the normal viewing rate ("fast forward") and a value of 0.5 indicates half the normal viewing rate. In other words, a value of 2 has content time increase at twice the playback time. For every second of elapsed (wallclock) time, 2 seconds of content time will be delivered. A negative value indicates reverse direction. For certain media transports, this may require certain considerations to work consistently; see Appendix C.1 for description on how RTP handles this. The transmitted-data rate SHOULD NOT be changed by selection of a different scale value. The resulting bitrate should be reasonably close to the nominal bitrate of the content for scale = 1. The server has to actively manipulate the data when needed to meet the bitrate constraints. Implementation of scale changes depends on the server and media type. For video, a server may, for example, deliver only key frames or selected frames. For audio, it may time-scale the audio while preserving pitch or, less desirably, deliver fragments of audio, or completely mute the audio. The server and content may restrict the range of scale values that it supports. The supported values are indicated by the Media-Properties header (Section 18.29). The client SHOULD only indicate request values to be supported. However, as the values may change as the content progresses, a requested value may no longer be valid when the request arrives. Thus, a non-supported value in a request does not generate an error, it only forces the server to choose the closest value. The response MUST always contain the actual scale value chosen by the server. If the server does not implement the possibility to scale, it will not return a Scale header. A server supporting scale operations for PLAY MUST indicate this with the use of the "play.scale" feature tag. When indicating a negative scale for a reverse playback, the Range header MUST indicate a decreasing range as described in Section 18.40. Example of playing in reverse at 3.5 times normal rate: Scale: -3.5 Range: npt=15-10
18.47. Seek-Style
When a client sends a PLAY request with a Range header to perform a random access to the media, the client does not know if the server will pick the first media samples or the first random access point prior to the request range. Depending on the use case, the client may have a strong preference. To express this preference and provide the client with information on how the server actually acted on that preference, the Seek-Style general-header is defined. Seek-Style is a general-header that MAY be included in any PLAY request to indicate the client's preference for any media stream that has the random access properties. The server MUST always include the header in any PLAY response for media with random access properties to indicate what policy was applied. A server that receives an unknown Seek-Style policy MUST ignore it and select the server default policy. A client receiving an unknown policy MUST ignore it and use the Range header and any media synchronization information as basis to determine what the server did. This specification defines the following seek policies that may be requested (see also Section 4.7.1): RAP: Random Access Point (RAP) is the behavior of requesting the server to locate the closest previous random access point that exists in the media aggregate and deliver from that. By requesting a RAP, media quality will be the best possible as all media will be delivered from a point where full media state can be established in the media decoder. CoRAP: Conditional Random Access Point (CoRAP) is a variant of the above RAP behavior. This policy is primarily intended for cases where there is larger distance between the random access points in the media. CoRAP uses the RAP policy if the condition that there is a Random Access Point closer to the requested start point than to the current pause point is fulfilled. Otherwise, no seeking is performed and playback will continue from the current pause point. This policy assumes that the media state existing prior to the pause is usable if delivery is continued. If the client or server knows that this is not the fact, the RAP policy should be used. In other words, in most cases when the client requests a start point prior to the current pause point, a valid decoding dependency chain from the media delivered prior to the pause and to the requested media unit will not exist. If the server searched to a random access point, the server MUST return the CoRAP policy in the Seek-Style header and adjust the Range header to reflect the position of the selected RAP. In case the random access point is farther away and the server chooses to continue
from the current pause point, it MUST include the "Next" policy in
the Seek-Style header and adjust the Range header start point to
the current pause point.
First-Prior: The first-prior policy will start delivery with the
media unit that has a playout time first prior to the requested
time. For discrete media, that would only include media units
that would still be rendered at the request time. For continuous
media, that is media that will be rendered during the requested
start time of the range.
Next: The next media units after the provided start time of the
range: for continuous framed media, that would mean the first next
frame after the provided time and for discrete media, the first
unit that is to be rendered after the provided time. The main
usage for this case is when the client knows it has all media up
to a certain point and would like to continue delivery so that a
complete uninterrupted media playback can be achieved. An example
of such a scenario would be switching from a broadcast/multicast
delivery to a unicast-based delivery. This policy MUST only be
used on the client's explicit request.
Please note that these expressed preferences exist for optimizing the
startup time or the media quality. The "Next" policy breaks the
normal definition of the Range header to enable a client to request
media with minimal overlap, although some may still occur for
aggregated sessions. RAP and First-Prior both fulfill the
requirement of providing media from the requested range and forward.
However, unless RAP is used, the media quality for many media codecs
using predictive methods can be severely degraded unless additional
data is available as, for example, already buffered, or through other
side channels.
18.48. Server
The Server general-header field contains information about the
software used by the origin server to create or handle the request.
This field can contain multiple product tokens and comments
identifying the server and any significant subproducts. The product
tokens are listed in order of their significance for identifying the
application.
Example:
Server: PhonyServer/1.0
If the response is being forwarded through a proxy, the proxy application MUST NOT modify the Server response-header. Instead, it SHOULD include a Via field (Section 18.57). If the response is generated by the proxy, the proxy application MUST return the Server response-header as previously returned by the server.18.49. Session
The Session general-header field identifies an RTSP session. An RTSP session is created by the server as a result of a successful SETUP request, and in the response, the session identifier is given to the client. The RTSP session exists until destroyed by a TEARDOWN or a REDIRECT or is timed out by the server. The session identifier is chosen by the server (see Section 4.3) and MUST be returned in the SETUP response. Once a client receives a session identifier, it MUST be included in any request related to that session. This means that the Session header MUST be included in a request, using the following methods: PLAY, PAUSE, PLAY_NOTIFY and TEARDOWN. It MAY be included in SETUP, OPTIONS, SET_PARAMETER, GET_PARAMETER, and REDIRECT. It MUST NOT be included in DESCRIBE. The Session header MUST NOT be included in the following methods, if these requests are pipelined and if the session identifier is not yet known: PLAY, PAUSE, TEARDOWN, SETUP, OPTIONS SET_PARAMETER, and GET_PARAMETER. In an RTSP response, the session header MUST be included in methods, SETUP, PLAY, PAUSE, and PLAY_NOTIFY, and it MAY be included in methods TEARDOWN and REDIRECT. If included in the request of the following methods it MUST also be included in the response: OPTIONS, GET_PARAMETER, and SET_PARAMETER. It MUST NOT be included in DESCRIBE responses. Note that a session identifier identifies an RTSP session across transport sessions or connections. RTSP requests for a given session can use different URIs (Presentation and media URIs). Note, that there are restrictions depending on the session as to which URIs are acceptable for a given method. However, multiple "user" sessions for the same URI from the same client will require use of different session identifiers. The session identifier is needed to distinguish several delivery requests for the same URI coming from the same client. The response 454 (Session Not Found) MUST be returned if the session identifier is invalid.
The header MAY include a parameter for session timeout period. If
not explicitly provided, this value is set to 60 seconds. As this
affects how often session keep-alives are needed, values smaller than
30 seconds are not recommended. However, larger-than-default values
can be useful in applications of RTSP that have inactive but
established sessions for longer time periods.
The 60-second value was chosen as the session timeout value as it
results in keep-alive messages that are not too frequent and low
sensitivity to variations in request/response timing. If one
reduces the timeout value to below 30 seconds, the corresponding
request/response timeout becomes a significant part of the session
timeout. The 60-second value also allows for reasonably rapid
recovery of committed server resources in case of client failure.
18.50. Speed
The Speed general-header field requests the server to deliver
specific amounts of nominal media time per unit of delivery time,
contingent on the server's ability and desire to serve the media
stream at the given speed. The client requests the delivery speed to
be within a given range with a lower and upper bound. The server
SHALL deliver at the highest possible speed within the range, but not
faster than the upper bound, for which the underlying network path
can support the resulting transport data rates. As long as any speed
value within the given range can be provided, the server SHALL NOT
modify the media quality. Only if the server is unable to deliver
media at the speed value provided by the lower bound shall it reduce
the media quality.
Implementation of the Speed functionality by the server is OPTIONAL.
The server can indicate its support through a feature tag,
play.speed. The lack of a Speed header in the response is an
indication of lack of support of this functionality.
The speed parameter values are expressed as a positive decimal value,
e.g., a value of 2.0 indicates that data is to be delivered twice as
fast as normal. A speed value of zero is invalid. The range is
specified in the form "lower bound - upper bound". The lower-bound
value may be smaller or equal to the upper bound. All speeds may not
be possible to support. Therefore, the server MAY modify the
requested values to the closest supported. The actual supported
speed MUST be included in the response. However, note that the use
cases may vary and that Speed value ranges such as 0.7-0.8, 0.3-2.0,
1.0-2.5, and 2.5-2.5 all have their usages.
Example:
Speed: 1.0-2.5
Use of this header changes the bandwidth used for data delivery. It
is meant for use in specific circumstances where delivery of the
presentation at a higher or lower rate is desired. The main use
cases are buffer operations or local scale operations. Implementers
should keep in mind that bandwidth for the session may be negotiated
beforehand (by means other than RTSP) and, therefore, renegotiation
may be necessary. To perform Speed operations, the server needs to
ensure that the network path can support the resulting bitrate.
Thus, the media transport needs to support feedback so that the
server can react and adapt to the available bitrate.
18.51. Supported
The Supported general-header enumerates all the extensions supported
by the client or server using feature tags. The header carries the
extensions supported by the message-sending client or server. The
Supported header MAY be included in any request. When present in a
request, the receiver MUST respond with its corresponding Supported
header. Note that the Supported header is also included in 4xx and
5xx responses.
The Supported header contains a list of feature tags, described in
Section 4.5, that are understood by the client or server. These
feature tags are the ones the server or client supports in general
and are not specific to the request resource.
Example:
C->S: OPTIONS rtsp://example.com/ RTSP/2.0
Supported: foo, bar, blech
User-Agent: PhonyClient/1.2
S->C: RTSP/2.0 200 OK
Supported: bar, blech, baz
18.52. Terminate-Reason
The Terminate-Reason request-header allows the server, when sending a REDIRECT or TEARDOWN request, to provide a reason for the session termination and any additional information. This specification identifies three reasons for Redirections and may be extended in the future: Server-Admin: The server needs to be shut down for some administrative reason. Session-Timeout: A client's session has been kept alive for extended periods of time and the server has determined that it needs to reclaim the resources associated with this session. Internal-Error An internal error that is impossible to recover from has occurred, forcing the server to terminate the session. The Server may provide additional parameters containing information around the redirect. This specification defines the following ones. time: Provides a wallclock time when the server will stop providing any service. user-msg: A UTF-8 text string with a message from the server to the user. This message SHOULD be displayed to the user.18.53. Timestamp
The Timestamp general-header describes when the agent sent the request. The value of the timestamp is of significance only to the agent and may use any timescale. The responding agent MUST echo the exact same value and MAY, if it has accurate information about this, add a floating-point number indicating the number of seconds that has elapsed since it has received the request. The timestamp can be used by the agent to compute the round-trip time to the responding agent so that it can adjust the timeout value for retransmissions when running over an unreliable protocol. It also resolves retransmission ambiguities for unreliable transport of RTSP. Note that the present specification provides only for reliable transport of RTSP messages. The Timestamp general-header is specified in case the protocol is extended in the future to use unreliable transport.
18.54. Transport
The Transport general-header indicates which transport protocol is to be used and configures its parameters such as destination address, compression, multicast time-to-live and destination port for a single stream. It sets those values not already determined by a presentation description. A Transport request-header MAY contain a list of transport options acceptable to the client, in the form of multiple transport specification entries. Transport specifications are comma separated and listed in decreasing order of preference. Each transport specification consists of a transport protocol identifier, followed by any number of parameters separated by semicolons. A Transport request-header MAY contain multiple transport specifications using the same transport protocol identifier. The server MUST return a Transport response-header in the response to indicate the values actually chosen, if any. If no transport specification is supported, no transport header is returned and the response MUST use the status code 461 (Unsupported Transport) (Section 17.4.25). In case more than one transport specification was present in the request, the server MUST return the single transport specification (transport- spec) that was actually chosen, if any. The number of transport-spec entries is expected to be limited as the client will receive guidance on what configurations are possible from the presentation description. The Transport header MAY also be used in subsequent SETUP requests to change transport parameters. A server MAY refuse to change parameters of an existing stream. The transport protocol identifier defines, for each transport specification, which transport protocol to use and any related rules. Each transport protocol identifier defines the parameters that are required to occur; additional optional parameters MAY occur. This flexibility is provided as parameters may be different and provide different options to the RTSP agent. A transport specification may only contain one of any given parameter within it. A parameter consists of a name and optionally a value string. Parameters MAY be given in any order. Additionally, a transport specification may only contain either the unicast or the multicast transport type parameter. The transport protocol identifier, and all parameters, need to be understood in a transport specification; if not, the transport specification MUST be ignored. An RTSP proxy of any type that uses or modifies the transport specification, e.g., access proxy or security proxy, MUST remove specifications with unknown parameters
before forwarding the RTSP message. If that results in no remaining transport specification, the proxy SHALL send a 461 (Unsupported Transport) (Section 17.4.25) response without any Transport header. The Transport header is restricted to describing a single media stream. (RTSP can also control multiple streams as a single entity.) Making it part of RTSP rather than relying on a multitude of session description formats greatly simplifies designs of firewalls. The general syntax for the transport protocol identifier is a list of slash-separated tokens: Value1/Value2/Value3... Which, for RTP transports, takes the form: RTP/profile/lower-transport. The default value for the "lower-transport" parameters is specific to the profile. For RTP/AVP, the default is UDP. There are two different methods for how to specify where the media should be delivered for unicast transport: dest_addr: The presence of this parameter and its values indicates the destination address or addresses (host address and port pairs for IP flows) necessary for the media transport. No dest_addr: The lack of the dest_addr parameter indicates that the server MUST send media to the same address from which the RTSP messages originates. The choice of method for indicating where the media is to be delivered depends on the use case. In some cases, the only allowed method will be to use no explicit address indication and have the server deliver media to the source of the RTSP messages. For multicast, there are several methods for specifying addresses, but they are different in how they work compared with unicast: dest_addr with client picked address: The address and relevant parameters, like TTL (scope), for the actual multicast group to deliver the media to. There are security implications (Section 21) with this method that need to be addressed because an RTSP server can be used as a DoS attacker on an existing multicast group.
dest_addr using Session Description Information: The information
included in the transport header can all be coming from the
session description, e.g., the SDP "c=" and "m=" lines. This
mitigates some of the security issues of the previous methods
as it is the session provider that picks the multicast group
and scope. The client MUST include the information if it is
available in the session description.
No dest_addr: The behavior when no explicit multicast group is
present in a request is not defined.
An RTSP proxy will need to take care. If the media is not desired to
be routed through the proxy, the proxy will need to introduce the
destination indication.
Below are the configuration parameters associated with transport:
General parameters:
unicast / multicast: This parameter is a mutually exclusive
indication of whether unicast or multicast delivery will be
attempted. One of the two values MUST be specified. Clients
that are capable of handling both unicast and multicast
transmission need to indicate such capability by including two
full transport-specs with separate parameters for each.
layers: The number of multicast layers to be used for this media
stream. The layers are sent to consecutive addresses starting
at the dest_addr address. If the parameter is not included, it
defaults to a single layer.
dest_addr: A general destination address parameter that can contain
one or more address specifications. Each combination of
protocol/profile/lower transport needs to have the format and
interpretation of its address specification defined. For
RTP/AVP/UDP and RTP/AVP/TCP, the address specification is a
tuple containing a host address and port. Note, only a single
destination parameter per transport spec is intended. The
usage of multiple destinations to distribute a single media to
multiple entities is unspecified.
The client originating the RTSP request MAY specify the
destination address of the stream recipient with the host
address as part of the tuple. When the destination address is
specified, the recipient may be a different party than the
originator of the request. To avoid becoming the unwitting
perpetrator of a remote-controlled DoS attack, a server MUST
perform security checks (see Section 21.2.1) and SHOULD log
such attempts before allowing the client to direct a media
stream to a recipient address not chosen by the server.
Implementations cannot rely on TCP as a reliable means of
client identification. If the server does not allow the host
address part of the tuple to be set, it MUST return 463
(Destination Prohibited).
The host address part of the tuple MAY be empty, for example
":58044", in cases when it is desired to specify only the
destination port. Responses to requests including the
Transport header with a dest_addr parameter SHOULD include the
full destination address that is actually used by the server.
The server MUST NOT remove address information that is already
present in the request when responding, unless the protocol
requires it.
src_addr: A general source address parameter that can contain one or
more address specifications. Each combination of
protocol/profile/lower transport needs to have the format and
interpretation of its address specification defined. For
RTP/AVP/UDP and RTP/AVP/TCP, the address specification is a
tuple containing a host address and port.
This parameter MUST be specified by the server if it transmits
media packets from an address other than the one RTSP messages
are sent to. This will allow the client to verify the source
address and give it a destination address for its RTCP feedback
packets, if RTP is used. The address or addresses indicated in
the src_addr parameter SHOULD be used both for the sending and
receiving of the media stream's data packets. The main reasons
are threefold: First, indicating the port and source address(s)
lets the receiver know where from the packets is expected to
originate. Second, traversal of NATs is greatly simplified
when traffic is flowing symmetrically over a NAT binding.
Third, certain NAT traversal mechanisms need to know to which
address and port to send so-called "binding packets" from the
receiver to the sender, thus creating an address binding in the
NAT that the sender-to-receiver packet flow can use.
This information may also be available through SDP.
However, since this is more a feature of transport than
media initialization, the authoritative source for this
information should be in the SETUP response.
mode: The mode parameter indicates the methods to be supported for
this session. The currently defined valid value is "PLAY". If
not provided, the default is "PLAY". The "RECORD" value was
defined in RFC 2326; in this specification, it is unspecified
but reserved. RECORD and other values may be specified in the
future.
interleaved: The interleaved parameter implies mixing the media
stream with the control stream in whatever protocol is being
used by the control stream, using the mechanism defined in
Section 14. The argument provides the channel number to be
used in the $ block (see Section 14) and MUST be present. This
parameter MAY be specified as an interval, e.g.,
interleaved=4-5 in cases where the transport choice for the
media stream requires it, e.g., for RTP with RTCP. The channel
number given in the request is only a guidance from the client
to the server on what channel number(s) to use. The server MAY
set any valid channel number in the response. The declared
channels are bidirectional, so both end parties MAY send data
on the given channel. One example of such usage is the second
channel used for RTCP, where both server and client send RTCP
packets on the same channel.
This allows RTP/RTCP to be handled similarly to the way that
it is done with UDP, i.e., one channel for RTP and the other
for RTCP.
MIKEY: This parameter is used in conjunction with transport
specifications that can utilize MIKEY [RFC3830] for security
context establishment. So far, only the SRTP-based RTP
profiles SAVP and SAVPF can utilize MIKEY, and this is defined
in Appendix C.1.4.1. This parameter can be included both in
request and response messages. The binary MIKEY message SHALL
be Base64-encoded [RFC4648] before being included in the value
part of the parameter, where the encoding adheres to the
definition in Section 4 of RFC 4648 and where the padding bits
are set to zero.
Multicast-specific:
ttl: multicast time-to-live for IPv4. When included in requests,
the value indicates the TTL value that the client requests the
server to use. In a response, the value actually being used by
the server is returned. A server will need to consider what
values that are reasonable and also the authority of the user
to set this value. Corresponding functions are not needed for
IPv6 as the scoping is part of the IPv6 multicast address
[RFC4291].
RTP-specific:
These parameters MAY only be used if the media-transport protocol is
RTP.
ssrc: The ssrc parameter, if included in a SETUP response, indicates
the RTP SSRC [RFC3550] value(s) that will be used by the media
server for RTP packets within the stream. The values are
expressed as a slash-separated sequence of SSRC values, each
SSRC expressed as an eight-digit hexadecimal value.
The ssrc parameter MUST NOT be specified in requests. The
functionality of specifying the ssrc parameter in a SETUP
request is deprecated as it is incompatible with the
specification of RTP [RFC3550]. If the parameter is included
in the Transport header of a SETUP request, the server SHOULD
ignore it, and choose appropriate SSRCs for the stream. The
server SHOULD set the ssrc parameter in the Transport header of
the response.
RTCP-mux: Used to negotiate the usage of RTP and RTCP multiplexing
[RFC5761] on a single underlying transport stream/flow. The
presence of this parameter in a SETUP request indicates the
client's support and requires the server to use RTP and RTCP
multiplexing. The client SHALL only include one transport
stream in the Transport header specification. To provide the
server with a choice between using RTP/RTCP multiplexing or
not, two different transport header specifications must be
included.
The parameter setup and connection defined below MAY only be used if
the media-transport protocol of the lower-level transport is
connection oriented (such as TCP). However, these parameters MUST
NOT be used when interleaving data over the RTSP connection.
setup: Clients use the setup parameter on the Transport line in a
SETUP request to indicate the roles it wishes to play in a TCP
connection. This parameter is adapted from [RFC4145]. The use
of this parameter in RTP/AVP/TCP non-interleaved transport is
discussed in Appendix C.2.2; the discussion below is limited to
syntactic issues. Clients may specify the following values for
the setup parameter:
active: The client will initiate an outgoing connection.
passive: The client will accept an incoming connection.
actpass: The client is willing to accept an incoming
connection or to initiate an outgoing connection.
If a client does not specify a setup value, the "active" value
is assumed.
In response to a client SETUP request where the setup parameter
is set to "active", a server's 2xx reply MUST assign the setup
parameter to "passive" on the Transport header line.
In response to a client SETUP request where the setup parameter
is set to "passive", a server's 2xx reply MUST assign the setup
parameter to "active" on the Transport header line.
In response to a client SETUP request where the setup parameter
is set to "actpass", a server's 2xx reply MUST assign the setup
parameter to "active" or "passive" on the Transport header
line.
Note that the "holdconn" value for setup is not defined for
RTSP use, and MUST NOT appear on a Transport line.
connection: Clients use the connection parameter in a transport
specification part of the Transport header in a SETUP request
to indicate the client's preference for either reusing an
existing connection between client and server (in which case
the client sets the "connection" parameter to "existing") or
requesting the creation of a new connection between client and
server (in which cast the client sets the "connection"
parameter to "new"). Typically, clients use the "new" value
for the first SETUP request for a URL, and "existing" for
subsequent SETUP requests for a URL.
If a client SETUP request assigns the "new" value to
"connection", the server response MUST also assign the "new"
value to "connection" on the Transport line.
If a client SETUP request assigns the "existing" value to
"connection", the server response MUST assign a value of
"existing" or "new" to "connection" on the Transport line, at
its discretion.
The default value of "connection" is "existing", for all SETUP
requests (initial and subsequent).
The combination of transport protocol, profile and lower transport
needs to be defined. A number of combinations are defined in the
Appendix C.
Below is a usage example, showing a client advertising the capability
to handle multicast or unicast, preferring multicast. Since this is
a unicast-only stream, the server responds with the proper transport
parameters for unicast.
C->S: SETUP rtsp://example.com/foo/bar/baz.rm RTSP/2.0
CSeq: 302
Transport: RTP/AVP;multicast;mode="PLAY",
RTP/AVP;unicast;dest_addr="192.0.2.5:3456"/
"192.0.2.5:3457";mode="PLAY"
Accept-Ranges: npt, smpte, clock
User-Agent: PhonyClient/1.2
S->C: RTSP/2.0 200 OK
CSeq: 302
Date: Fri, 20 Dec 2013 10:20:32 +0000
Session: rQi1hBrGlFdiYld241FxUO
Transport: RTP/AVP;unicast;dest_addr="192.0.2.5:3456"/
"192.0.2.5:3457";src_addr="192.0.2.224:6256"/
"192.0.2.224:6257";mode="PLAY"
Accept-Ranges: npt
Media-Properties: Random-Access=0.6, Dynamic,
Time-Limited=20081128T165900
18.55. Unsupported
The Unsupported response-header lists the features not supported by
the responding RTSP agent. In the case where the feature was
specified via the Proxy-Require field (Section 18.37), if there is a
proxy on the path between the client and the server, the proxy MUST
send a response message with a status code of 551 (Option Not
Supported). The request MUST NOT be forwarded.
See Section 18.43 for a usage example.
18.56. User-Agent
The User-Agent general-header field contains information about the user agent originating the request or producing a response. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests. The field can contain multiple product tokens and comments identifying the agent and any subproducts which form a significant part of the user agent. By convention, the product tokens are listed in order of their significance for identifying the application. Example: User-Agent: PhonyClient/1.218.57. Via
The Via general-header field MUST be used by proxies to indicate the intermediate protocols and recipients between the user agent and the server on requests and between the origin server and the client on responses. The field is intended to be used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of all senders along the request/response chain. Each of multiple values in the Via field represents each proxy that has forwarded the message. Each recipient MUST append its information such that the end result is ordered according to the sequence of forwarding applications. So messages originating with the client or server do not include the Via header. The first proxy or other intermediate adds the header and its information into the field. Any additional intermediate adds additional field-values. Resulting in the server seeing the chains of intermediates in a client-to-server request and the client seeing the full chain in the response message. Proxies (e.g., Access Proxy or Translator Proxy) SHOULD NOT, by default, forward the names and ports of hosts within the private/ protected region. This information SHOULD only be propagated if explicitly enabled. If not enabled, the via-received of any host behind the firewall/NAT SHOULD be replaced by an appropriate pseudonym for that host.
For organizations that have strong privacy requirements for hiding internal structures, a proxy MAY combine an ordered subsequence of Via header field entries with identical sent-protocol values into a single such entry. Applications MUST NOT combine entries that have different received-protocol values.18.58. WWW-Authenticate
The WWW-Authenticate header is specified in [RFC7235]; its usage depends on the used authentication schemes, such as Digest [RFC7616] and Basic [RFC7617]. The WWW-Authenticate response-header field MUST be included in 401 (Unauthorized) response messages. The field-value consists of at least one challenge that indicates the authentication scheme(s) and parameters applicable to the Request-URI. This header MUST only be used in response messages related to client to server requests. The HTTP access authentication process is described in [RFC7235] with some clarification in Section 19.1. User agents are advised to take special care in parsing the WWW-Authenticate field-value as it might contain more than one challenge, or if more than one WWW-Authenticate header field is provided, the contents of a challenge itself can contain a comma-separated list of authentication parameters.
(page 185 continued on part 9)
