Singularity OPAL reference

Singularity's audio output settings are exposed as eight OPAL Tasks in hub. They do what the Audio tab of Singularity's settings does, and add the output latency and a scriptable test tone. For the settings themselves see Choose an audio output in Singularity.

The tasks never open Singularity. The settings tasks work whether or not Singularity has been opened in hub: they read and write the stored settings, and a running Singularity follows the change. Only singularity.audio.play-test-tone needs Singularity to be open, and it fails with the canonical not-open message otherwise.

Permission scopes

Kind Tasks Tier Scope
Read list-outputs, get-output, get-volume identified none
Write set-output, set-output-pair, set-layout-override, set-volume, play-test-tone operational singularity.audio.write

Every failure message ends with State: no change., and a failed task changes nothing.

singularity.audio.list-outputs

Lists every audio output device with its channel count, how Singularity reads its channels, and how many output pairs it has.

Parameters: none.

Output keys:

Key Type Meaning
count integer Number of devices
outputs JSON array One object per device: id, description, channels, layout (Speakers (7.1), Separate outputs (14)), pairs, selected

Example:

hub --opal 'singularity.audio.list-outputs' -c

singularity.audio.get-output

Reports the current output device.

Parameters: none.

Output keys:

Key Type Meaning
id string System id of the device
description string Device name
layout string How Singularity reads the device
graph_layout string The layout Singularity produces, Speakers (stereo)
first_output integer First output of the pair, counted from 1
layout_override string automatic, speakers or separate
latency_ms number Audio written but not yet played, in milliseconds. Present only while Singularity is open

Example:

hub --opal 'singularity.audio.get-output' -c

singularity.audio.set-output

Selects the output device and stores the choice.

Parameters:

Name Required Default Description
device yes — The system id or the exact name of a present device

Output keys: id, layout.

Side effects: A running Singularity moves every output to the device.

Example:

hub --opal 'singularity.audio.set-output device="AudioBox 1818 VSL Multichannel"' -c

singularity.audio.set-output-pair

Selects the pair of outputs songs play on, for a device with separate outputs.

Parameters:

Name Required Default Description
first_output yes — First output of the pair, counted from 1

Output keys:

Key Type Meaning
first_output integer The pair that was set. It can be lower than requested when the pair did not fit
corrected boolean true when the requested pair was moved to fit

Fails on a device that reads as speakers, and when first_output is outside 1 to the device's channel count.

Example:

hub --opal 'singularity.audio.set-output-pair first_output=3' -c

singularity.audio.set-layout-override

Sets how the current device's channels are read.

Parameters:

Name Required Default Description
layout yes — automatic, speakers or separate. speakers is refused for a device with more than 8 channels

Output keys: layout.

Example:

hub --opal 'singularity.audio.set-layout-override layout=separate' -c

singularity.audio.get-volume

Reports the stored volume.

Parameters: none.

Output keys: volume (0 to 100).

singularity.audio.set-volume

Stores the volume and applies it to the session and the preview.

Parameters:

Name Required Default Description
volume yes — 0 to 100

Output keys: volume.

singularity.audio.play-test-tone

Plays a 440 Hz tone through the current device and pair. Use it after set-output-pair to confirm where the sound lands.

Parameters:

Name Required Default Description
seconds no 1.0 Tone length, 0.1 to 5.0

Output keys: played.

Example:

hub --opal 'singularity.audio.play-test-tone seconds=2' -c

See also