Протокол для приложений управления микшерной консолью SYNERGY MINI¶

Общее описание протокола¶

Протокол предназначен для связи микшера с внешним приложением или ПО с целью управления фейдерами и состояниями линеек и других блоков микшерной консоли, а также с целью получения состояния линеек и других блоков консоли.

Для таких внешних приложений микшер реализует TCP-сервер, к которому могут подключаться приложения-клиенты. Протокол позволяет приложению и микшеру обмениваться сообщениями.

С точки зрения протокола и сервер (консоль), и клиент (вещательное или управляющее приложение) могут посылать и принимать сообщения, на уровне протокола ответного сообщения не предусматривается.

Примечание: логика ответа, если она необходима, и тайм-ауты должны обрабатываться на уровне приложения.

Сервер микшера может поддерживать более одного TCP соединения от внешних приложений.

Примечание: логика работы микшера под контролем нескольких приложений протоколом не определяется и зависит от реализации.

Протокол ориентирован на работу в реальном времени. Реализация протокола на передающей стороне должна обеспечивать немедленную посылку сообщения через TCP-соединение с партнером, буферизация и введение задержек не допускается, если они не связаны с ограничениями от производительности IP-сети. Реализация протокола на приемной стороне должна обеспечивать доставку, десериализацию и обработку сообщения немедленно после приема нулевого байта, терминирующего очередной JSON-объект входного потока.

Кодирование и синтаксис сообщений¶

Одно сообщение представляет собой строку текста в кодировке UTF-8 с терминирующим нулем. Сообщения следуют одно за другим в потоке байтов TCP-соединения. Строка текста кодируется в JSON-синтаксисе.

Примечание: синтаксис текстового представления JSON-объектов определяется в документе RFC-7159; см. также синтаксические диаграммы БНФ в последнем разделе данного описания.

Каждая строка, терминированная нулем, содержит либо одно сообщение, либо группу сообщений. Второй вариант представляет собой способ одновременной посылки группы сообщений, которые должны обрабатываться приложением или консолью атомарно как одно "макросообщение". Синтаксически, одно сообщение соответствует одному JSON-объекту, а группа - массиву JSON-объектов. То есть, после выделения из TCP-потока строки, терминированной нулевым байтом, ее содержимое должно быть либо отдельным JSON-объектом, либо массивом JSON-объектов. Другие варианты не являются синтаксически правильными с точки зрения данного протокола.

Примечание: синтаксис JSON разрешает отдельно стоящие строки, литералы, числа или массивы массивов, но все эти конструкции неправильны для сообщений данного протокола.

Каждое сообщение, т.е. либо единственный JSON-объект, либо каждый в массиве в случае использования группировки сообщений, обязательно имеет поле с именем "msg" и строковым значением. Поле с именем "msg" определяет тип сообщения и является единственным обязательным полем. Тип сообщения (т.е. содержимое поля "msg") определяет какой набор других полей должен или может присутствовать в JSON-объекте сообщения. Реализация протокола выполняет сериализацию и десериализацию всех известных ей полей, неизвестные поля JSON-объекта при приеме игнорируются.

Все ключевые слова (названия параметров, списки значений) должны записываться в сообщениях строчными буквами (в lowercase). Протокол чувствителен к регистру символов и ключевые слова не должны опознаваться реализацией при написании прописными буквами или смешанными регистрами сивмолов (т.е. в uppercase, capitalized и в любых других вариантах). Параметры, переносящие текстовые значения (например, названия линеек фэйдера, имена пресетов и тому подобное) могут записываться любыми символами и содержать любой текст, если обратное не оговорено в описании конкретного сообщения и/или параметра.

Сообщения: общие¶

Сообщение: msg = "getdevicedesc": Приложение-> Микшерная консоль: Запрос типа/модели консоли¶

Посылается на микшерную консоль приложением с целью получить информацию о модели, типе, производителе подключаемого устройства.

{
   "msg":"getdevicedesc"
}

Сообщение: msg = "devicedesc": Приложение-> Микшерная консоль: Ответ на типа/модели консоли¶

Посылается микшерной консолью в ответ на сообщение "getdevicedesc".

{
 "msg":"devicedesc",
 "model":"xxx1",
 "manufacturer":"xxx2",
 "version":"xxx3",
 "protocol_level":nnn
}

Параметры «модель», «производитель» и «версия» являются просто информационными строками.

Параметр «protocol_level» в будущем может повлиять на некоторые детали взаимодействия между приложением и консолью. На данный момент его значение фиксируется на целочисленную константу 1 и соответствует поколению спецификации протокола (первая цифра в версии спецификации протокола).

Сообщение: msg = "idle": В любом направлении: Heartbeat/Keep-alive¶

Посылается в любом направлении: как приложением, так и микшерной консолью. Информирует участников о состоянии своей работоспособности.

Сообщения: линейки микшера¶

Сообщение: msg = "getlinelist": Приложение -> Микшерная консоль : Запрос списка линеек микшера.¶

Посылается на микшерную консоль с целью получить количество и имена линеек.

{
   "msg":"getlinelist"
}

Сообщение: msg = "linelist" : Микшерная консоль -> Приложение : Ответ на запрос о списке линеек.¶

Посылается микшерной консолью в ответ на сообщение "getline"

{
   "msg":"linelist",
   "lines":[
             "xxx1",
             "xxx2",
              . . .,
             "xxxN"
           ]
}

• "xxx" - string - имя линейки
• в массиве "lines" номера линеек соответствуют значению индекса элемента линейки в массиве плюс 1. То есть, элемент с нулевым индексом массива - первая линейка, с индексом один - вторая, и так далее.

Сообщение: msg = "getlineinfo": Приложение -> Микшерная консоль : Запрос состояния линейки.¶

Посылается на микшерную консоль с целью получить состояние линейки, или линеек.

{
   "msg":"getlineinfo",
   "num":nnn
}

• nnn - integer - номер линейки

Параметр nnn должен идентифицировать опрашиваемую линейку.
Если параметр не указан (отсутствует в сообщении), то консоль должна послать группу сообщений, описывающих состояние всех линеек. Протокол допускает присылать их приложению как группой, так и отдельными сообщениями.

Сообщение: msg = "lineinfo" : Микшерная консоль -> Приложение : Ответ на запрос о состоянии линейки/нотификация об изменении состояния линейки.¶

Посылается микшерной консолью в двух случаях:

• как ответ на сообщение "getline" стороны приложения-клиента, либо
• как незапланированное сообщение по инициативе микшерной консоли при изменении любого из параметров данной линейки (например, когда оператор передвинул фэйдер на линейке, или нажал на кнопку и состояние линейки изменилось)

{
   "msg":"lineinfo",
   "num":nnn,
   "name":"xxx",
   "state":"sss1",
   "pfl":"sss2",
   "gain":ggg
}

• nnn - integer - номер линейки
• "sss1" - string - состояние: одна из следующих строк:
  • "off" — линейка выключена
  • "on" — линейка включена
  • "waitbutton" — линейка выключена, ожидает нажатия кнопки START
  • "waitfader" — линейка выключена, ожидает подъема фэйдера
• "sss2" - состояние PFL
  • "off" — PFL на линейке выключен
  • "on" — PFL на линейке включен
• ggg - float - коэффициент передачи линейки в децибелах

msg = "setlineinfo": Приложение -> Микшерная консоль : Изменить состояние линейки.¶

Посылается на микшерную консоль с целью изменить состояние линейки

{
   "msg":"setlineinfo",
   "num":nnn,
   "state":"sss1",
   "pfl":"sss2",
   "gain":ggg
}

• nnn - integer - номер линейки
• "sss1" - string - состояние: одна из следующих строк:
  • "off" — линейка выключена
  • "on" — линейка включена
  • "waitbutton" — линейка выключена, ожидает нажатия кнопки START
  • "waitfader" — линейка выключена, ожидает подъема фэйдера
• "sss2" - состояние PFL
  • "off" — PFL на линейке выключен
  • "on" — PFL на линейке включен
• ggg - float - коэффициент передачи линейки в децибелах

Параметр nnn должен идентифицировать опрашиваемую линейку.

Сообщения: Общее управление микшированием¶

msg = "setcue": Приложение -> Микшерная консоль : Изменить состояние подслушки микшерной консоли¶

Посылается на микшерную консоль с целью изменить общее состояние подслушки микшерной консоли.

{
   "msg":"setcue",
   "state":"sss",
}

• "sss" - string - состояние: одна из следующих строк:
  • "off" — линейка выключена
  • "on" — линейка включена

Сообщения: Кнопки и другие обобщенные параметры¶

msg = "getparlist": Приложение -> Микшерная консоль : Запрос списка параметров микшера.¶

Посылается на микшерную консоль с целью получения количества и полного списка поддерживаемых консолью параметров.

{
   "msg":"getparlist"
}

Сообщение: msg = "parlist" : Микшерная консоль -> Приложение : Ответ на запрос о списке параметров.¶

Посылается микшерной консолью в ответ на сообщение "getparlist".

{
   "msg":"parlist",
   "pars":[
             "id-xxx1",
             "id-xxx2",
              . . .,
             "id-xxxN"
           ]
}

• "id-xxx…" - string - имя параметра
• порядок параметров в массиве "pars" не определен и существенного значения не имеет.

Сообщение: msg = "getpar": Приложение -> Микшерная консоль : Запрос состояния параметра (параметров).¶

Посылается на микшерную консоль с целью получить состояние параметра, или параметров.

{
   "msg":"getpar",
   "id":"id-xxx"
}

• "id-xxx" - string - идентификация запрашиваемого параметра (из списка полученного в сообщении "parlist")

Идентификатор "id-xxx" должен определять для консоли запрашиваемый параметр.
Если поле "id" не указано (отсутствует в сообщении), то консоль должна послать несколько сообщений, описывающих состояние всех параметров (по одному сообщению "par" для каждого параметра).
Протокол допускает присылать приложению информацию о нескольких параметрах как группой (массив JSON), так и отдельными сообщениями.

Сообщение: msg = "par" : Микшерная консоль -> Приложение : Ответ на запрос о состоянии параметра/нотификация об изменении состояния параметра.¶

Посылается микшерной консолью в двух случаях:

• как ответ на сообщение "getpar" стороны приложения-клиента, либо
• как незапланированное сообщение по инициативе микшерной консоли при изменении состояние или значения данного параметра (например, когда оператор покрутил кодер параметра, или нажал на кнопку и состояние параметра изменилось)

{
   "msg":"par",
   "id":"id-xxx",
   "val":"val-xxx"
}

• "id-xxx" - string - идентификация параметра (из списка полученного в сообщении "parlist")
• "val-xxx" - string - значение состояния.

Значение может иметь строковый или числовой тип, тип и набор возможных значений специфичны для конкретного параметра и протоколом не определяются. Для значений параметров, которые имеют два состояния, протокол рекомендует использовать одну из следующих строк:

• "off" — параметр выключен (например, кнопка отжата, или перешла в отжатое состояние, если это событие);
• "on" — параметр включен (например, кнопка нажата, или перешла в нажатое состояние, если это событие).

В событиях (сообщениях нотификации об изменении состояния параметра) должно передаваться новое (измененное) значение параметра.

msg = "setpar": Приложение -> Микшерная консоль : Изменить состояние параметра.¶

Посылается на микшерную консоль с целью изменить состояние указанного параметра.

{
   "msg":"setpar",
   "id":"id-xxx",
   "val":"val-xxx"
}

• "id-xxx" - string - идентификация устанавливаемого параметра (из списка полученного в сообщении "parlist")
• "val-xxx" - string - требуемое новое значение состояния.

 Пример для кнопки "cue"¶

При нажатии кнопки консоль посылает сообщение:

{
   "msg":"par",
   "id":"cue_button",
   "val":"on"
}

При отпускании кнопки консоль посылает сообщение:

{
   "msg":"par",
   "id":"cue_button",
   "val":"off"
}

Части протокола, специфичные для производителей/моделей консолей¶

Вещательная микшерная консоль Clyde (ТР-9)¶

В этой главе описываются общие параметры для микшерных консолей Clyde.

Поддерживаемые параметры должны быть перечислены в сообщении "parlist" консоли в ответ на сообщение "getparlist" приложения. Параметры суммируются в таблице ниже с указанием того, могут ли они быть использованы в сообщениях "getpar" и "setpar" команд из приложения на консоль.

Примечание. Каждый поддерживаемый параметр может появиться в "par"-сообщении от консоли к приложению как сообщение о смене статуса или как результат "getpar"-запроса.

Название параметра	Использование в "getpar"	Использование в "setpar"	Описание
mic_on	да	нет	Уведомление/Запрос: Любой микрофон в эфире. Значения: “on”, “off”
preset	да	да	Уведомление/Запрос/Установка. Значения: “rec”, “auto”, “live”
phone_line1 phone_line2 …	да	да	Уведомление/Запрос/Установка: состояние телефонной линии. Значения: “ring”, “talk”, “idle”
monitor1 monitor2 monitor3 …	да	да	Уведомление/Запрос/Установка: подключить группу/шину к линии вывода монитора/наушников. Значения: “pg1”, “pg2”, “rec”, “aux”, “ext”
settings commutation	???	да	Установка: открыть/закрыть соответствующее окно управления консолью (настройками/коммутатором). Значения: “open”, “close”
intro_button outro_button link_button forward_button backward_button cue_button play_button	да	да	Уведомление/Запрос/Установка: Состояние кнопок, расположенных на панели консоли микширования: PREFADE/CUE

 

Example:

<-- {"msg":"par","id":"phone_line1","val":"ring"}        // mixer: входящий звонок на линии 1

--> {"msg":"setpar","id":"phone_line1","val":"talk"}     // app command: ответ на звонок

<-- {"msg":"par","id":"phone_line1","val":"talk"}         // mixer:линия 1 разговаривает

--> {"msg":"setpar","id":"phone_line1","val":"idle"}     // app command: окончание звонка

<-- {"msg":"par","id":"phone_line1","val":"talk"}         // mixer: линия 1 свободна

Вещательные микшерные консоли компании Тракт¶

В этой главе описываются обобщённые параметры для вещательного микшерного пульта, разработанного компанией ТРАКТ, который также использует протокол, основанный на формате JSON.

 

Вещательная микшерная консоль ТР-7¶

Поддерживаемые параметры должны быть перечислены в сообщении "parlist" пульта в ответ на сообщение "getparlist" приложения. Параметры суммируются в таблице ниже с указанием того, могут ли они быть использованы в сообщениях "getpar" и "setpar" команд из приложения на пульт.

Примечание. Большинство из поддерживаемых параметров могут появиться в "par"-сообщении от пульта к приложению как сообщение о смене статуса или как результат "getpar"-запроса. Исключением являются параметры из группы “.State”, которые являются только уведомлениями.

Название параметра	Использование в "getpar"	Использование в "setpar"	Описание
F1.Color F2.Color F3.Color F4.Color F5.Color	да	да	Уведомление/Запрос/Установка для цвета устанавливаемой пользовательской кнопки. Значение целое (представлено в строке JSON) объединенное из значений R, G и B в диапазоне 0:255 каждый: ( R )|( G<<8 )|( B<<16 )
F1.Text F2.Text F3.Text F4.Text F5.Text	да	да	Уведомление/Запрос/Установка для текста устанавливаемой пользовательской кнопки. Значение - название кнопки в строке JSON. При установке пустого значения кнопка становится невидимой.
F1.State F2.State F3.State F4.State F5.State	нет	нет	Только уведомление. Значения: “on” и “off”. Последовательность сообщений включения/выключения, сгенерированная пультом, когда пользователь нажимает кнопку на сенсорном экране пульта.
RMT1.Text RMT2.Text RMT3.Text RMT4.Text	да	да	Уведомление/Запрос/Установка для текста на экране над ручками энкодеров в режиме ДУ. Значение - название кнопки в строке JSON.
RMT1.State RMT2.State RMT3.State RMT4.State	нет	нет	Только уведомление. Значения: “on” и “off”. Клики ручек энкодеров в режиме ДУ.
RMT1.Step RMT2.Step RMT3.Step RMT4.Step	нет	нет	Только уведомление. Значения: “-1” и “+1”. Повороты ручек энкодеров в режиме ДУ. Одно сообщение на шаг (щелчок) поворота ручки энкодера.

 

 

Формальная грамматика сообщений (в EBNF)¶

Правила грамматического разбора TCP потока и JSON сообщений протокола.

Примечания:
   1. Последовательности символов "чистых пробелов" (ws) могут быть вставлены везде, кроме как внутри лексем 'string' и 'number'.
   2. Числа представляются в 8-байтовом IEEEE формате c плавающей точкой (double). Допустимы только истинные числа, не допустимы значения NaN и INF.
   3. Если поток символов 'JSON-text' содержит суррогатные символы, они должны быть корректно закодированы (не допускается использование "половинок" суррогатных пар по отдельности).
   4. Лексемы 'literal' должны быть записаны строчными буквами (lowercase). Допускаются только перечисленные в грамматике значения.