Subject: [MMUSIC] RTSP: GET_PARAMETER model and usage clarifications.

From: Magnus Westerlund <[email-masked]>
Date: Mon, 09 Mar 2009 14:43:15 +0100

Hi,

We had this issue that Joe Pallas raised way back about content
negotiation model around GET/SET_PARAMETER. I have written an overview
section on what is available. It still isn't much, failure indication
and feature-tags. I also have clarified which headers are usable with
GET_PARAMETER to retrieve state. Please look at this.

2.4.  Session Parameter Manipulations

   A session may have additional state or functionality that effects how
   the server or client treats the session, content, how it functions,
   or feedback on how well the session works.  Such extensions are not
   defined in this specifcation, but may be done in various extensions.
   RTSP has two methods used to retrieve parameter values or to set them
   on either the client or the server: GET_PARAMETER (Section 13.8) or
   SET_PARAMETER (Section 13.9).  These methods are carrying the
   parameters in a message body of the appropriate format.  One can also
   use certain type of headers to query state with the GET_PARAMETER
   method.  As an example clients needing to know the current Media-
   Range for a time-progressing session can use the GET_PARAMETER method
   and include the media-range.  Also synchronization information using
   the combination of RTP-Info and Range can be requested.

   RTSP 2.0 does not have a strong mechanism for providing negotiation
   of which headers or parameters and their formats that can be used.
   The protocol will indicate headers or parameters that it doesn't
   support if tried.  But determination a priori of what is available
   needs to be done through out-of-band mechanism, like in the session
   description, or through the usage of feature tags (Section 4.7).

13.8.  GET_PARAMETER

   The GET_PARAMETER request retrieves the value of any specified
   parameter or parameters for a presentation or stream specified in the
   URI.  If the Session header is present in a request, the value of a
   parameter MUST be retrieved in the specified session context.  There
   are two ways of specifying the parameters to be retrieved.  The first
   is by including headers which have been defined such that you can use
   them for this purpose.  Header for this purpose should allow empty,
   or stripped value parts to avoid having to specify bogus data when
   indicating the desire to retrieve a value.  The successful completion
   of the request should also be evident from any filled out values in
   the response.  The Media-Range header (Section 16.29) is one such
   header.  The other is to specify a message body that lists the
   parameter(s) that are desirable to retrieve.  The Content-Type header
   (Section 16.18) is used to specify which format the message body has.

   The headers that MAY be used for retriving their current value using
   GET_PARAMETER are:

   o  Accept-Ranges

   o  Media-Range

   o  Media-Properties

   o  Range

   o  RTP-Info

Schulzrinne, et al.    Expires September 10, 2009              [Page 85]

Internet-Draft   Real Time Streaming Protocol 2.0 (RTSP)      March 2009

   The method MAY also be used without a message body or any header that
   request parameters for keep-alive purpose.  Any request that is
   successful, i.e., a 200 OK response is received, then the keep-alive
   timer has been updated.  Any non-required header present in such a
   request may or may not been processed.  Normally the presence of
   filled out values in the header will be indication that the header
   has been processed.  However, for cases when this is difficult to
   determine, it is recommended to use a feature-tag and the Require
   header.  Due to this reason it is usually easier if any parameters to
   be retrieved are sent in the body, rather than using any header.

   Parameters specified within the body of the message must all be
   understood by the request receiving agent.  If one or more parameters
   are not understood a 451 (Parameter Not Understood) MUST be sent
   including a body listing these parameters that wasn't understood.  If
   all parameters are understood their value is filled in and returned
   in the response message body.

   Example:

     S->C: GET_PARAMETER rtsp://example.com/fizzle/foo RTSP/2.0
           CSeq: 431
           Content-Type: text/parameters
           Session: 12345678
           Content-Length: 26
           User-Agent: PhonyClient/1.2

           packets_received
           jitter

     C->S: RTSP/2.0 200 OK
           CSeq: 431
           Content-Length: 38
           Content-Type: text/parameters

           packets_received: 10
           jitter: 0.3838

16.5.  Accept-Ranges

   The Accept-Ranges request and response-header field allows indication
   of the format supported in the Range header.  The client MUST include
   the header in SETUP requests to indicate which formats it support to
   receive in PLAY and PAUSE responses, and REDIRECT requests.  The
   server MUST include the header in SETUP and 456 error responses to
   indicate the formats supported for the resource indicated by the
   request URI.  The header MAY be included in GET_PARAMETER request and
   response pairs.  The GET_PARAMETER request MUST contain a Session
   header to identify the session context the request are related to.
   The requester and responder will indicate their capabilites regarding
   Range formats respectively.
      Accept-Ranges: NPT, SMPTE

   The syntax is defined in Section 20.2.3.

16.28.  Media-Properties (Partial section)

   This general header is used in SETUP response or PLAY_NOTIFY requests
   to indicate the media's properties that currently are applicable to
   the RTSP session.  PLAY_NOTIFY MAY be used to modify these properties
   at any point.  However, the client SHOULD have received the update
   prior to any action related to the new media properties take affect.
   For aggregated sessions the Media-Properties header will be returned
   in each SETUP response.  The header received in the latest response
   is the one that applies on the whole session from this point until
   any future update.  The header MAY be included without value in
   GET_PARAMETER requests to the server with a Session header included
   to query the current Media-Properties for the session.  The responder
   MUST include the current session's media properties.

16.29.  Media-Range (Partial section)

   The Media-Range general header is used to give the range of the media
   at the time of sending the RTSP message.  This header MUST be
   included in SETUP response, and PLAY and PAUSE response for media
   that are Time-Progressing, and PLAY and PAUSE response after any
   change for media that are Dynamic, and in PLAY_NOTIFY request that
   are sent due to Media-Property-Update.  Media-Range header without
   any range specifications MAY be included in GET_PARAMETER requests to
   the server to request the current range.  The server MUST in this
   case include the current range at the time of sending the response.

16.38.  Range (Partial section)

   The Range header specifies a time range in PLAY (Section 13.4), PAUSE
   (Section 13.6), SETUP (Section 13.3), REDIRECT (Section 13.10), and
   PLAY_NOTIFY (Section 13.5) requests and responses.  It MAY be
   included in GET_PARAMETER request fromt he client to the server with
   only a Range format and no value to request the current media
   position independet if the session is in playing or ready state in
   the included format.  The server SHALL if supporting that range
   format responde 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 Range, like
   Scale, that is also required to be included in any GET_PARAMETER
   response to provide complete information.

16.43.  RTP-Info (Partial section)

   The RTP-Info response-header field is used to set RTP-specific
   parameters in the PLAY response.  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 that a client needs 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 their arrival.  Also functionality as
      informing 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 MAY also be included in
   GET_PARAMETER reqeusts from client to server without any value to
   indicate a request for this information.  In such a case the Range
   header MUST also be included in the request.  The server SHALL
   responde if the session is in playing state with the RTP-Info value
   corresponding to the given Range value.

-- 

Magnus Westerlund

IETF Transport Area Director & TSVWG Chair
----------------------------------------------------------------------
Multimedia Technologies, Ericsson Research EAB/TVM
----------------------------------------------------------------------
Ericsson AB                | Phone  +46 10 7148287
Färögatan 6                | Mobile +46 73 0949079
SE-164 80 Stockholm, Sweden| mailto: [email-masked]
----------------------------------------------------------------------

---

From: "Jaehwan Kim" <[email-masked]>
Date: Thu, 12 Mar 2009 11:45:00 +0900

>           Content-Type: text/parameters
I guess Session header is missing here.

>The server SHALL
Can player ask server for a future point of information?
Because rtp timestamp should reflect real time, I think the values of
RTP-Info in the response is just 'expected value'.
Even for the past point, the actual seq and rtp timestamp might be
different according to the time whether seek operation was given or not.

Looks good other parts.

Regards,
Jaehwan Kim

Senior Development Manager / Xenon Platform Architect
Vidiator(r) - Mobilizing Interactive Media(tm)

7th Fl. AnnJay BLDG 718-2 
YeokSam-Dong, KangNam-Gu, 135-920, Seoul
 
d: +82.70.7012.2540
f:  +82.2.569.5348
m:+82.10.6225.0619
e:  [email-masked]
w: www.vidiator.com

The message represents the personal views and opinion of the individual
sender and under no circumstances represents those of HWL or its Group
Companies. The shareholders, directors and management of HWL and any of
its Group Companies accept no responsibility and accordingly shall have
no liability to any party whatsoever with respect to the contents of
this message. 
This message (including any attachments) is intended only for the use of
the addressee(s) named above. It may contain information that is
PRIVILEGED and CONFIDENTIAL and should not be read, copied or otherwise
used by any other person. 
If you are not the intended recipient, you are hereby notified that any
use, retention, disclosure, copying, printing, forwarding or
dissemination of this communication is strictly prohibited. If you have
received this communication in error, please erase all copies of the
message and its attachments and notify us immediately.

---

From: Magnus Westerlund <[email-masked]>
Date: Fri, 20 Mar 2009 00:34:30 +0100

Thanks for the feedback,

Can you please indicate section or page when quoting text. There start
to be a lot of text. In this case quite obvious, but maybe not always.

> Can player ask server for a future point of information?

No, that was not intended. The given value is returned by the server,
and should be the current position in my opinion.

> RTP-Info in the response is just 'expected value'.

With the current value, i.e. for packets already sent. For RTP you don't
need future values, only a reasonable current synchronization point.

> different according to the time whether seek operation was given or not.
Yes, this was only intended to provide the current playback point and
sync point. That way you avoid the problems you raise.

Cheers

Magnus Westerlund

---

From: Magnus Westerlund <[email-masked]>
Date: Fri, 20 Mar 2009 00:38:07 +0100

For the RTP-Info text, I think this would make it clearer what I intended:

The server SHALL respond if the session is in playing state with the
Range header filled in with the current playback point and with the
corresponding RTP-Info values.

Magnus

Magnus Westerlund skrev:
> _______________________________________________
> mmusic mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/mmusic
> 

-- 

Magnus Westerlund