Sonic Byte plugin¶

The built-in call_baxter.plugins.sonic_byte plugin turns Call Baxter events into deterministic musical notifications by invoking the external sonic-byte-codec command.

The plugin deliberately does not copy the synthesizer into Call Baxter. It provides a small, constrained process boundary around the independently usable script and exposes three actions:

Action	Purpose
`sonic_byte.inspect`	Return the lossless musical mapping of byte payloads as JSON.
`sonic_byte.render`	Render payloads to stereo WAV files below an allowlisted output directory.
`sonic_byte.play`	Trigger playback; detached by default so event processing is not blocked.

Prerequisite¶

Install the script from the sibling scripting project:

cd /home/user/code/scripting
./install-scripts.sh install sonic-byte-codec
sonic-byte-codec 0xAB --compact

The Call Baxter daemon user must be able to resolve sonic-byte-codec through PATH. Alternatively, configure an explicit command prefix:

plugins:
  - module: call_baxter.plugins.sonic_byte
    config:
      command:
        - uv
        - run
        - --script
        - /home/user/code/scripting/media/sonic-byte-codec.py

Command arrays are executed directly. No shell is used and action values cannot inject additional flags outside the plugin's structured option set.

Recommended configuration¶

plugins:
  - call_baxter.plugins.system
  - module: call_baxter.plugins.sonic_byte
    config:
      command: sonic-byte-codec
      detached_playback: true
      allow_playback: true
      timeout: 30
      max_timeout: 120
      output_dir: /var/lib/call-baxter/sonic-byte
      allowed_players: [pw-play, paplay, aplay, ffplay, play]
      player: pw-play
      sound:
        root: C3
        waveform: fm
        space: room
        gain: 0.9
        cutoff: 7200

Important controls:

command: executable string or argument array. Use an array for uv run --script.
cwd: optional working directory for the child process.
output_dir: root directory for relative WAV outputs.
allow_absolute_output: disabled by default.
allow_playback: permits or disables the sonic_byte.play action.
detached_playback: defaults to true for non-blocking notifications.
allowed_players: allowlist for per-action player selection.
max_payload_tokens, max_token_bytes, max_payload_bytes: process-input limits.
sound: default render/play parameters overridden by action arguments.

Trigger playback from a rule¶

id: telegram-sonic-byte-alert
enabled: true
match:
  source: telegram
  kind: telegram.message.new
  attrs:
    text: byte me
actions:
  - kind: sonic_byte.play
    args:
      payload: ["text:message received"]
      root: Bb2
      waveform: pulse
      space: dub
      gain: 0.85

Payload entries use the script's explicit token forms:

payload: ["0xAB"]
payload: ["171", "0b00000001"]
payload: ["hex:deadbeef"]
payload: ["text:backup complete"]
payload: ["file:/var/lib/call-baxter/state.bin"]

file: payloads are read by sonic-byte-codec with the daemon user's permissions. Only use them with trusted rule/configuration authors.

Render a retained WAV¶

- kind: sonic_byte.render
  args:
    payload: ["text:deploy complete"]
    output: deploy-complete.wav
    root: C2
    waveform: saw
    space: room

Relative outputs remain inside output_dir; .. escapes and non-WAV extensions are rejected before starting a child process. The action result contains output_path and the parsed JSON render report.

Synchronous playback¶

Detached playback is appropriate for notifications. Use synchronous playback when a subsequent action must depend on completion:

- kind: sonic_byte.play
  args:
    payload: ["0xAB"]
    wait: true
    timeout: 20

The action then returns the child exit code, stdout, and stderr. A timeout or non-zero exit is represented as a failed Call Baxter action and can activate the rule's on_error chain.