HTTP-интерфейс trivum

25 июля 2023

HTTP-интерфейс trivum принимает запросы, которые можно легко проверить с помощью веб-браузера, и возвращает ответы в формате XML.

1. команды

1.1. ZoneCommand

Позволяет делать основные вещи, такие как переключение зоны, или изменение громкости.

 /xml/zone/runCommand.xml?zone=@zoneId&command=commandNumber

ZoneId

Идентификатор зоны. Список возможных идентификаторов см. в веб-конфигурации в разделе
Automation/trivum API или см. ниже пример getAll.xml.

Некоторые приводы могут обращаться к первой зоне не по @0, а по @1 из-за внутренних неиспользуемых файлов конфигурации. Чтобы исправить это, вы можете сбросить всю конфигурацию, выполнив следующие действия:
Система/Резервное копирование/Восстановление/Сброс всех данных конфигурации

Вместо @0 можно указать имя зоны. Если он содержит специальные символы, перепишите их, используя %:

/xml/zone/runCommand.xml?zone=living%20room&command=…

commandNumber

Это числовая команда с этими возможными значениями:

ZONECMD_POWER_OFF             001
ZONECMD_MUTE                  002   toggle mute
ZONECMD_MUTE_ON               680   since v9.29
ZONECMD_MUTE_OFF              681   since v9.29
ZONECMD_VOLUME_INC            003
ZONECMD_VOLUME_DEC            004
ZONECMD_VOLUME_INC2           009
ZONECMD_VOLUME_DEC2           010
ZONECMD_VOLUME_INC5           011
ZONECMD_VOLUME_DEC5           012
ZONECMD_ALLOFF                015
ZONECMD_SNOOZE                017
ZONECMD_LOCAL_SOURCE          019   if present (LineIn)
ZONECMD_USE_PREV_SOURCE       029   see Zones / zone / KNX/HTTP sources
ZONECMD_JOIN                  030
ZONECMD_UNJOIN                031
ZONECMD_USE_NEXT_SOURCE       041   see Zones / zone / KNX/HTTP sources
ZONECMD_USE_NEXT_ZONE         042   see Zones / zone / KNX/HTTP sources
ZONECMD_DEFAULT_STREAMING     050   if present
ZONECMD_DEFAULT_TUNER         051   if present
ZONECMD_VOLUME_DEC_1          080
ZONECMD_VOLUME_DEC_10         089
ZONECMD_VOLUME_INC_1          090
ZONECMD_VOLUME_INC_10         099
MULTIKEY_BASIC_FORWARD        400   skip to next  track, preset
MULTIKEY_BASIC_BACKWARD       401   skip to prev. track, preset
MULTIKEY_BASIC_FASTFORWARD    402
MULTIKEY_BASIC_FASTBACKWARD   403
MULTIKEY_BASIC_PLAYPAUSE      406
MULTIKEY_PLAY                 431
MULTIKEY_PAUSE                432
MULTIKEY_STOP                 433
MULTIKEY_STATION_DOWN         490
MULTIKEY_STATION_UP           491
MULTIKEY_NEXT_ALBUM           493
MULTIKEY_PREVIOUS_ALBUM       494
MULTIKEY_NEXT_PLAYLIST        495
MULTIKEY_PREVIOUS_PLAYLIST    496
ZONECMD_START_PAGING_1        500
ZONECMD_START_PAGING_32       531
ZONECMD_STOP_PAGING_1         550
ZONECMD_STOP_PAGING_32        581
ZONECMD_STOP_PAGING_ALL       599
ZONECMD_PRESET_1              600
ZONECMD_PRESET_7              606
ZONECMD_GROUP_START_1         621
ZONECMD_GROUP_START_8         628
ZONECMD_GROUP_STOP            630
ZONECMD_GROUP_STOP_1          631
ZONECMD_GROUP_STOP_8          638
ZONECMD_GROUP_STOP_ALL        639
ZONECMD_STREAMING_NOPLAY      641
ZONECMD_VOLUME_00             900
ZONECMD_VOLUME_99             999
ZONECMD_ROOM_VOLUME_00       1000
ZONECMD_ROOM_VOLUME_99       1099

Примеры

позвонить function

позвонить	function
`/xml/zone/getAll.xml`	Список всех возможных идентификаторов зон.
`/xml/zone/get.xml?zone=@0`	Получить статус отдельной зоны. Необязательные параметры: &addSourceBasicData &addSourceStatusData
`/xml/zone/getSelection.xml?grouped`	Список зон с полной информацией о группах.
`/xml/zone/runCommand.xml?zone=@0&command=50`	Переключите первую зону на потоковую передачу по умолчанию.
`/xml/zone/runCommand.xml?zone=@0&command=1`	Выключите первую зону.
`/xml/zone/runCommand.xml?zone=@0&command=15`	Выключить все зоны.
`/xml/zone/runCommand.xml?zone=@0&command=680`	Отключить звук вкл
`/xml/zone/runCommand.xml?zone=@0&command=681`	Отключение звука

/xml/zone/getAll.xml

Список всех возможных идентификаторов зон.

/xml/zone/get.xml?zone=@0

Получить статус отдельной зоны. Необязательные параметры: &addSourceBasicData &addSourceStatusData

/xml/zone/getSelection.xml?grouped

Список зон с полной информацией о группах.

/xml/zone/runCommand.xml?zone=@0&command=50

Переключите первую зону на потоковую передачу по умолчанию.

/xml/zone/runCommand.xml?zone=@0&command=1

Выключите первую зону.

/xml/zone/runCommand.xml?zone=@0&command=15

Выключить все зоны.

/xml/zone/runCommand.xml?zone=@0&command=680

Отключить звук вкл

/xml/zone/runCommand.xml?zone=@0&command=681

Отключение звука

1.2. Установить источник зоны

Выберите источник зоны по сокращенному названию

/xml/zone/set.xml?zone=@0&source=@shortSourceName

shortSourceName

текст действие примечание

текст	действие	примечание
`a` `a1` `a3`	первый аналоговый вход первый аналоговый вход третий аналоговый вход	в зависимости от модели устройства, от 0 до 8 поддерживаются аналоговые входы.
`p` `p5`	первая предустановка FM-тюнера пятая предустановка FM-тюнера	Требуется, чтобы для зоны был настроен FM-тюнер по умолчанию.
f ` `f2	первое trivum избранное второе trivum избранное
`y` `y2`	первый список воспроизведения trivum второй список воспроизведения trivum
`i` `i2`	первая предустановка настройки вторая предустановка настройки
`s`	источник потока зоны по умолчанию	играет недавний выбор
`t`	по умолчанию FM-тюнер зоны	играет последняя частота

a

a1
a3

первый аналоговый вход
первый аналоговый вход
третий аналоговый вход

в зависимости от модели устройства, от 0 до 8 поддерживаются аналоговые входы.

p

p5

первая предустановка FM-тюнера
пятая предустановка FM-тюнера

Требуется, чтобы для зоны был настроен FM-тюнер по умолчанию.

f `

`f2

первое trivum избранное
второе trivum избранное

y

y2

первый список воспроизведения trivum
второй список воспроизведения trivum

i

i2

первая предустановка настройки
вторая предустановка настройки

s

источник потока зоны по умолчанию

играет недавний выбор

t

по умолчанию FM-тюнер зоны

играет последняя частота

Примеры

вызов API

примечание

/xml/zone/set.xml?zone=@0&source=@a1

переключиться на первый аналоговый вход

/xml/zone/set.xml?zone=@0&source=@t

переключиться на FM-тюнер зоны по умолчанию и воспроизвести последнюю частоту

/xml/zone/set.xml?zone=@0&source=@p3

переключиться на FM-тюнер зоны по умолчанию и настроить предустановку станции воспроизведения 3

/xml/zone/set.xml?zone=@0&source=@f2

переключиться на потоковую передачу зоны по умолчанию и играть trivum избранное 2

/xml/zone/set.xml?zone=@0&source=@i5

переключиться на потоковую передачу зоны по умолчанию и воспроизвести предустановку веб-радио TuneIn 5

/xml/zone/set.xml?zone=@1@source=@n

Только для C4: используйте источник с гнездом карты n. (n >= 0)

/xml/zone/runCommand.xml?zone=@0&command=15

Выключить все зоны.

1.3. Установить атрибут зоны

Измените основные значения в зоне, например, громкость, отключение звука, баланс или бас.

вызов API

примечание

/xml/zone/set.xml?zone=@0&volume=10

установить громкость (0 … 100)

/xml/zone/set.xml?zone=@0&action=1

то же, что и /xml/zone/runCommand.xml для запуска числовой команды, в данном случае ZONECMD_POWER_OFF (1)

/xml/zone/set.xml?zone=@0&balance=0

установить баланс, от -15 (полностью слева) до 15 (полностью справа)

/xml/zone/set.xml?zone=@0&bass=-5

установить уменьшение или усиление басов, от -15 до 15

/xml/zone/set.xml?zone=@0&treble=5

установить снижение или усиление высоких частот, от -15 до 15

1.4. trivum Избранное

Чтобы создать фавориты trivum:

воспроизвести какой-либо музыкальный контент, например альбом NAS
затем выберите «…» в правом верхнем углу
затем выберите "Добавить в trivum избранное".

Получить список фаворитов trivum:

/api/v1/тривум/фаворит.xml

Играйте в любимую мелочь:

/xml/zone/set.xml?source=@f1&zone=@0

Вы также можете добавить опции:

вариант

примечание

&sequence=random-sequential

выбрать случайный стартовый трек

&sequence=random-random

играть в постоянном случайном порядке

1.5. Плейлисты trivum

Получить список из trivum плейлистов:

/api/v1/тривум/плейлист.xml

Воспроизвести список воспроизведения trivum:

/xml/zone/set.xml?source=@y1&zone=@0

Вы также можете добавить опции:

вариант

примечание

&sequence=random-sequential

запустить наугад трек

&sequence=random-random

воспроизводить только случайные треки

1.6. Избранное в TuneIn

Их также можно создать с помощью … в правом верхнем углу во время воспроизведения станции TuneIn.

Получите список избранных TuneIn:

/api/v1/tunein/favorite.xml

Воспроизведение любимого TuneIn:

/xml/zone/set.xml?source=@i1&zone=@0

1.7. FM-предустановки

Список предустановок FM:

/xml/система/getTunerStationList.xml

На C4 отображается общесистемный список предустановок FM, но нет локальных предустановок, хранящихся на карте FM-тюнера.

1.8. Состояние и контроль состояния NAS

вызов API

примечание

/xml/system/getMusicCenterStatus.xml

получить статус библиотеки NAS

/xml/system/scanMusicCenterShares.xml

повторно запустить полное сканирование NAS

1.9. Управление группой

Группы могут быть созданы, изменены или удалены одним вызовом:

/xml/zone/createGroup.xml?zone=zVisu&oldgroup=zMaster&members=++----------

Параметры:

имя

примечание

zVisu

индекс текущей зоны визуализации client

zМастер

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

+/-

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

Пример: вторая зона присоединяется к воспроизведению первой зоны

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

/xml/zone/createGroup.xml?zone=1&oldgroup=0&members=++--

Результат: вторая зона начинает играть тот же поток, что и первая зона.

Пример: первая зона присоединяется к воспроизведению второй зоны

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

/xml/zone/createGroup.xml?zone=0&oldgroup=1&members=++--

Результат: первая зона запускает тот же FM-тюнер, что и вторая зона.

Это означает, что если обе зоны воспроизводят разные источники, то
"oldgroup" решает, какую музыку воспроизводить после присоединения к группе.

Пример: вторая зона должна покинуть группу

/xml/zone/createGroup.xml?zone=0&oldgroup=0&members=+---

Релевантно здесь изменение от + до - в списке участников.

Изменение уровня громкости в группе

Внутри группы зоны обычно не используют изолированные уровни громкости,
но изменение громкости влияет на всех членов группы.
Эта взаимозависимость обрабатывается вызовом:

/xml/зона/setVolume.xml

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

вызов API

примечание

/xml/zone/setVolume.xml?id=@0&volume=0

Уменьшите громкость группы для всей группы. id — это любой идентификатор зоны из группы. Громкость всех членов зоны будет уменьшена на несколько шагов.

/xml/zone/setVolume.xml?id=@0&volume=99

Увеличьте громкость группы для всей группы. Громкость всех членов зоны будет увеличена на несколько шагов.

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=99

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

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=0

Ступенчатое уменьшение объема одной зоны, не затрагивая других членов группы.

/xml/zone/setVolume.xml?id=@0&stop

Немедленно остановить изменение громкости.

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=50&absolute

Установите абсолютный объем для одной зоны, изолированной от других членов группы. (Используйте с осторожностью.)

Чтобы получить новую информацию об уровне громкости в группе, выполните вызов getChanges и просмотрите список состояния громкости.

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&now

Пример вывода, если сгруппирован, под зоной/статусом:

<zone>
 ...
 <status>
 <volume>17</volume>  - volume of zone making the getChanges call
 ...
 <group>
  <zone>0</zone>
  <volume>17</volume> - volume for zone id 0
 </group>
 <group>
  <zone>1</zone>
  <volume>26</volume> - volume for zone id 1
 </group>
 <group>
   ...
 </group>
 <groupMembers>2</groupMembers>
 </status>
</zone>

Полное объяснение getChanges см. на Получить статус зоны.

1.10. Paging

Страницы должны быть настроены в веб-конфигурации. Затем можно использовать следующие вызовы:

Начало пейджинга

/xml/пейджинг/start.xml

параметры

имя описание

имя	описание
`id`	идентификатор пейджинга, 0 - 31
`volume`	необязательно, 5 - 100. , если не указан, используется настроенный уровень громкости подкачки.
`autostoptime`	опционально, 5–100 секунд. , если не указано, используются настроенные параметры остановки.

id

идентификатор пейджинга, 0 - 31

volume

необязательно, 5 - 100. , если не указан, используется настроенный уровень громкости подкачки.

autostoptime

опционально, 5–100 секунд. , если не указано, используются настроенные параметры остановки.

Пример

/xml/paging/start.xml?id=0&volume=10&autostoptime=10

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

/xml/пейджинг/stop.xml?id=0

2. Интерактивный выбор музыки

Начинается с:

/xml/system/getWebTouchMenu.xml?that=music&zone=@0&visuid=90

Это создает такие записи, как:

<row>
  <type>action</type>
  <mode>menu</mode>
  <action>/xml/system/getWebTouchMenu.xml?which=trivumFavorites&amp;keypad=4</action>
  <icon>/imgs/visuIconServiceFavorites_128px.png</icon>
  <text>trivum_20favorites</text>
</row>

то за запись:

декодируйте и отобразите текстовое поле в вашей визуализации.
_20 означает символ с кодом Ascii 0x20 (пробел).
если коснуться, вызовите URL-адрес действия и отобразите следующий уровень меню.

Не полагайтесь на постоянную доступность определенных уровней меню.
Со временем могут меняться, в частности, меню, предоставляемые музыкальными сервисами.

3. Получить статус зоны

3.1. Синхронный

Опросите статус зоны одним коротким вызовом API:

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&now

параметры

имя

функция

visuid

число от 1 до 99 для идентификации экземпляра внешней визуализации.
в этом документе API для тестовых запросов используется visuid=90.

apiLevel

всегда должно быть 2. это создаст xml-объекты «кнопка» в разделе «клавиатура/базовая».

now

указывает серверу немедленно вернуть статус новой зоны и закрыть соединение.
без &now вызов будет заблокирован до истечения времени ожидания или до изменения информации о статусе зоны.

reload=1

если две визуализации обращаются к одному и тому же серверу с одинаковым визуальным идентификатором , может появиться ошибка "используется дважды". в этом случае самая последняя визуализация должна добавить &reload=1 при первом вызове, чтобы четко указать , что это самая последняя визуализация.

О блоках управления (визуализации)

Если вы отправляете запросы с visuid=90, на сервере создается объект Control Unit с идентификатором 90.

Вы можете получить список текущих блоков управления в веб-конфигурации в разделе Control Units.

После первого доступа устройство отображается как "Не настроено". Как только вы измените его конфигурацию, например, установив опцию "Off коротким нажатием на power", он называется Configured, и последующие очистки списка блоков управления не удалят его.

Если запросов на этот блок нет, через некоторое время он будет числиться под " неактивными в данный момент блоками управления ".

3.2. Асинхронный

Это означает, что вызов HTTP не вернется немедленно, но будет заблокирован до тех пор, пока что-то не изменится.

Пример:

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2

Обратите внимание, что & now отсутствует. Произойдет следующее:

при первом вызове API:

Блок управления с ID 90 создан и связан с первой зоной.
Вызов API немедленно возвращается с полными данными о состоянии зоны.

при всех дальнейших вызовах API:

Существующий блок управления 90 используется повторно. Вызов API может быть заблокирован до тех пор, пока:

достигнут тайм-аут (примерно 10 секунд). в этом случае вы получите ответ вида:
<rows><system><timeout>1</timeout>
или пока что-то не изменилось, например, громкость в зоне.

если (много) данных о статусе изменилось на сервере между двумя вызовами getChanges, вызов может вообще не блокироваться, а немедленно возвращать новый статус.

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

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

3.3. Приложение: схематический пример клиентского приложения Visu

3.3.1. Однопоточное приложение

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

Основная тема

начало: отправить /xml/zone/getChanges.xml?visuid=90&now
начало цикла: обновить графический интерфейс.
- обрабатывать события ввода от пользователя.
- отправлять синхронные команды, такие как:
  /xml/zone/runCommand.xml?…
  получать ответ, проверять rc И обрабатывать данные состояния xml
  (то же, что и с ответами getChanges)
- проверить, существуют ли данные ответа для текущего вызова getChanges
  (в коде C: вызов select() на сокете)
  ЕСЛИ существуют данные с сервера trivum:
  - Найдите <userdata name="rc">0</userdata>.
    Если НЕ присутствует
    _ обработайте ошибку и подождите несколько секунд.
    В противном случае, если НЕ время ожидания
    _ обработка XML-ответа (данные о состоянии)
    Endif
    асинхронный вызов (просто отправить)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    Endif
- если данные с сервера не приходят в течение 1 минуты
  - асинхронный вызов (просто отправить)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    endif
- повторный цикл

3.3.2. Пример приложения с двумя потоками

Может использоваться, если вы предпочитаете выполнять блокировку получения сокетов в отдельном потоке ввода-вывода.

Основная тема

обновить графический интерфейс.
обрабатывать события ввода от пользователя.
отправлять синхронные команды, такие как:
/xml/zone/runCommand.xml?…
получать ответ, проверять rc И обрабатывать данные состояния xml
(то же, что и с ответами getChanges)
получать данные о состоянии и ошибки из потока состояния.
перезапустите этот цикл.

Статус темы

ЕСЛИ на первом цикле:
- отправить /xml/zone/getChanges.xml?visuid=90&now
  ДРУГОЕ
- отправить /xml/zone/getChanges.xml?visuid=90&onlyChanges
получить ответ (это блокируется до 10 секунд)
Найдите <userdata name="rc">0</userdata>.
Если этого НЕТ, то это ошибка.
Не просто перезапустите цикл при ошибках
, но хотя бы подождите несколько секунд и сообщите об этом основному потоку.
Найдите <rows><system><timeout>1</timeout>.
ЕСЛИ присутствует
- немедленно перезапустите цикл.
  ДРУГОЕ
- обработайте данные о состоянии ответа
  и скопируйте новые данные о состоянии в основной поток.
перезапустите этот цикл.

документация API trivum

HTTP-интерфейс trivum

1. команды

1.1. ZoneCommand

ZoneId

commandNumber

1.2. Установить источник зоны

shortSourceName

1.3. Установить атрибут зоны

1.4. trivum Избранное

1.5. Плейлисты trivum

1.6. Избранное в TuneIn

1.7. FM-предустановки

1.8. Состояние и контроль состояния NAS

1.9. Управление группой

Изменение уровня громкости в группе

1.10. Paging

2. Интерактивный выбор музыки

3. Получить статус зоны

3.1. Синхронный

3.2. Асинхронный

3.3. Приложение: схематический пример клиентского приложения Visu

3.3.1. Однопоточное приложение

3.3.2. Пример приложения с двумя потоками