aioresonate 0.12.0

Async Python implementation of the Resonate Protocol.

aioresonate

Async Python library implementing the Resonate Protocol.

For a WIP reference implementation of a server using this library, see Music Assistant

CLI Client

Note: The CLI client is currently included in the aioresonate library for development purposes. Once the Resonate Protocol stabilizes, it will be moved to a separate repository and package. This will require users to uninstall aioresonate[cli] and install the new CLI package separately.

This repository includes a highly experimental CLI client for testing and development purposes.

Installation

Install from PyPI:

pip install "aioresonate[cli]"

Install from source

git clone https://github.com/Resonate-Protocol/aioresonate.git
cd aioresonate
pip install ".[cli]"

Running the CLI

resonate-cli

The CLI client will automatically connect to a Resonate server on your local network and be available for playback.

Configuration Options

Client Identification

If you want to run multiple CLI clients simultaneously, each must have a unique identifier:

resonate-cli --id my-client-1 --name "Kitchen"
resonate-cli --id my-client-2 --name "Bedroom"

• --id: A unique identifier for this client (required if running multiple instances)
• --name: A friendly name displayed on the server (optional)

Audio Output Device Selection

By default, the CLI client uses your system's default audio output device. You can list available devices or select a specific device:

List available audio devices:

resonate-cli --list-audio-devices

This displays all audio output devices with their IDs, channel configurations, and sample rates. The default device is marked.

Select a specific audio device:

resonate-cli --audio-device 2

This is particularly useful for headless devices or when you want to route audio to a specific output.

Adjusting Playback Delay

The CLI supports adjusting playback delay to compensate for audio hardware latency or achieve better synchronization across devices.

Setting delay at startup:

resonate-cli --static-delay-ms -100

Note: Based on limited testing, the delay value is typically a negative number (e.g., -100 or -150) to compensate for audio hardware buffering.

Adjusting delay in real-time: While the client is running, you can use the delay command:

• delay - Show current delay value
• delay <ms> - Set absolute delay (e.g., delay -100)
• delay + <ms> - Increase delay (e.g., delay + 50)
• delay - <ms> - Decrease delay (e.g., delay - 25)

The synchronization will seamlessly adjust to the new delay value within a couple of seconds.

Debugging & Troubleshooting

If you experience synchronization issues or audio glitches, you can enable detailed logging to help diagnose the problem:

resonate-cli --log-level DEBUG

This provides detailed information about time synchronization. The output can be helpful when reporting issues.

Limitations & Known Issues

This client is highly experimental and has several known limitations:

• Platform Support: Only tested on Linux; macOS and Windows support untested
• Format Support: Currently fixed to uncompressed 44.1kHz 16-bit stereo PCM
• CLI User Experience: The CLI is pretty bare bones for now
• Configuration Persistence: Settings are not persistently stored; delay must be reconfigured on each restart using the --static-delay-ms option