Metadata-Version: 2.4
Name: sendspin
Version: 0.1.0
Summary: Synchronized audio player for Sendspin servers
Author-email: Sendspin Protocol Authors <sendspin@openhomefoundation.org>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Sendspin-Protocol/sendspin
Project-URL: Bug Tracker, https://github.com/Sendspin-Protocol/sendspin/issues
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiosendspin
Requires-Dist: aioconsole>=0.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: sounddevice>=0.4.6
Provides-Extra: test
Requires-Dist: codespell==2.4.1; extra == "test"
Requires-Dist: mypy==1.18.2; extra == "test"
Requires-Dist: pre-commit==4.4.0; extra == "test"
Requires-Dist: pre-commit-hooks==6.0.0; extra == "test"
Requires-Dist: ruff==0.14.5; extra == "test"
Dynamic: license-file

# sendspin

[![pypi_badge](https://img.shields.io/pypi/v/sendspin.svg)](https://pypi.python.org/pypi/sendspin)

Synchronized audio player for [Sendspin](https://github.com/Sendspin-Protocol/spec) servers.

[![A project from the Open Home Foundation](https://www.openhomefoundation.org/badges/ohf-project.png)](https://www.openhomefoundation.org/)

## Quick Start

**Run directly with [uv](https://docs.astral.sh/uv/getting-started/installation/):**
```bash
uvx sendspin
```

## Installation

**With pip:**
```bash
pip install sendspin
```

**With uv:**
```bash
uv tool install sendspin
```

<details>
<summary>Install from source</summary>

```bash
git clone https://github.com/Sendspin-Protocol/sendspin.git
cd sendspin
pip install .
```

</details>

**After installation, run:**
```bash
sendspin
```

The player will automatically connect to a Sendspin server on your local network and be available for playback.

## Configuration Options

### Client Identification

If you want to run multiple players on the **same computer**, you can specify unique identifiers:

```bash
sendspin --id my-client-1 --name "Kitchen"
sendspin --id my-client-2 --name "Bedroom"
```

- `--id`: A unique identifier for this client (optional; defaults to `sendspin-<hostname>`, useful for running multiple instances on one computer)
- `--name`: A friendly name displayed on the server (optional; defaults to hostname)

### Audio Output Device Selection

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

**List available audio devices:**
```bash
sendspin --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:**
```bash
sendspin --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 player supports adjusting playback delay to compensate for audio hardware latency or achieve better synchronization across devices.

**Setting delay at startup:**
```bash
sendspin --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 player 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:

```bash
sendspin --log-level DEBUG
```

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

## Limitations & Known Issues

This player 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
- **User Experience**: The interface 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
