trivum HTTP Interface


The trivum HTTP interface takes requests which can be tested easily by a web browser, and returns replies in XML format.

1. Commands

1.1. ZoneCommand

Allows to do basic things like switching a zone off, or to change volume.


The ID of a zone. For the list of possible IDs look into the web configuration under
Automation /trivum API or see below the getAll.xml example.

Some Actuators may not address the first zone by @0 but by @1 due to internal, unused configuration file(s). To fix this, you may reset the whole configuration by:
System / Backup/Restore / Reset all configuration data

Instead of @0 the zone name can be given. If it contains special characters rewrite them using % :


This is a numeric command with these possible values:

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_PLAY                 431
MULTIKEY_PAUSE                432
MULTIKEY_STOP                 433
ZONECMD_PRESET_1              600
ZONECMD_PRESET_7              606
ZONECMD_GROUP_STOP            630
ZONECMD_GROUP_STOP_1          631
ZONECMD_GROUP_STOP_8          638
ZONECMD_VOLUME_00             900
ZONECMD_VOLUME_99             999


call function


List all possible zone ID’s.


Get status of a single zone. Optional parameters are: &addSourceBasicData &addSourceStatusData


List zones with full group informations.


Switch the first zone to default streaming.


Switch the first zone off.


Switch all zones off.


Mute on


Mute off

1.2. Set Zone Source

Select a zone source by short name

text action remark


first analog input
first analog input
third analog input

Depending on the device model, 0 to 8 analog inputs are supported.


first FM tuner preset
fifth FM tuner preset

Requires that a default FM tuner is configured for the zone.


first trivum favorite
second trivum favorite


first trivum playlist
second trivum playlist


first tunein preset
second tunein preset


default stream source of zone

playing recent selection


default FM tuner of zone

playing recent frequency


API call



switch to first analogue input


switch to default FM tuner of zone and play recent frequency


switch to default FM tuner of zone and play station preset 3


switch to default streaming of zone and play trivum favorite 2


switch to default streaming of zone and play TuneIn webradio preset 5


C4 only: use a source by card slot n. (n >= 0)


Switch all zones off.

1.3. Set Zone Attribute

Change basic values in a zone, like volume, mute, balance or bass.

API call



set volume (0 …​ 100)


same as /xml/zone/runCommand.xml to run a numeric command, in this case ZONECMD_POWER_OFF (1)


set balance, from -15 (full left) to 15 (full right)


set bass reduction or enhancement, from -15 to 15


set treble reduction or enhancement, from -15 to 15

1.4. trivum Favorites

To create trivum favorites:

  • play some music content, like a NAS album

  • then select …​ at the right top

  • then select "Add to trivum favorites".

Get the list of trivum favorites:


Play a trivum favorite:


You may also add options:




select a random start track


play in permanent random order

1.5. trivum Playlists

Get the list of trivum playlists:


Play a trivum playlist:


You may also add options:




to start at a random track


to play only random tracks

1.6. TuneIn Favorites

These can also be created by …​ at the right top while a TuneIn station is playing.

Get the list of TuneIn favorites:


Play a TuneIn favorite:


1.7. FM presets

List FM presets:


On C4 this shows the system wide list of FM presets, but no local presets stored per FM tuner card.

1.8. NAS status and control

API call



get NAS library status


rerun full NAS scan

1.9. Group management

Groups can be created, changed or removed by one call:






index of the current zone of the visualization client


index of the group master whose music should be used (if both zones are currently playing different sources)


characters telling graphically which zones should take part in a group. for example, with a 4 zone system, type 4 characters or less (is filled up with - automatically).

Example: second zone joins playback of first zone

  • first zone is playing a stream, second zone is playing FM tuner, all other zones are off.

  • second zone should be added to a group with first zone,
    and it should take over music from first zone (the stream).


Result: the second zone starts playing the same stream as first zone.

Example: first zone joins playback of second zone

  • first zone is playing a stream, second zone is playing FM tuner, all other zones are off.

  • first zone should be added to a group with second zone, and it should take over music from second zone (the tuner).


Result: first zone starts playing the same FM tuner as second zone.

This means if both zones are playing different sources then
"oldgroup" decides which music to play after the group join.

Example: second zone should leave the group


Relevant here is the change from + to - in the members list.

Change volume level within a group

Within a group, zones normally do not use isolated volume levels,
but a change in volume affects all group members.
This interdependency is handled by the call:


By default, this call will not simply set an absolute volume level, but it steps a bit into the direction of a given target volume. This is best used with a + or - button in your visualization.

API call



Step the group volume downwards for the whole group. id is any zone ID from the group. The volume of all zone members will be decreased a few steps.


Step the group volume upwards for the whole group. The volume of all zone members will be increased a few steps.


Increase volume of a single zone step wise, not affecting other group members.


Decrease volume of a single zone step wise, not affecting other group members.


Stop volume stepping immediately.


Set absolute volume for a single zone, isolated from other group members. (Use with care.)

To get the new volume level informations within a group make a getChanges call and look into the volume status list.


Example output, if grouped, under zone / status:

 <volume>17</volume>  - volume of zone making the getChanges call
  <volume>17</volume> - volume for zone id 0
  <volume>26</volume> - volume for zone id 1

For a full explanation of getChanges see Get Zone Status.

1.10. Paging

Pagings must be configured in the web configuration. Then the following calls can be used:

Start paging



name description


paging ID, 0 - 31


optional, 5 - 100. if not supplied the configured paging volume level is used.


optional, 5 - 100 seconds. if not supplied the configured stop settings are used.



A paging stops automatically after the defined time, but you may stop it earlier by calling:


2. Interactive Music Selection

Starts with:


This produces records like:


then, per record:

  • decode and display the text field in your visualization.
    _20 means a character with Ascii Code 0x20 (a space).

  • if touched, call the action url and display the next menu level.

Do not rely on the permanent availability of specific menu levels.
Especially the menus provided by music services may change over time.

3. Get Zone Status

3.1. Synchroneous

Poll the status of a zone with one short API call:






a number from 1 to 99 to identify your external visualization instance.
within this API document, visuid=90 is used for test requests.


should always be 2. this will produce button xml objects under keypad / basic.


tells the server to return the new zone status immediately, and to close the connection.
without &now the call would block until a timeout, or until a change in the zone status informations.


if two visualizations access the same server with the same visuid an error "used twice" may appear. in this case the most recent visu should add &reload=1 on the first call, to tell clearly it is the most recent visualization.

About Control units (Visualizations)

If you send requests with visuid=90 a Control Unit object with ID 90 is created in the server.

You can get the list of current Control Units in the web configuration, under Control Units.

After first access, the unit is listed as "Not configured". As soon as you change it’s configuration, e.g. by setting the option "Off by a short press on power", it is called Configured, and later cleanups of the Control Units list will not delete this one.

If there are no requests for this unit, after some time it will be listed under "currently inactive control units".

3.2. Asynchroneous

This means a HTTP call will not return immediately, but it will block until something changes.



Notice that &now is missing. The following will happen:

on first API call:

A Control Unit with ID 90 is created, and linked with the first zone.
The API call returns immediately, with full status data of the zone.

on all further API calls:

The existing Control Unit 90 is reused. The API call may block, until:

  • a timeout is reached (10 seconds approx.). in this case you get a reply like:

  • or until something changed, for example, the volume in the zone.

if (many) status data has changed at the server between two getChanges calls, the call may not block at all, but return the new status immediately.

when you receive a timeout, just re-run the getChanges immediately. this means you may run getChanges endlessly, in a loop, for example in a separate I/O thread. Because a request returns only on changes, this will cause no load problems with the server.

when you do not receive a timeout, i.e. the call returns immediately or after a few seconds (as soon as something has changed), then process the status data, and then re-run the getChanges request.

3.3. Appendix: schematic example for a Visu Client Application

3.3.1. Single Thread Application

This requires that you can test, in your programming language, if reply data for a socket exists (via select() call).

Main Thread

  • start: send /xml/zone/getChanges.xml?visuid=90&now

  • loop begin: update the GUI.

    • process input events from user.

    • send synchroneous commands like:
      receive reply, check rc AND process xml status data
      (same as with getChanges replies)

    • check if reply data exists for ongoing getChanges call
      (in C code: select() call on socket)
      IF data exists from trivum server:

      • Look for <userdata name="rc">0</userdata>.
        If NOT present
        _ process the error and wait a few seconds.
        Else if NOT a timeout
        _ process xml reply (status data)
        async call (just send)

    • if no data from server arrive within 1 minute

      • async call (just send)

    • re-run loop

3.3.2. Two Thread Application Example

Can be used if you prefer to run blocking receives on sockets in a separate I/O thread.

Main Thread

  • update the GUI.

  • process input events from user.

  • send synchroneous commands like:
    receive reply, check rc AND process xml status data
    (same as with getChanges replies)

  • receive status data and errors from Status Thread.

  • re-run this loop.

Status Thread

  • IF on first loop:

    • send /xml/zone/getChanges.xml?visuid=90&now

    • send /xml/zone/getChanges.xml?visuid=90&onlyChanges

  • receive reply (this is blocked up to 10 seconds)

  • Look for <userdata name="rc">0</userdata>.
    If this is NOT present then there is an error.
    Make sure not simply to re-run the loop on errors,
    but at least wait a few seconds, and tell the Main Thread.

  • Look for <rows><system><timeout>1</timeout>.
    IF this is present

    • re-run the loop immediately.

    • process the reply status data,
      and copy new status data to Main Thread.

  • re-run this loop.