OSC

Экран OSC — это ручная работа с Open Sound Control (OSC 1.0) по UDP. В нём три части:

• Отправитель: одно сообщение с типизированными аргументами; уходит по нажатию Enter.
• Монитор: слушает порт и декодирует каждый пришедший пакет.
• Генератор сигнала: много раз в секунду отправляет значение, которое меняется по заданной форме волны, и рисует его.

Signal Lab кодирует и декодирует OSC сам. То, что он отправляет, показывает Инспектор — байт в байт.

Отправка сообщения

1. Откройте OSC.
2. В поле Цель host:port введите IP-адрес или имя хоста устройства и его порт, например 127.0.0.1:9000 или stage-mixer.local:9000.
3. В поле OSC-адрес введите адрес, который слушает устройство, например /mixer/fader/1.
4. В блоке Аргументы задайте тип и значение каждого аргумента. Кнопка + аргумент добавляет ещё один; ✕ удаляет.
5. Нажмите Отправить или Enter в любом поле отправителя.

Строка под кнопками сообщает, что ушло: адрес, его размер в байтах и цель. Повторная отправка того же сообщения увеличивает счётчик (×2, ×3…), так что видно, что повтор сработал. Если отправка не удалась, вместо этого показана ошибка — и в консоли тоже.

Цель, адрес и аргументы сохраняются при переключении между экранами и при перезапуске приложения.

Поля

Поле	Что это	По умолчанию
Цель host:port	IP:port или host:port получателя. IPv6-адрес берётся в квадратные скобки: [::1]:9000. Имя хоста разрешается при каждой отправке; если у него есть адрес IPv4, используется он (так localhost достаёт до получателя, который слушает на 127.0.0.1), иначе — адрес IPv6. Цель без порта отклоняется.	127.0.0.1:9000
OSC-адрес	OSC-адрес: начинается с /, части разделены /. Адрес без начального / отклоняется до отправки.	/hello/avatar/1
Аргументы	Типизированные значения после адреса, по порядку. Аргументов может не быть вовсе.	один float, 1.0

Типы аргументов

Тип каждого аргумента входит в сообщение (это его тег типа), поэтому устройство, которое ждёт float, может проигнорировать int с тем же значением.

Тип в списке	Тег OSC	Значение	Как вводится
int	i	32-битное целое со знаком	целое число
float	f	32-битное число с плавающей точкой	число, 0.75
str	s	текст	любой текст, отправляется в UTF-8
bool	T / F	истина или ложь	true или false из списка; байтов не несёт, только тег
long	h	64-битное целое со знаком	целое число
double	d	64-битное число с плавающей точкой	число
nil	N	ничего	без значения
blob	b	байты	здесь не вводится: появляется только для чтения, в шестнадцатеричном виде, когда вы открываете сигнал, в котором он есть

Числовое поле, в котором нет числа, отправляет 0.

TIP

OSC true — это тег T, а не текст "true". Устройство, которое ждёт bool, молча игнорирует строку.

Бандлы

Отправитель посылает отдельные сообщения, а не бандлы. Когда приходит бандл (#bundle), монитор, ожидания эксперимента и эмуляторы его распаковывают: каждое вложенное сообщение обрабатывается само по себе, а его временная метка игнорируется.

Наблюдение за портом

Чтобы увидеть, что отправляет устройство или шоу-контроллер:

1. В поле Адрес прослушивания введите адрес и порт, на которых слушать. 0.0.0.0:9000 (по умолчанию) слушает на всех сетевых картах; 127.0.0.1:9000 — только на этом компьютере.
2. Нажмите Слушать. Пока монитор работает, поле заблокировано.
3. Укажите в устройстве-отправителе IP-адрес этого компьютера и этот порт.

Каждый пакет становится строкой, новые сверху:

Столбец	Что в нём
Время	Когда пакет пришёл, с точностью до миллисекунды
Откуда	IP:port отправителя
Адрес	OSC-адрес или (ошибка декодирования), если пакет — не корректный OSC
Аргументы	Значения аргументов; blob показан как blob[n], nil — как nil. Для пакета, который не удалось декодировать, — причина.

Бандл даёт по строке на каждое сообщение. В списке хранятся последние 300 строк; кнопка Очистить очищает его. Чтобы закрыть порт, нажмите Стоп. Монитор — ещё и задача в полосе задач, поэтому остановить его можно и оттуда.

Монитор читает пакеты размером до 64 КиБ. Он декодирует теги i f s S b h d T F N I (S читается как текст, I — как nil); пакет с любым другим тегом или оборванный показывается как ошибка декодирования, а не отбрасывается.

Превращение сообщения в ожидание

В каждой строке есть кнопка ⇠, Ждать это. Она добавляет в открытый эксперимент узел Ждать OSC, который слушает на адресе прослушивания монитора (Адрес прослушивания) этот OSC-адрес, с правилом «равно» для каждого текстового, целого и логического аргумента (для float, blob и nil правил нет) — не больше 16 правил. Тайм-аут — 2000 мс. Редактор открывается с выбранным новым узлом.

WARNING

Остановите монитор перед запуском этого эксперимента. Запуск сам открывает тот же порт, а два слушателя не могут делить его.

Подача сигнала заданной формы

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

1. Задайте Цель host:port и Адрес. Оба поля проверяются при нажатии Запустить генератор — так же, как их проверяет отправитель.
2. Выберите значения полей Форма волны, Частота (Гц) и Темп (пак/с).
3. Задайте границы диапазона значения: Мин и Макс.
4. Нажмите Запустить генератор. Генератор работает, пока вы не нажмёте Остановить генератор или не остановите его задачу в полосе задач.

Поле	Что это	По умолчанию
Цель host:port	IP:port или host:port получателя; имя разрешается один раз, при запуске генератора	127.0.0.1:9000
Адрес	Адрес, на который уходит каждое сообщение; начинается с /	/hello/lfo
Форма волны	Форма значения во времени (ниже)	синус
Частота (Гц)	Циклов формы волны в секунду	1
Темп (пак/с)	Сообщений в секунду, от 0,1 до 5000; значение вне диапазона приводится к его границе	60
Мин, Макс	Наименьшее и наибольшее значение. Если максимум меньше минимума, значение не меняется.	0, 1
отправлять как int	Округлять до ближайшего целого и отправлять int вместо float	выключено

Форма волны	Что делает значение в каждом цикле
синус	Плавно колеблется между минимумом и максимумом, начиная с середины и поднимаясь
треугольник	Растёт от минимума до максимума, затем спадает обратно до минимума; начинает с минимума
пила	Падающая пила: начинает с максимума, спадает до минимума, затем скачком возвращается к максимуму
рампа	Нарастающая пила: начинает с минимума, растёт до максимума, затем скачком возвращается к минимуму
меандр	Максимум в первой половине цикла, минимум во второй
шум	С каждым сообщением — новое случайное значение между минимумом и максимумом; частота не используется
константа	Каждый раз максимум; частота не используется

Осциллограф

Рядом с полями осциллограф рисует значение по мере отправки: последние 300 точек, масштабированные по размеру. Под ним — форма волны, частота, темп и последнее отправленное значение. Осциллограф обновляется около 30 раз в секунду, как бы быстро ни отправлял генератор, поэтому на высоком темпе он показывает выборку сообщений, а не каждое.

Если отправка не удалась, генератор останавливается, а консоль объясняет причину.

В Инспекторе

Когда захват включён (Включить захват на вкладке Инспектор), трафик OSC появляется с протоколом osc:

Источник	Что это	Примечания
osc-send	Каждое сообщение, которое отправляют отправитель, сигнал библиотеки, узел OSC-сообщение или signallab send osc	Узел, который ждёт ответ, показан как experiment
osc-monitor	Каждый пакет, принятый монитором	Бандл описан первым сообщением и +n more in bundle; у повреждённого пакета вердикт decode error: …
osc-gen	Сообщения генератора	Захватывается не чаще одного за 100 мс, с вердиктом sampled; следующее после пропущенных добавляет, сколько их не показано: sampled · +5 not shown

Каждый кадр хранит байты, из которых он собран. См. Инспектор.

Сохранение и повторное использование

• Сохранить как сигнал. Кнопка Сохранить… под основными кнопками сохраняет сообщение — цель, адрес и аргументы — в библиотеке сигналов, в папке на ваш выбор. С этого момента отправитель связан с этим сигналом: Сохранить (или Ctrl+S в отправителе) обновляет его, Сохранить как… делает копию, а плашка рядом с ними открывает его на экране Сигналы. Позже отправьте его с экрана Сигналы или нажатием Ctrl+K на любом экране. См. Сигналы.
• Добавить в эксперимент. Кнопка В эксперимент добавляет в открытый эксперимент узел OSC-сообщение с теми же целью, адресом и аргументами — прямо перед узлом «Финиш» или после выбранного узла — и открывает его. Пока эксперимент выполняется, ничего добавить нельзя; консоль сообщает об этом.

В экспериментах

Узел	Что он делает
OSC-сообщение	Отправляет одно сообщение. Его цель, адрес и текстовые аргументы принимают {{templates}}. С параметром ждать ответ отправляет со своего порта и ждёт там ответа в том же шаге. Подробнее
Ждать OSC	Ждёт сообщение, адрес которого подходит под шаблон, а аргументы проходят правила. Подробнее
Эмулятор	OSC-устройство, которое отвечает по правилам на протяжении всего запуска. См. Эмуляторы.

Узел, отправляющий OSC-сообщение, принимает IP:port или host:port, как и экран, а его адрес должен начинаться с /. Имя хоста разрешается при каждой отправке узла.

Шаблоны адресов

Узел Ждать OSC, ответ узла OSC-сообщение и правила OSC-эмулятора сопоставляют адреса с шаблонами OSC 1.0:

Шаблон	Что подходит
*	любая последовательность символов, в том числе пустая
?	ровно один символ
[0-9], [a-c]	один символ из набора или диапазона
[!0-9]	один символ не из набора
{ping,pong}	одно из слов

Подстановочные символы действуют в пределах одной части между слешами: /cue/* подходит к /cue/7, но не к /cue/7/go, а шаблон подходит только к адресу с тем же числом частей. Регистр учитывается. Шаблон начинается с /, не содержит пустых частей (//), пробелов, # и символов вне ASCII и не длиннее 512 символов.

Правила аргументов сравнивают аргумент с номером 0–63 со значением (равно, меньше, содержит, соответствует регулярному выражению и так далее); у ожидания их не больше 16. Когда приходит бандл, ожидание принимает его, если подходит любое сообщение внутри. О том, что подошедшее сообщение даёт следующим шагам, см. Данные и шаблоны.

Из командной строки

signallab send osc отправляет одно сообщение так же, как отправитель:

signallab send osc 127.0.0.1:9000 /cue/go f:0.75 s:main

✔ sent /cue/go (24 bytes) → 127.0.0.1:9000

Каждый аргумент записывается как tag:value: i:3, f:0.5, d:1.5, h:64, s:text, b:de ad be ef (байты в шестнадцатеричном виде) или T, F, N сами по себе. Без тега целое число считается i, число с десятичной точкой — f, всё остальное — s; чтобы отправить текст 7, напишите s:7. Цель — IP:port или host:port. Код завершения: 0, если сообщение ушло, 1, если отправка не удалась (в том числе если имя хоста не разрешилось), и 2, если аргумент, адрес или цель недопустимы. signallab fire отправляет сохранённый сигнал. См. Командная строка.

TIP

В Git Bash на Windows аргумент, начинающийся с /, превращается в путь к файлу раньше, чем его увидит signallab. Поставьте перед командой MSYS_NO_PATHCONV=1 или используйте PowerShell либо cmd.

Проблемы

Что вы видите	Обычная причина
… is not a valid address при отправке	У цели нет порта, или она не в форме IP:port и не в форме host:port.
Cannot resolve … при отправке	Имя хоста не разрешается на этом компьютере. Проверьте его или используйте IP-адрес.
OSC addresses start with / (…)	В адресе нет начального /.
Сообщение отправлено, но устройство ничего не делает	Неверный порт или адрес; тип не тот, что ожидается (int вместо float, текст "true" вместо bool). Посмотрите сообщение в Инспекторе или направьте цель на монитор на этом компьютере, чтобы увидеть, что уходит.
… is already in use by another program при нажатии Слушать	Порт занят другой программой — или идущим экспериментом, эмулятором либо вторым монитором.
… is not an address of this computer	IP в поле Адрес прослушивания принадлежит другому компьютеру. Используйте 0.0.0.0 или один из адресов этого компьютера.
Пакеты с других компьютеров не приходят	В Windows их может не пускать брандмауэр: разрешите Signal Lab, когда приложение предложит. Локальный трафик (127.0.0.1) это не затрагивает. См. Устранение неполадок.
Строки (ошибка декодирования)	Отправитель говорит на этом порту не на OSC 1.0 или использует тег типа, который Signal Lab не декодирует.

На сервере экран работает в сети сервера: 127.0.0.1 — это сам сервер, а монитор слушает порты сервера. См. Сервер.

Все сообщения об ошибках перечислены в разделе Сообщения об ошибках.