Remote recording and configuration¶

Start and stop recordings with Python or the CLI, and configure channels, bitrate, gain and maximum duration. Audio can be saved on the ring, streamed to the computer, or both.

Record with the CLI¶

Select a device, then record five seconds and download it:

uv run openzilo device use
uv run openzilo audio-record recordings/test.wav --seconds 5 --channels 1

WAV output requires ffmpeg. Inspect settings and recording status:

uv run openzilo audio-config
uv run openzilo audio-status

See the CLI guide for all commands.

Record and save with Python¶

Replace ADDRESS with the scanned address. This example stores five seconds on the ring, waits for saving, and downloads the completed recording:

import asyncio
import openzilo as sdk

ADDRESS = "AA:BB:CC:DD:EE:FF"

async def main():
    ring = await sdk.connect_ring(address=ADDRESS)
    try:
        if not ring.capabilities.supports("recording_control"):
            print("No compatible remote recording interface is available")
            return
        config = sdk.AudioRecordingConfig(
            output=sdk.AudioOutput.FLASH,
            channels=1,
            bitrate=16000,
            max_duration_ms=5000,
        )
        await sdk.set_audio_recording_config(ring, config)
        session_id = await sdk.start_audio_recording(ring)
        status = await sdk.wait_audio_recording_finished(ring, session_id)
        if status.saved:
            info, data = await sdk.download_audio_file(ring, status.file_index)
            bundle = sdk.save_audio_bundle(
                file_index=info.file_index, data=data, output_dir="recordings",
            )
            print(bundle.play_path)
    finally:
        await ring.disconnect()

asyncio.run(main())

Change recording settings¶

Read with get_audio_recording_config() and write with set_audio_recording_config(). Changes are allowed only while idle, survive reconnection and reset on reboot.

Sample rate is fixed at 16 kHz with 20 ms frames. The device also reports allowed ranges, checked by the SDK before writing. Other fixed Opus parameters can be read but not changed through this API.

CONTINUE_SAVING requires FLASH or LIVE_AND_FLASH.

Stop early or cancel¶

start_audio_recording() returns the recording session_id, not completion. To stop early:

await sdk.stop_audio_recording(ring, session_id)
status = await sdk.wait_audio_recording_finished(ring, session_id)

Pass cancel=True to discard an uncommitted recording. A stop response does not establish that a file was saved; query or wait for completion.

If START times out, query get_audio_recording_status() instead of repeating START. Session IDs last only for the current device boot and cannot be reused after reboot.

Stream with a device copy¶

For LIVE or LIVE_AND_FLASH, subscribe before starting. Call start_audio_recording() from receive_live_audio_file()'s on_subscribed callback. See remote_recording.py.

Interrupted live audio cannot resume across connections. With simultaneous saving, the device copy can be downloaded after saving finishes. Live-only disconnect fails that transfer.

API quick reference¶

All APIs above are asynchronous. Except the completion waiter, they accept timeout_s for a single request timeout.