MVCP 协议
Copyright (C) 2004-2014 Meltytech, LLC
Last Revision: 2011-04-17
通用格式
--------------
MVCP 是一种基于 ASCII 的请求/响应 TCP 协议，与 FTP 非常相似，
并受 SGI MVCP [1]（Multiport Video Computer Protocol，多端口视频
计算机协议）启发。每条命令长三到八个字符，其后跟零个或多个
参数。请求中的每个条目（命令或参数）以空格分隔，并以换行符
结束。含有空格的参数必须用双引号包围。换行符必须包含一个
换行符（line feed），其前可以可选地带一个回车符（carriage
return）。没有请求头行或请求体。
[1] http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=bks&fname=/SGI_EndUser/MSB3xx_UG/ch09.html
响应码
--------------
响应由一个数字结果码加上一个空格、再接一段对结果的简短文字
描述组成。描述不做任何引号处理，无论其中是否含有空格。结果码
按百位数分组归入响应的大类。200-299 范围内的任何结果都视为
成功，300 及以上的都是错误或异常。大多数响应不包含响应体，
只有某些报告信息的成功结果、以及有时 500 Server Error 会返回
具体内容。
200 结果码不包含响应体。
201 结果码的响应体包含一行或多行，并以一个空行结束该响应。
202 结果码的响应体只包含单独一行响应。
400 范围内的错误表示被正常处理的错误：由于协议语法错误，或
一个或多个参数的校验问题，命令无法执行其动作。这通常说明
客户端发出了一个非法请求，责任在客户端。
500 范围内的错误表示服务器错误或异常。
以下是响应码及其描述的列表：
200 OK
201 OK
202 OK
400 Unknown command
401 Operation timed out
402 Argument missing
403 Unit not found
404 Failed to locate or open clip
405 Argument value out of range
500 Server Error
建立连接
-------------------------
可以使用 telnet 或自定义客户端连接到 melted 服务器，最好使用
libmvcp 客户端 API 开发的客户端。默认端口是 5250。连接可以随时
中断，或使用 BYE 命令请求服务器终止连接。
命令的通用信息
---------------------------
所有命令都不区分大小写。参数可能区分大小写，也可能不区分。
命令分为两类：全局命令和单元命令。全局命令在服务器级别操作。
单元命令针对某个特定的单元。melted 是一个多单元系统。单元
命名为 U?，其中 ? 是单元编号，例如 U0。随着单元被添加到
服务器，单元编号递增；第一个单元是 U0。
HELP 命令列出服务器已知的所有命令，并附带其用途和参数的简短
描述。除单元名之外，大多数命令接受零个或一个参数。有时参数
是可选的，可选参数总是跟在必选参数之后。所有单元命令都要求
提供单元名参数。
{} = 必选参数
[] = 可选参数
() = 预定义值集合中的一个
全局命令
---------------
HELP
列出命令及其简短描述。
BYE
关闭连接。
SHUTDOWN
关闭服务器及所有客户端连接。
SET {key=value}
设置一个全局服务器配置属性。
目前唯一计划支持的 key 是 "root"，用于为 CLS 和 LOAD 命令设置
基准目录路径。root 的默认值是 /。
GET {key}
读取某个配置属性的当前值。
该值单独位于响应体中返回。
CLS {path}
列出服务器上 {path} 路径下的剪辑和子目录。
仅支持子目录、非隐藏的普通文件、符号链接和 NFS 共享。
响应体每个条目占一行。
子目录/文件的名称总是用双引号包围，以防其中含有空格。
子目录排在文件之前列出，且其名称末尾带一个 /。
文件条目的第二列位置是以字节为单位的文件大小。
RUN {file}
处理位于服务器上的某个文件中的命令。
命令逐条依次执行、中间无延迟，直到到达文件末尾，或某条命令
返回不在 200 范围内的响应码为止。
响应体包含连同其参数一起发送的每条命令，随后是每条命令的
响应状态码和响应体。
STATUS
为每个单元回复 USTA 的输出，并且不再接受后续输入。每当单元
的状态发生变化，服务器就返回包含该单元状态的新行。
单元管理
以下全局命令管理服务器内的放像单元。目前最多四个单元，且
单元不可被移除。每个单元可处于在线（online）或离线（offline）
状态。离线单元不可使用，对离线单元发出的任何单元命令都会
得到 403 响应。
NLS
* 在 melted 中尚未实现 *
UADD mlt-consumer[:argument]
根据 mlt-consumer id 及可选的构造函数参数添加一个单元。
如果找不到该消费器，单元仍会被添加，但处于离线状态。之后
当把设备添加到总线时，该单元会自动变为在线。
响应体包含新单元的名称：U0、U1、U2 或 U3。
Channel 是一个可选设置。
ULS
列出各单元。
响应体中每个单元占一行、以空格分隔，包含以下各列：
- 单元名称（U0、U1、U2 或 U3 之一）
- uadd 时给定的 mlt-consumer[:argument]
- 1394 节点 GUID（默认——目前在 melted 中总是 0）
- 在线标志（1 = 在线，0 = 离线）
SHUTDOWN
关闭服务器。
单元命令
-------------
任何单元命令的第一个参数是单元名（U0 - U3）。单元必须先装载
一个文件才能播放任何内容。"剪辑"（clip）指装载进单元中的
文件。剪辑可以包含入点（in point）和出点（out point）来设定
播放区域。默认入点为 0，默认出点为文件总帧数减一。因此所有
帧位置都从零开始计数。
USET {unit} {key=value}
设置单元的某个配置属性。
Key 是以下之一：eof、points。
"eof" 属性决定回放到剪辑末尾时播放引擎的行为。eof 属性取以下
值之一：stop、loop、continue 或 pause。默认值是 pause。
"points" 属性决定播放引擎是否把播放区域限制在入点和出点之间。
它取以下值之一：use、ignore。
UGET {unit} {key}
读取单元的某个配置属性。
Key 是以下之一：eof、points。
响应体只包含该 key 的值。各属性的含义参见 USET。
LIST {unit}
列出与单元相关联的剪辑。
响应体由两部分组成——第一部分是一行，包含与该单元关联的
播放列表（playlist）的代号（一个从 0 开始的整数，每次执行
改变播放列表的操作后递增）。第二部分为播放列表中的每个剪辑
提供一行、以空格分隔，包含以下各列：
- 剪辑索引（从 0 开始）
- 文件名
- 入点
- 出点
- 文件的真实长度
- 计算得到的文件长度
当指定 USET points=use（默认）时，计算长度是 (出点-入点)+1。
当忽略入出点时，返回文件的真实长度。
LOAD {unit} {filename} [in out]
向单元装载一个剪辑。
可选地把入点和出点设定为指定的绝对帧号。
会将当前位置设为剪辑的第一帧。
在文件名前加 '!' 前缀，告知磁盘读取线程只从缓冲区队列的尾部
移除重复帧（来自之前已装载并在播放的剪辑）。否则，melted 在
LOAD 时会冲刷其全部缓冲区，以使 LOAD 的效果即时生效。
LOAD !、USET eof=pause 以及扩展的 USTA 信息可以用于客户端侧的
播放列表（参见演示程序）。
APND {unit} {filename} [in out]
向单元的播放列表追加一个剪辑。
可选地把入点和出点设定为指定的绝对帧号。
INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
在指定的剪辑索引处、或相对于当前正在播放的剪辑索引处，向
单元的播放列表插入一个剪辑。
REMOVE {unit} [ [+|-]clip ]
从指定的剪辑索引处、或相对于当前正在播放的剪辑索引处，
移除一个剪辑。
CLEAN {unit}
移除除正在播放的剪辑之外的所有剪辑。
WIPE {unit}
移除正在播放的剪辑之前的所有剪辑。
MOVE {unit} [+|-]clip [ [+|-]clip ]
把播放列表中的一个剪辑移动到指定位置，或相对于当前正在播放
的剪辑的位置。
PLAY {unit} [speed]
从当前位置开始单元播放。
未指定速度时默认为 100%。
速度以百分比值乘以 10 表示。因此默认播放速度是 1000
（1X 即 100%），2X 是 2000。
负的速度值表示倒放。
STOP {unit}
终止单元播放，不再输出任何视频。
PAUSE {unit}
暂停单元播放，使当前帧位置被无限期保持。
REW {unit}
回滚单元。
如果单元正在播放，REW 会把播放速度设为 -2000（200%）。
如果单元已停止，则把帧位置重置到第一帧。第一帧取决于
"points" 单元配置属性，以及该剪辑是否已用 SIN 命令建立了
入点。
设置当前装载剪辑的入点。
帧号从零开始且是绝对的，不依赖剪辑当前的入点。
帧号为 -1 时，将入点重置为 0。
FF {unit}
快进单元。
如果单元正在播放，FF 会把播放速度设为 2000（200%，
倒放方向）。
如果单元已停止，则把帧位置重置到第一帧。第一帧取决于
"points" 单元配置属性，以及该剪辑是否已用 SIN 命令建立了
入点。
STEP {unit} {number-of-frames}
按指定的帧数调整当前帧位置。
number-of-frames 可接受正值或负值。
GOTO {unit} {frame-number} [ [+|-]clip ]
把当前帧位置设为 frame-number。
帧号从零开始，且是剪辑内的绝对位置，即相对于文件开头而非
剪辑入点。
该命令不会改变单元的播放状态。
SIN {unit} {frame-number} [ [+|-]clip ]
设置当前装载剪辑的入点。
入点是剪辑的逻辑起始帧。
帧号从零开始且是绝对的，不依赖剪辑当前的入点。
帧号为 -1 时，将入点重置为 0。
SOUT {unit} {frame-number} [ [+|-]clip ]
设置当前装载剪辑的出点。
出点是剪辑的逻辑最后一帧。
帧号从零开始且是绝对的，不依赖剪辑当前的出点。
帧号为 -1 时，将出点重置为文件总帧数减 1。
USTA {unit}
获取单元状态报告。
响应体包含以下以空格分隔的字段：
- 单元号：U0、U1、U2 或 U3（不带 "U" 前缀）
- 模式：(offline|not_loaded|playing|stopped|paused|disconnected|unknown)
"unknown" 表示该单元尚未被添加
"disconnected" 表示服务器已关闭与客户端的连接。
- 当前剪辑名：文件名
- 当前位置：以绝对帧号计
- 速度：播放速率（百分比 * 10）
- fps：已装载剪辑的每秒帧数
- 当前入点：起始帧号
- 当前出点：结束帧号
- 剪辑长度
- 缓冲区尾部剪辑名：文件名
- 缓冲区尾部位置：以绝对帧号计
- 缓冲区尾部入点：起始帧号
- 缓冲区尾部出点：结束帧号
- 缓冲区尾部长度：缓冲区尾部中剪辑的长度
- 可 seek 标志：指示当前剪辑是否可 seek（与队首相关）
- 播放列表代号
- 当前剪辑索引（与队首相关）
该状态报告不仅基于当前正在输出的帧（上述 current），还基于
磁盘读取线程最近读取并添加到输入缓冲区队列尾部的帧（上述
buffer tail）。
XFER {unit} {target-unit}
把该单元的剪辑转移到目标单元。
剪辑本身即包含入点和出点信息。
目标单元的 "points" 配置属性会被设为 "use"。
PUSH {unit}
{size}
{XML}
向单元追加一个带内（in-band）MLT XML 文档。
注意：size 和 XML 参数各自位于新行上。
size 是 XML 负载的字节大小。
如果 XML 格式 malformed，或 XML 生产器（XML producer）解析失败，
返回 404。