10 Method Definitions (方法定义)

10 Method Definitions (方法定义)

Method token (方法记号) 指明要对 Request-URI (请求 URI) 所标识资源执行的操作。方法区分大小写。将来可定义新方法。方法名 MUST NOT 以字符 $ (十进制 24) 开头, 且 MUST 为 token (记号)。方法概要见表 2。

method	direction	object	requirement
DESCRIBE	C->S	P,S	recommended
ANNOUNCE	C->S, S->C	P,S	optional
GET_PARAMETER	C->S, S->C	P,S	optional
OPTIONS	C->S, S->C	P,S	required (S->C: optional)
PAUSE	C->S	P,S	recommended
PLAY	C->S	P,S	required
RECORD	C->S	P,S	optional
REDIRECT	S->C	P,S	optional
SETUP	C->S	S	required
SET_PARAMETER	C->S, S->C	P,S	optional
TEARDOWN	C->S	P,S	required

表 2: RTSP 方法概览, 方向, 及其作用对象 (P: presentation (演示), S: stream (流))

对表 2 的说明: PAUSE 为 recommended (推荐), 但并非 required (必需), 因为完全可以构建不支持该方法的全功能服务器, 例如用于直播。若服务器不支持某特定方法, 它 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 description, 而非仅附加部分, 以便可删除各组成部分。

示例:

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" 响应。为利于穿越防火墙, 客户端 MUST 指明传输参数, 即使它无法影响这些参数, 例如服务器通告固定组播地址时。

由于 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 (正常播放时间) 定位到所指定 range (范围) 的起点, 并投递流数据直至范围结束。PLAY 请求可 pipelined (流水线排队); 服务器 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 参数可用于同步来自不同源的流。

对 on-demand stream (点播流), 服务器以将实际播放的范围响应。若媒体源要求将请求范围对齐到有效帧边界, 该范围可能与请求不同。若请求未指定范围, 响应中返回当前位置。响应中范围的单位与请求中相同。

播放完所需范围后, 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 或流组, 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 (暂停点)"。头部 MUST 含恰好一个值而非时间范围。流的 normal play time 设为暂停点。暂停请求在服务器首次遇到当前未决 PLAY 请求中指定的时间点时生效。若 Range 指定的时间落在任何当前未决 PLAY 之外, 返回错误 "457 Invalid Range"。若某 media unit (媒体单元) (如音频或视频帧) 恰在暂停点开始呈现, 则既不播放也不录制。若缺少 Range 头部, 收到消息后立即中断流投递, 暂停点设为当前 normal play time。

PAUSE 请求丢弃所有排队的 PLAY。但媒体流中的暂停点 MUST 保留。随后不带 Range 的 PLAY 从暂停点恢复。

例如, 若服务器有待执行的播放范围 10-15 与 20-29, 然后收到 NPT 21 的暂停请求, 它将开始播放第二段并在 NPT 21 停止。若暂停针对 NPT 12 且服务器在 NPT 13 服务第一段, 服务器立即停止。若暂停针对 NPT 16, 服务器在完成第一段后停止并丢弃第二段 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 禁止更改参数值。

注意: 媒体流的传输参数 MUST 仅通过 SETUP 命令设置。

将传输参数限制在 SETUP 是为了利于防火墙。

参数细粒度划分以便有更明确的错误指示。但若希望原子设置多个参数, 允许同时设置若干参数可能有意义。设想设备控制: 客户端不希望除非云台也能转到正确角度, 否则相机不 pan (摇摄)。

示例:

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 (美元符号) (十六进制 24), 后跟一字节 channel identifier (信道标识符), 后跟 network byte order (网络字节序) 的二进制两字节整数表示的封装二进制数据长度封装。流数据紧随其后, 无 CRLF, 但含上层协议头部。每个 $ 块恰好含一个 upper-layer protocol data unit (上层协议数据单元), 例如一个 RTP 包。

信道标识符在 Transport 头部的 interleaved 参数中定义 (第 12.39 节)。

传输选择为 RTP 时, 服务器也在 TCP 连接上交错 RTCP 消息。默认地, RTCP 包在高于 RTP 信道的第一个可用信道发送。客户端 MAY 显式请求在另一信道上传 RTCP。做法是在 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}