soir
OVERVIEW
The system module provides access to low-level facilities of the soir engine.
CLASS
AudioDeviceInfo
AudioDeviceInfo(id: int, name: str, is_default: bool, channels: int) -> None
Information about an audio device.
Arguments
| Name | Type | Description |
|---|---|---|
id |
Device index. | |
name |
Device name. | |
is_default |
Whether this is the system default device. | |
channels |
Number of channels supported by the device. |
FUNCTION
get_audio_in_devices
get_audio_in_devices() -> list[soir.rt.system.AudioDeviceInfo]
Get the current input audio devices.
Returns
– A list of audio input devices with detailed information.
get_audio_out_devices
get_audio_out_devices() -> list[soir.rt.system.AudioDeviceInfo]
Get the current output audio devices.
Returns
– A list of audio output devices with detailed information.
get_audio_underruns
get_audio_underruns() -> int
Get the number of audio output underruns since the device opened.
An underrun means the output device ran out of audio because the engine did not push a block in time: the device inserted silence, which is audible as a click or crackle. A count that grows while you listen confirms the crackles come from the engine not keeping up (input-side problems, like the external audio ring dropping frames, are reported in the log instead).
The counter belongs to the current output device instance, so switching the output device resets it.
Returns
– Number of underrun callbacks.
get_midi_out_devices
get_midi_out_devices() -> list[tuple[int, str]]
Get the current MIDI output devices.
Returns
– A list of MIDI output devices.
info
info() -> None
Prints the current layout of the system.
Returns
– None
record
record(file_path: str) -> bool
Record audio to a WAV file.
This function starts recording all audio output to the specified WAV file. Recording will automatically stop if this function is not called in a subsequent evaluation cycle (similar to how controls work). This enables automatic cleanup when code is changed or removed.
Arguments
| Name | Type | Description |
|---|---|---|
file_path |
Path to the WAV file where audio will be recorded. The file will be created or overwritten if it exists. Parent directories will be created automatically if needed. |
Returns
– True if recording started/continued successfully, False otherwise.
Raises
| Exception | Description |
|---|---|
InLoopException |
If called from within a loop context. Recording must be initiated from the global scope only. |
set_force_kill_at_shutdown
set_force_kill_at_shutdown(flag: bool) -> None
Sends a kill signal to the Python thread at exit.
This is required under rare circumstances where the Python thread is blocked (like when serving documentation).
Arguments
| Name | Type | Description |
|---|---|---|
flag |
bool, whether to set the force kill flag at shutdown or not. |
Returns
– None