メインコンテンツまでスキップ

10 Method Definitions (メソッド定義)

10 Method Definitions (メソッド定義)​

method token (メソッド・トークン) は, Request-URI (リクエスト URI) で識別されるリソースに対して実行する操作を示します。メソッドは大文字と小文字を区別します。将来, 新しいメソッドが定義されてもよいものとします。メソッド名は文字 $ (10 進で 24) で始めてはならず, token でなければなりません。メソッドの概要は表 2 に示します。

methoddirectionobjectrequirement
DESCRIBEC->SP,Srecommended
ANNOUNCEC->S, S->CP,Soptional
GET_PARAMETERC->S, S->CP,Soptional
OPTIONSC->S, S->CP,Srequired (S->C: optional)
PAUSEC->SP,Srecommended
PLAYC->SP,Srequired
RECORDC->SP,Soptional
REDIRECTS->CP,Soptional
SETUPC->SSrequired
SET_PARAMETERC->S, S->CP,Soptional
TEARDOWNC->SP,Srequired

表 2: RTSP メソッド, 方向, 作用対象 (P: presentation (プレゼンテーション), S: stream (ストリーム)) の概要

表 2 への注: PAUSE は recommended だが required ではない。完全機能サーバーを PAUSE をサポートしない形で構築できる (例: ライブフィード)。サーバーが特定のメソッドをサポートしない場合, MUST "501 Not Implemented" を返し, クライアントは SHOULD NOT 当該サーバーに対して再度そのメソッドを試みない。

10.1 OPTIONS​

動作は [H9.2] に記述されたものと等価です。OPTIONS リクエストはいつでも発行してよい (例: クライアントが非標準リクエストを試みようとする直前)。サーバー状態には影響しません。

例:

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

これらは必然的に架空の機能であることに注意 (本当に有用な機能をわざと見落とすことは望ましくない)。

10.2 DESCRIBE​

DESCRIBE メソッドは, サーバーからリクエスト URL で識別される presentation または media object (メディアオブジェクト) の記述を取得します。Accept ヘッダーでクライアントが理解する記述形式を指定してもよい。サーバーは要求されたリソースの記述で応答します。DESCRIBE のリクエスト-レスポンスの対は, RTSP の media initialization phase (メディア初期化フェーズ) を構成します。

例:

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=[email protected] (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

DESCRIBE レスポンスは MUST, 記述するリソースに必要なすべての media initialization information (メディア初期化情報) を含まなければならない。メディアクライアントが DESCRIBE 以外のソースから presentation description (プレゼンテーション記述) を得ており, その記述に完全なメディア初期化パラメータ集合が含まれる場合, クライアントは SHOULD それらのパラメータを用い, 同一メディアについて RTSP 経由で記述を再要求しない。

さらに, サーバーは SHOULD NOT DESCRIBE レスポンスを media indirection (メディア間接参照) の手段として用いる。

クライアントがいつ DESCRIBE 経由でメディア初期化情報を要求すべきか, すべきでないかを明確に知るための明確なルールが必要である。DESCRIBE レスポンスに記述するストリーム集合のすべてのメディア初期化を含めることを強制し, DESCRIBE のメディア間接利用を抑えることで, 他の手法に起因しうるループ問題を避ける。

メディア初期化は RTSP ベースのシステムに必須だが, RTSP 仕様は DESCRIBE メソッドで行うことを要求しない。RTSP クライアントが初期化情報を得る方法は三つある:

  • RTSP の DESCRIBE メソッド経由; * 他のプロトコル (HTTP, 電子メール添付など) 経由; * コマンドラインまたは標準入力経由 (SDP ファイル等のメディア初期化形式で起動されるブラウザヘルパーアプリケーションとして動作)。

実運用の相互運用性のため, minimal servers (最小サーバー) が DESCRIBE をサポートし, minimal clients (最小クライアント) が標準入力, コマンドライン, および/またはクライアント環境に適した他の手段からメディア初期化ファイルを受け取る "helper application (ヘルパーアプリケーション)" として動作する能力をサポートすることが強く推奨される。

10.3 ANNOUNCE​

ANNOUNCE メソッドには二つの目的がある:

クライアントからサーバーへ送る場合, ANNOUNCE はリクエスト URL で識別される presentation またはメディアオブジェクトの記述をサーバーへ投稿する。サーバーからクライアントへ送る場合, ANNOUNCE は session description (セッション記述) をリアルタイムで更新する。

presentation に新しいメディアストリームが追加された場合 (例: ライブ presentation 中), 追加部分だけでなく presentation 記述全体を再送し, 構成要素を削除できるようにすべきである。

例:

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=[email protected] (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

10.4 SETUP​

URI に対する SETUP リクエストは, ストリームされたメディアに用いる transport mechanism (トランスポート機構) を指定する。既に再生中のストリームに対してクライアントは SETUP を発行してトランスポートパラメータを変更してもよいが, サーバー MAY 許可する。許可しない場合, MUST エラー "455 Method Not Valid In This State" で応答する。介在するファイアウォールのため, クライアントはこれらのパラメータに影響できない場合 (例: サーバーが固定マルチキャストアドレスを告知) であっても, トランスポートパラメータを示さなければならない。

SETUP はすべてのトランスポート初期化情報を含むため, その情報を必要とするファイアウォール等の中間装置は, メディア初期化用に留保されている DESCRIBE レスポンスを解析するより重い作業を省略できる。

Transport ヘッダーはデータ伝送についてクライアントが受け入れ可能なトランスポートパラメータを指定する; レスポンスにはサーバーが選択したトランスポートパラメータが含まれる。

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

サーバーは SETUP レスポンスに対して session identifiers (セッション識別子) を生成する。サーバーへの SETUP にセッション識別子が含まれる場合, サーバーは MUST この setup を既存セッションに束ねるか, エラー "459 Aggregate Operation Not Allowed" を返す (セクション 11.3.10 参照)。

10.5 PLAY​

PLAY メソッドは, SETUP で指定された機構経由でサーバーにデータ送信開始を指示する。クライアントは MUST NOT, 未処理の SETUP が成功と確認される前に PLAY を発行する。

PLAY は normal play time (正常再生時刻) を指定範囲の先頭に置き, 範囲終端に達するまでストリームデータを配送する。PLAY はパイプライン化 (キュー) してよい; サーバーは MUST PLAY を順序どおり実行するようキューに入れる。すなわち, 先行 PLAY がまだ有効な間に到着した PLAY は, 先の完了まで遅延される。

これにより正確な編集が可能になる。

例えば, 下の二つの PLAY がどれだけ近い間隔で到着しても, サーバーはまず 10〜15 秒を再生し, 続けて 20〜25 秒, 最後に 30 秒から末尾までを再生する。

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-

さらなる例は PAUSE リクエストの説明を参照。

Range ヘッダーのない PLAY も合法である。ストリームが一時停止されていない限り, ストリームの先頭から再生を開始する。PAUSE で一時停止されていれば, 一時停止点で配送を再開する。再生中であれば, そのような PLAY は追加動作を起こさず, サーバーの生存確認に使える。

Range に time パラメータを含めてもよい。再生開始の UTC 時刻を指定する。指定時刻より後にメッセージを受信した場合は直ちに再生を開始する。time パラメータは異なるソースから得たストリームの同期に役立つ。

オンデマンドストリームでは, サーバーは実際に再生される範囲で応答する。メディアソースが要求範囲を有効フレーム境界に合わせる必要がある場合, 要求と異なってよい。要求に範囲がなければ, 応答に現在位置を返す。応答の範囲の単位は要求と同じである。

希望範囲の再生後, presentation は PAUSE が発行されたかのように自動的に一時停止する。

次の例は SMPTE time code (タイムコード) 0:10:20 からクリップ末尾までプレゼンテーション全体を再生する。再生開始は 1997 年 1 月 23 日 15:36 である。

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

ライブ presentation の録画を再生する場合, clock 単位が望ましいことがある:

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

再生のみをサポートするメディアサーバーは MUST npt 形式をサポートし, MAY clock および smpte 形式をサポートする。

10.6 PAUSE​

PAUSE はストリーム配送を一時的に中断 (停止) する。リクエスト URL がストリームを指す場合, そのストリームの再生と録音のみが停止する。例: 音声ではミュートに相当。URL が presentation またはストリーム群を指す場合, その中の現在アクティブなすべてのストリームの配送が停止する。再生または録音再開後, トラックの同期は MUST 維持される。サーバーリソースは保持されるが, サーバー MAY SETUP メッセージの Session ヘッダーの timeout パラメータで指定された時間一時停止した後にセッションを閉じリソースを解放してもよい。

例:

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

PAUSE に Range を含め, ストリームまたは presentation をいつ停止するか指定してよい。この点を "pause point (一時停止点)" と呼ぶ。ヘッダーは時間範囲ではなくちょうど一つの値を含まなければならない。ストリームの normal play time は一時停止点に設定される。一時停止要求は, 現在保留中のいずれかの PLAY で指定された時刻点にサーバーが初めて遭遇したときに有効になる。Range が現在保留中のいずれの PLAY の外の時刻を指定する場合, エラー "457 Invalid Range" を返す。メディアユニット (音声フレーム等) がちょうど一時停止点で提示を開始する場合, 再生も録音もしない。Range が欠けると, メッセージ受信直ちに配送を中断し, 一時停止点は現在の normal play time に設定される。

PAUSE はキューされたすべての PLAY を破棄する。ただしメディアストリーム内の一時停止点は MUST 維持される。続く Range のない PLAY は一時停止点から再開する。

例: サーバーに 10〜15 と 20〜29 の再生要求が保留され, NPT 21 の PAUSE を受信した場合, 第二範囲の再生を開始し NPT 21 で停止する。NPT 12 の PAUSE でサーバーが第一段の NPT 13 を再生中なら直ちに停止する。NPT 16 の PAUSE なら第一段完了後に停止し第二の PLAY を破棄する。

別例: 10〜15 の後に 13〜20 (重複範囲) の再生要求がある場合, NPT=14 の PAUSE は第一段再生中に効き, 第二の PLAY は (PAUSE が第二の重複範囲の再生開始前に到着すると仮定して) 実質無視される。PAUSE の到着時刻にかかわらず NPT は 14 になる。

サーバーが Range で指定した時刻より先のデータを既に送っていても, PLAY はその時刻から再開する (クライアントがその時点以降のデータを破棄したと仮定)。これにより一時停止/再生の連続サイクルにギャップが生じない。

10.7 TEARDOWN​

TEARDOWN は指定 URI のストリーム配送を停止し, 関連リソースを解放する。URI がこの presentation の presentation URI なら, セッションに関連付けられた RTSP session identifier は無効になる。セッション記述ですべてのトランスポートパラメータが定義されていない限り, 再び再生する前に SETUP を発行しなければならない。

例: C->S: TEARDOWN rtsp://example.com/fizzle/foo RTSP/1.0 CSeq: 892 Session: 12345678 S->C: RTSP/1.0 200 OK CSeq: 892

10.8 GET_PARAMETER​

GET_PARAMETER は URI で指定された presentation またはストリームの parameter (パラメータ) の値を取得する。応答内容は実装に委ねられる。entity body のない GET_PARAMETER はクライアントまたはサーバーの生存確認 ("ping") に使える。

例:

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

"text/parameters" はパラメータ型の例にすぎない。本メソッドは意図的に緩く定義され, さらなる実験の後に応答内容を定める想定である。

10.9 SET_PARAMETER​

本メソッドは URI で指定された presentation またはストリームのパラメータ値の設定を要求する。

リクエストは SHOULD 単一パラメータのみ含め, 失敗理由をクライアントが判断できるようにする。複数含む場合, サーバーは MUST すべて成功設定できる場合にのみ処理する。サーバーは MUST 同一値への繰り返し設定を許可するが, 値の変更を禁じてもよい (MAY disallow)。

注: メディアストリームのトランスポートパラメータは MUST SETUP コマンドでのみ設定する。

トランスポートパラメータを SETUP に限定するのはファイアウォールのためである。

パラメータは細かく分かれており意味のあるエラー表示が可能になる。ただし原子設定が望ましい場合は複数同時設定も合理的でありうる。例: デバイス制御で, クライアントはカメラを pan させたくない, 同時に tilt が正しい角度にできない限り。

例:

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 Invalid Parameter

CSeq: 421 Content-length: 10 Content-type: text/parameters

barparam

"text/parameters" は例にすぎない。本メソッドは意図的に緩く定義され, 実験後に応答内容を定める想定である。

10.10 REDIRECT​

redirect 要求はクライアントが別サーバー位置に接続しなければならないことを通知する。必須ヘッダー Location を含み, クライアントがその URL にリクエストすべきことを示す。Range を含め, リダイレクトがいつ有効になるか示してもよい。クライアントがこの URI で送受信を続けたい場合, MUST 現在のセッションに TEARDOWN を発行し, 指定ホストで新セッションに SETUP する。

本例は所定の再生時刻で当該 URI のトラフィックを新サーバーへリダイレクトする:

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

10.11 RECORD​

本メソッドは presentation description に従いメディアデータの範囲の録画を開始する。タイムスタンプは開始・終了時刻 (UTC) を表す。時間範囲がなければ presentation description の開始または終了時刻を用いる。セッションが既に開始されていれば直ちに録画を開始する。

サーバーは録画データを request-URI または別 URI に保存するか決める。request-URI を用いない場合, 応答は SHOULD 201 (Created) とし, 要求の状態を記述し新リソースを参照するエンティティと Location ヘッダーを含める。

ライブ presentation の録画をサポートするメディアサーバーは MUST clock 範囲形式をサポートし, smpte は意味をなさない。

本例ではメディアサーバーは既に示された会議に招待されていた。

C->S: RECORD rtsp://example.com/meeting/audio.en RTSP/1.0 CSeq: 954 Session: 12345678 Conference: 128.16.64.19/32492374

10.12 Embedded (Interleaved) Binary Data (埋め込み (インタリーブ) バイナリデータ)​

特定のファイアウォール設計等により, サーバーは RTSP メソッドとストリームデータをインタリーブせざるを得ないことがある。必要でない限り一般に避けるべきであり, クライアント/サーバー操作を複雑にしオーバーヘッドを増やす。インタリーブバイナリは SHOULD RTSP が TCP で運ばれる場合にのみ用いる。

RTP パケット等のストリームデータは, ASCII の dollar sign (ドル記号) (16 進 24), 続けて 1 バイトの channel identifier (チャネル識別子), 続けてネットワークバイト順の 2 バイト整数によるカプセル化バイナリ長でカプセル化される。ストリームデータは直後に続き CRLF はないが上位層プロトコルヘッダーを含む。各 $ ブロックは正確に一つの upper-layer protocol data unit (上位層 PDU) (例: 一つの RTP パケット) を含む。

チャネル識別子は Transport ヘッダーの interleaved パラメータで定義される (セクション 12.39)。

トランスポートが RTP の場合, サーバーは TCP 接続上で RTCP もインタリーブする。既定では RTCP は RTP チャネルより大きい最初の利用可能チャネルで送られる。クライアント MAY 別チャネルを明示要求する。Transport の interleaved に二チャネルを指定する (セクション 12.39)。

二つ以上のストリームをこのようにインタリーブする場合, 同期に RTCP が必要。またネットワーク構成上必要なとき, TCP 制御接続で RTP/RTCP をトンネルし可能なら UDP に載せ替える便利な手段となる。

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}

に最終更新