trivum HTTP接口

2023 年 7 月 25 日

trivum HTTP 接口接受可通过 Web 浏览器轻松测试的请求，并以 XML 格式返回回复。

1. 命令

1.1. ZoneCommand

允许执行基本操作，例如关闭区域或更改音量。

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

了zoneid

区域的ID。有关可能 ID 的列表，请查看
Automation /trivum API 下的 Web 配置或查看下面的 getAll.xml 示例。

由于内部未使用的配置文件，某些执行器可能不会通过 @0 而是通过 @1 来寻址第一个区域。要解决此问题，您可以通过以下方式重置整个配置：
System/Backup/Restore/Reset all configuration data

可以指定区域名称而不是“@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

例子

致电函数

致电	函数
`/xml/zone/getAll.xml`	列出所有可能的区域 ID。
`/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`	静音 on
`/xml/zone/runCommand.xml?zone=@0&command=681`	静音

/xml/zone/getAll.xml

列出所有可能的区域 ID。

/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

静音 on

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

静音

1.2. 设置区域源

按短名称选择区域来源

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

shortSourceName

文本行动 remark

文本	行动	remark
`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 调谐器

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/trivum/favorite.xml

发挥一个小小的最爱：

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

您还可以添加选项：

选项

备注 &sequence=random-sequential

选择随机开始曲目 &sequence=随机-随机

以永久随机顺序播放

1.5. 播放列表

获取trivum播放列表的列表：

/api/v1/trivum/playlist.xml

播放trivum播放列表：

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

您还可以添加选项：

选项

备注 &sequence=random-sequential

从随机曲目开始 &sequence=随机-随机

仅播放随机曲目

1.6. 收听收藏夹

这些也可以在 TuneIn 电台播放时通过右上角的“…”创建。

获取TuneIn收藏列表：

/api/v1/tunein/favorite.xml

播放TuneIn最爱：

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

1.7. FM预设

列出FM预设：

/xml/system/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=++----------

参数：

姓名

备注

维苏

可视化客户端当前区域索引

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/zone/setVolume.xml

默认情况下，此调用不会简单地“设置”绝对音量级别，而是“稍微”进入给定目标音量的方向。这最好与可视化中的 + 或 - 按钮一起使用。

API调用

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

将整个群组的群组音量逐步降低。 id 是群组中的任何区域 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. 分页

必须在 Web 配置中配置分页。然后可以使用以下调用：

开始分页

/xml/paging/start.xml

参数

名称描述

名称	描述
`id`	寻呼 ID，0 - 31
`卷`	可选，5 - 100. 如果未提供，则使用配置的寻呼音量级别。
`autostoptime`	可选，5 - 100 秒。如果未提供，则使用配置的停止设置。

id

寻呼 ID，0 - 31

卷

可选，5 - 100. 如果未提供，则使用配置的寻呼音量级别。

autostoptime

可选，5 - 100 秒。如果未提供，则使用配置的停止设置。

实施例

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

寻呼在定义的时间后自动停止，但您可以通过调用以下命令提前停止它：

/xml/paging/stop.xml?id=0

2. 互动音乐选择

以。。开始：

/xml/system/getWebTouchMenu.xml?which=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。这将在“keypad/basic”下生成“button” xml 对象。

now

告诉服务器立即返回新区域状态，并关闭连接。
如果没有“&now”，调用将会阻塞，直到超时，或者直到区域状态信息发生更改。

reload=1

如果两个可视化使用相同的 visuid 访问同一服务器，则可能会出现错误 "used两次"。在这种情况下，最近的最近的可视化应该在第一次调用时添加 &reload=1，以清楚地告诉这是最近的可视化。

关于控制单元（可视化）

如果您使用“visuid=90”发送请求，则会在服务器中创建 ID 为 90 的_Control Unit_对象。

您可以在 Control Units 下的 Web 配置中获取当前控制单元的列表。

首次访问后，该设备被列为 "Notconfigured"。一旦您更改其配置，例如通过短按 power" 设置选项 "Off，它就会被称为_Configured_，并且稍后清理控制单元列表不会删除此选项。

如果没有对该单元的请求，一段时间后它将列在 "currently inactive control units" 下。

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，例如在单独的 I/O 线程中。因为请求仅在更改时返回，所以这不会导致服务器出现负载问题。

当您没有收到超时时，即调用立即或几秒钟后返回（一旦发生更改），然后处理状态数据，然后重新运行 getChanges 请求。

3.3. 附录：Visu 客户端应用程序的示意图示例

3.3.1. 单线程应用程序

这要求您可以用您的编程语言测试套接字的回复数据是否存在（通过 select() 调用）。

主线程

开始：发送 /xml/zone/getChanges.xml?visuid=90&now
循环开始：更新GUI。
- 处理来自用户的输入事件。
- 发送同步命令，例如：
  /xml/zone/runCommand.xml?…
  接收回复，检查 rc 并处理 xml 状态数据
  （与 getChanges 回复相同）
- 检查正在进行的 getChanges 调用是否存在回复数据
  （C 代码中：套接字上的 select() 调用）
  如果 trivum 服务器存在数据：
  - 查找“<userdata name="rc">0</userdata>”。
    如果不存在
    _ 处理错误并等待几秒钟。
    Else if NOT 超时
    _ 处理 xml 回复（状态数据）
    Endif
    异步调用（仅发送）
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    Endif
- 如果1分钟内没有来自服务器的数据到达
  - 异步调用（仅发送）
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    endif
- 重新运行循环

3.3.2. 两线程应用示例

如果您更喜欢在单独的 I/O 线程中的套接字上运行阻塞接收，则可以使用。

主线程

更新图形用户界面。
处理来自用户的输入事件。
发送同步命令，例如：
/xml/zone/runCommand.xml?…
接收回复，检查 rc 并处理 xml 状态数据
（与 getChanges 回复相同）
从状态线程接收状态数据和错误。
重新运行这个循环。

状态线程

IF 在第一个循环上：
- 发送 /xml/zone/getChanges.xml?visuid=90&now
  ELSE
- 发送 /xml/zone/getChanges.xml?visuid=90&onlyChanges
接收回复（最多被阻止 10 秒）
查找“<userdata name="rc">0</userdata>”。
如果不存在，则出现错误。
确保不仅仅是在出现错误时重新运行循环，
而是至少等待几秒钟，然后通知主线程。
查找“<rows><system><timeout>1</timeout>”。
如果存在
- 立即重新运行循环。
  其他
- 处理回复状态数据
  并将新的状态数据复制到主线程。
重新运行这个循环。

trivum API文档

trivum HTTP接口

1. 命令

1.1. ZoneCommand

了zoneid

commandNumber

1.2. 设置区域源

shortSourceName

1.3. 设置区域属性

1.4. trivum收藏夹

1.5. 播放列表

1.6. 收听收藏夹

1.7. FM预设

1.8. NAS状态和控制

1.9. 集团管理

更改组内的音量级别

1.10. 分页

2. 互动音乐选择

3. 获取区域状态

3.1. 同步

3.2. 异步

3.3. 附录：Visu 客户端应用程序的示意图示例

3.3.1. 单线程应用程序

3.3.2. 两线程应用示例