Metadata-Version: 2.4
Name: squeezy
Version: 0.3.0
Summary: Minimal Squeezebox player for Lyrion Music Server
License-Expression: MIT
Project-URL: Homepage, https://github.com/catcatcatcatcatcatcatcatcatcat/squeezy
Project-URL: Issues, https://github.com/catcatcatcatcatcatcatcatcatcat/squeezy/issues
Keywords: squeezebox,lyrion,slimproto,audio,music-player
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: miniaudio>=1.59
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-timeout>=2.0; extra == "test"

# Squeezy

Minimal Squeezebox-compatible player for [Lyrion Music Server](https://lyrion.org/) (formerly Logitech Media Server). Advertises as a player on your network, receives streaming audio, and plays it back through your default audio output. Supports synchronized playback with other players.

## Requirements

- macOS, Linux, or Windows
- Python 3.9+
- [ffmpeg](https://ffmpeg.org/)

## Install

Pick whichever method suits you. All three result in a `squeezy` command on your PATH.

### Option 1: pipx (recommended)

```bash
# macOS
brew install ffmpeg pipx
pipx install squeezy

# Debian/Ubuntu
sudo apt install ffmpeg pipx
pipx install squeezy
```

### Option 2: Homebrew tap (macOS only)

```bash
brew tap catcatcatcatcatcatcatcatcatcat/tap
brew install squeezy
```

This installs ffmpeg automatically as a dependency.

### Option 3: From source

```bash
git clone https://github.com/catcatcatcatcatcatcatcatcatcat/squeezy.git
cd squeezy
python3 -m venv .venv
source .venv/bin/activate
pip install .
```

For development (run directly without installing):

```bash
./run.sh -n "My Speaker" -vv
```

Squeezy checks for updates on startup and will notify you when a new version is available.

## Usage

```bash
# Auto-discover server on local network
squeezy

# Specify server and player name
squeezy -s 192.168.1.100 -n "Kitchen Speaker"

# Custom MAC address (for persistent player identity)
squeezy -m aa:bb:cc:dd:ee:ff

# List available audio output devices
squeezy -l

# Use a specific audio output (substring match, case-insensitive)
squeezy -d "HDMI" -n "Living Room"

# Verbose logging (connection, playback events, volume changes)
squeezy -v

# Debug logging (protocol-level detail: strm commands, STAT packets)
squeezy -vv

# Check installed version
squeezy --version
```

Your player will appear in the Lyrion Music Server web UI. Select it from the player dropdown to start streaming.

## Project Structure

```
src/squeezy/
├── squeezy.py          # Main player orchestrator
├── audio/              # Audio playback & streaming
│   ├── player.py       # miniaudio device, mixing, crossfade
│   └── stream_decoder.py # HTTP streaming & FFmpeg
├── protocol/           # SlimProto protocol & LMS communication
│   ├── handler.py      # Message dispatch & parsing
│   ├── slimproto.py    # Protocol constants & packet builders
│   └── lms_client.py   # LMS message operations
├── network/            # Network connectivity
│   └── server_connection.py # Socket management
└── config/             # Configuration & metadata
    ├── config.py       # XDG-compliant config
    └── metadata.py     # ICY metadata parsing
```

## Contributing

See [DEVELOPER.md](DEVELOPER.md) for a full walkthrough of the repo structure,
how to set up a dev environment, and how to cut a release.

## How it works

Squeezy implements the [SlimProto protocol](https://wiki.slimdevices.com/index.php/SlimProto_TCP_protocol) to communicate with Lyrion Music Server:

1. Discovers the server via UDP broadcast on port 3483
2. Registers as a player via TCP (HELO packet)
3. Receives stream commands from the server
4. Fetches audio via HTTP, decodes with ffmpeg, outputs via [miniaudio](https://github.com/irmen/pyminiaudio)
5. Reports playback status back to the server for sync coordination

## Uninstall

```bash
# If installed via pipx
pipx uninstall squeezy

# If installed via Homebrew
brew uninstall squeezy
brew untap catcatcatcatcatcatcatcatcatcat/tap
```

## Releasing (for maintainers)

Version is defined in one place: `pyproject.toml`. To release:

```bash
# 1. Bump version in pyproject.toml
# 2. Commit, tag, and push
git add -A && git commit -m "Release vX.Y.Z"
git tag vX.Y.Z && git push origin main vX.Y.Z

# 3. Build and publish to PyPI
python -m build && twine upload dist/squeezy-X.Y.Z*

# 4. Update Homebrew tap (macOS formula)
# Get the SHA256 of the new tag tarball:
curl -sL https://github.com/catcatcatcatcatcatcatcatcatcat/squeezy/archive/refs/tags/vX.Y.Z.tar.gz | shasum -a 256
# Update url + sha256 in homebrew-tap/Formula/squeezy.rb, commit and push
```

All installed users will see an upgrade notice on next startup.

## License

MIT
