Miracle Control Protocol (DVCP) Reference Documentation

Copyright (C) 2004 Ushodaya Enterprised Limited
Author: Dan Dennedy <dan@dennedy.org>
Last Revision: 2004-03-20
Translator: Ruslan Popov <radz@yandex.ru>
Last Revision: 2006-01-22

Протокол DVCP

Общий формат

DVCP является текстовым (ASCII, запрос/отклик) TCP протоколом, очень похожим на FTP и вдохновлённым примером SGI MVCP (Multiport Video Computer Protocol). Каждая команда может иметь от трёх до восьми символов и ноль или более аргументов. Каждый элемент (команда или аргумент) запроса отделяется пробелом, команда завершается символом \n. Аргументы, которые содержат пробелы, должны быть заключены в двойные скобки. Строка может иметь символ \r после \n. Запрос не делится на заголовок и тело.

Коды отклика

Отклики состоят из числового кода результата и краткого текстового описания отделённого от кода пробелом. Кавычки не применяются, несмотря на то, что описание может содержать пробелы. Коды, отражающие результат выполнения команды, сгруппированы сотнями в основные категории. Код из диапазона 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

Установка соединения

Подключение к miracle серверу можно производить с помощью утилиты telnet или своего клиента, который был разработан с использованием valerie API. Для подключения используёте порт 5250. Соединение может быть разорвано по желанию или с помощью команды BYE попросить сервер разорвать соединение.

Общая информация по командам

Все команды безразлично относятся к регистру символов, с аргументами это не всегда верно. Существует две категории команд: глобальные и для элементов. Глобальные команды работают на уровне сервера, элементарные команды работают с указанным элементом. Сервер miracle является многоэлементной системой. Элементы именуются как U?, где ? является номером элемента, например, U0. После добавления элементов к серверу, номер элемента увеличивается, первый элемент имеет имя U0.

Команда HELP выводит список всех команд с кратким описанием каждой, которые поддерживает сервер. Большинство команд принимают один аргумент (или вообще ни одного) кроме указания имени элемента. Иногда аргумент может быть необязательным. Необязательный аргумент всегда следует за обязательными аргументами. Все команды для работы с элементами требуют указания имени элемента.

Глобальные команды

Обозначение аргументов:

• {} - обязательный аргумент;
• [] - необязательный аргумент;
• () - одно из предопределённых значений.

Команда	Описание
HELP	Выводит список команд и их краткое описание.
BYE	Закрывает соединение с сервером.
SHUTDOWN	Останавливает сервер и обрывает все клиентские соединения.
SET {key=value}	Устанавливает глобальный параметр конфигурации сервера. В настоящее время, единственным ключом может быть root, который предназначен для установки стандартного пути до каталога для команд CLS и LOAD. По умолчанию равен /.
GET {key}	Получает текущее значение параметра конфигурации. Значение возвращается в теле отклика.
CLS {path}	Выводит список клипов и подкаталогов находящихся в {path} на сервере. Поддерживается отображение только подкаталогов, обычных нескрытых файлов, символических ссылок и NFS ресурсов. Тело отклика отформатировано так, что одна строка содержит информацию об одном файле или каталоге. Имя файла или подкаталога всегда приводится в двойных кавычках, если оно содержит в себе пробелы. Подкаталоги выводятся перед файлами и их имена завершаются символом /. Файлы приводятся с указанием их размера в байтах во втором столбце.
RUN {file}	Выполнить команды из указанного файла, который располагается на файловой системе сервера. Команды выполняются одна за другой, без задержек, до тех пор пока не закончится список команд или одна из команд не вернёт код возврата отличный от диапазона 200. Тело отклика содержит каждую отосланную команду с её аргументами, за командой указан код возврата и тело отклика.
STATUS	Применяем команду USTA к каждому элементу. При изменении состояния элемента, сервер возвращает строку, сообщая о состоянии элемента.

Управление элементами

Приведённые в этом разделе глобальные команды предназначены для управления DV элементами внутри сервера. В настоящее время работает ограничение, максимум четыре элемента, которые не могут быть удалены. Каждый элемент может находится в рабочем и нерабочем состояниях. Элементы, находящиеся в нерабочем состоянии, не могут быть использованы. Любая команда для элементов выполненная над нерабочим элементом будет завершена с кодом ошибки 403.

Команда	Описание
NLS	Пока ещё не реализована в miracle.
UADD mlt-consumer[:argument]	Добавляет элемент, созданный на основе идентификатора потребителя и необязательного аргумента. Если потребитель не найден, то элемент всё равно будет добавлен, правда в нерабочем состоянии. Впоследствии, добавив устройство к шине, элемент автоматически перейдёт в рабочее состояние. Тело отклика содержит имя нового элемента: U0, U1, U2 или U3. Канал является необязательным параметром.

| ULS | Выводит список элементов. Тело отклика содержит запись, разделённую пробелами, для каждого элемента содержащую следующие поля:

• имя элемента (одно из U0, U1, U2 или U3);
• mlt-consumer[:argument] - см. команду UADD;
• 1394 node GUID (defunt - всегда 0 для miracle for now);
• флаг состояния (1 - рабочее, 0 - нерабочее). |

SHUTDOWN

Производит выключение сервера miracle.

Команды для элементов

Первым аргументом у команд данной категории всегда будет имя элемента (одно из U0, U1, U2 или U3). Элемент должен быть загружен вместе с файлом перед тем, как что-либо проигрывать. Термин клип соответствует файлу загруженному в элемент. Клип может содержать точки начала и завершения для определения области подлежащей проигрыванию. По умолчанию, эти точки настроены так, чтобы проигрывать весь клип. Следовательно, нумерация кадров в клипе начинается с нуля.

Команда	Описание
USET {unit} {key=value}	Устанавливает параметр конфигурации элемента. Ключ может принимать одно из значений: eof, points. Параметр eof определяет действие движка, когда он достигает конца клипа. Параметр может принимать одно из следующих значений: stop (остановить), loop (зациклить), continue (продолжить) или pause (пауза). По умолчанию используется pause. Параметр points определяет ограничивает ли движок область проигрывания точками начала и завершения. Параметр может принимать одно из следующих значений:=use= (использовать), ignore (игнорировать).
UGET {unit} {key}	Получает значение параметра конфигурации элемента. Имя параметра может быть одним из: eof, points. Тело отклика содержит значение параметра. См. команду USET для подробностей о каждом параметре.

| LIST {unit} | Вывести список клипов связанных с элементом. Тело отклика содержит две секции. Первая секция - это одна строка содержащая номер поколения списка проигрывания ассоциированного с элементом (целое, начинающееся с нуля, увеличивающееся с каждым действием, применённым к списку проигрывания). Вторая секция содержит записи, разделёнными пробелами, для каждого клипа в элементе:

• индекс клипа, начинается с 0;
• имя файла;
• точка начала;
• точка завершения;
• реальная длина файла;
• вычисленная длина файла. |

Если указан USET points=use (обычно так и происходит), то вычисленный размер равен (out-in)+1. В противном случае возвращается реальная длина файла.
LOAD {unit} {filename} [in out]	Загрузить клип в элемент.
	Необязательные параметры in и out используются для определения абсолютных номеров кадров для точек начала и завершения.
	Устанавливает текущую позицию проигрывания на первый кадр клипа.
	Если перед именем файла указать символ !, то поток чтения с диска будет удалять только одинаковые кадры из конца своей буферной очереди (от предыдущего загруженного и проигрываемого клипа). Иначе, miracle отчищает все свои буферы, мгновенно выполняя загрузку файла. Команды LOAD , USET eof=pause и расширенная USTA информация может быть использована для создания списков проигрывания на клиентской стороне (см. демонстрационную программу).
APND {unit} {filename} [in out]	Добавляет клип в список проигрывания элемента.
	Необязательные параметры in и out используются для определения абсолютных номеров кадров для точек начала и завершения.
=INSERT {unit} {filename}	Вставляет клип в список проигрывания элементов на указанное место, используется абсолютное или относительное позиционирование.
REMOVE {unit} [ [+	-]clip ]	Удаляет клип, указанный индексом или позицией относительно текущего проигрываемого клипа.
CLEAN {unit}	Удаляет все проигрываемые клипы.
WIPE {unit}	Удаляет все клипы перед текущим проигрываемом клипом.
MOVE {unit} [+	-]clip [ [+	-]clip ]	Перемещает клип в списке проигрывания в указанную позицию (абсолютную или относительную).
PLAY {unit} [speed]	Запускает проигрывание с текущей позиции. По умолчанию используется 100% скорость, если не указано обратное. Скорость представляется в виде процентного значения умноженного на 10. Следовательно, скорость по умолчанию будет равна 1000 (1х или 100%), 2х будет равна 2000. Отрицательная скорость приводит к проигрыванию в обратном направлении.
STOP {unit}	Прекращает воспроизведение.
PAUSE {unit}	Приостанавливает воспроизведение, удерживая текущую позицию.
REW {unit}	Перемотка назад. Если команда исполняется во время воспроизведения, то скорость воспроизведения устанавливается в 2000 (200%). Если же воспроизведение было остановлено, то текущая позиция сбрасывается на первый кадр. Первый кадр зависит от точек начала и завершения элемента, а также от точки начала установленной с помощью команды SIN для клипа. Устанавливает точку начала для текущего загруженного клипа. Кадры считаются от нуля, номер кадра не зависит от точки начала текущего клипа.
FF {unit}	Перемотка. Если команда исполняется во время воспроизведения, то скорость воспроизведения устанавливается в -2000 (200% в обратную сторону). Если же воспроизведение было остановлено, то текущая позиция сбрасывается на первый кадр. Первый кадр зависит от точек начала и завершения элемента, а также от точки начала установленной с помощью команды SIN для клипа.
STEP {unit} {number-of-frames}	Изменяет текущую позицию на указанное количество кадров, которое может быть положительным и отрицательным.
GOTO {unit} {frame-number} [ [+	-]clip ]	Изменяет текущую позицию с помощью перехода на указанный кадр клипа. Номер кадра отсчитывается от нуля и является абсолютным внутри клипа. Это означает, что нумерация клипа относительна начала клипа. Команда не изменяет состояние воспроизведения.
SIN {unit} {frame-number} [ [+	-]clip ]	Устанавливает точку начала для текущего загруженного клипа. Точка начала - это логический кадр с которого начинается клип. Номер кадра отсчитывается от нуля и является абсолютным для клипа. Если указан номер кадра -1, то позиция устанавливается в 0.
SOUT {unit} {frame-number} [ [+	-]clip ]	Устанавливает точку завершения для текущего загруженного клипа. Точка завершения аналогична по свойствам точке начала. Если указан номер кадра -1, то позиция устанавливается на последний кадр клипа.

| USTA {unit} | Получает отчет о состоянии элемента. Тело отклика содержит следующие поля разделённые пробелами:

• номер элемента - U0, U1, U2 или U3 без префикса U;
• режим - один из offline, not_loaded, playing, stopped, paused, disconnected или unknown, причём unknown означает, что элемент не был добавлен, а disconnected - что сервер закрыл соединение с клиентом;
• имя текущего клипа - имя файла;
• текущая позиция в клипе - абсолютный номер кадра;
• скорость - скорость воспроизведения в % * 10;
• количество кадров секунду - величина для загруженного клипа;
• текущая точка начала - номер стартового кадра;
• текущая точка завершения - номер завершающего кадра;
• длительность клипа;
• buffer tail clip name: filename
• buffer tail position: in absolute frame number units
• buffer tail in-point: starting frame number
• buffer tail out-point: ending frame number
• buffer tail length: length of clip in buffer tail
• флаг свободного перемещения по контенту - указывает можно ли перемещаться по клипу;
• номер поколения списка проигрывания;
• индекс текущего клипа. |

Статус содержит информацию полученную не только из отправленного кадра, но и из только что прочтённого с диска и добавленного в конец очереди ожидания обработки.

| XFER {unit} {target-unit} | Перемещает клип в целевой элемент. Информация о клипе включает в себя информацию о точках начала и завершения. Точки целевого элемента устанавливаются в use..