HiFiBerry Interaction API

Extension to expose the HiFiBerryOS (Beocreate) message bus as Webhook-API for instrumentation of arbitrary frontend commands.

With interactions, HiFiBerryOS offers various options for remote control. This instrumentation is far from complete, though. Luckily, the node.js-based frontend internally communicates via message bus events. A small extension allows to emit such (largely undocumented) commands directly, thereby exposing much more functionality as single-endpoint HTTP API.

Installation

The sources just need to be copied into the user extension folder:

scp -pr message-interact root@hifiberry.local:/etc/beocreate/beo-extensions/

A corresponding interaction can be created afterwards, for example with sendMessage as trigger endpoint. Received JSON data will be passed to the extension’s action.

New webhook endpoint trigger – Screenshot New interaction with bus message action – Screenshot

Usage

While using the frontend, the browser console logs triggered bus message commands. Alternatively, accepted structures need to be derived by Beocreate2 code inspection. For example, using the new endpoint to start an arbitrary remote or local stream with the radio source:

curl -i -X POST -H 'Content-Type: application/json' -d '{
  "data": {
    "target": "radio",
    "header": "play",
    "content": {
      "URL": "https://st01.sslstream.dlf.de/dlf/01/128/mp3/stream.mp3?aggregator=web",
      "stationName": "Deutschlandfunk"
    }
  }
}' http://hifiberry.local/interact/trigger/sendMessage

The following event maps to the stop playback button:

curl -i -X POST -H 'Content-Type: application/json' -d '{
  "data": {
    "target": "now-playing",
    "header": "transport",
    "content": {
      "action": "pause"
    }
  }
}' http://hifiberry.local/interact/trigger/sendMessage

As one use-case, a corresponding systemd unit allows to start and stop playback with a certain volume automatically on demand. (Similar functionality to starting a stream using the Chromecast Audio script).

[Unit]
Description=HiFiBerry Stream

[Service]
Type=oneshot
RemainAfterExit=true
Restart=on-failure
RestartSec=10
TimeoutSec=30
ExecStart=/usr/bin/curl -sS -o /dev/null --retry 2 --retry-delay 5 -X POST -H "Content-Type: application/json" \
    -d '{"data":{…}}' \
    http://hifiberry.local/interact/trigger/sendMessage
ExecStart=/usr/bin/curl -sS -o /dev/null --retry 2 --retry-delay 5 -X POST -H "Content-Type: application/json" \
    -d '{"data":{"target":"sound","header":"setVolume","content":100}}' \
    http://hifiberry.local/interact/trigger/sendMessage
ExecStop=/usr/bin/curl -sS -o /dev/null --retry 2 --retry-delay 5 -X POST -H "Content-Type: application/json" \
    -d '{"data":{"target":"now-playing","header":"transport","content":{"action":"pause"}}}' \
    http://hifiberry.local/interact/trigger/sendMessage

Code & Download