Metadata-Version: 2.4
Name: wzrd-listen
Version: 0.1.1
Summary: Passive music witness client for wzrd-listen. Observe playback locally, report checkpoints, finalize portable session receipts.
Author-email: twzrd <twzrd@twzrd.xyz>
License-Expression: MIT
Project-URL: Homepage, https://twzrd.xyz/listen
Project-URL: Repository, https://github.com/twzrd-sol/wzrd-final
Project-URL: Listen API, https://api.twzrd.xyz/v1/listen
Keywords: music,listening,proof-of-attention,witness,solana,x402,mpp,agent,co-listener
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pynacl<2,>=1.5
Requires-Dist: httpx<1,>=0.25

# wzrd-listen

Passive witness client for music playback. Observes what you're listening to locally, reports checkpoints to the TWZRD listen API, and finalizes sessions with a Merkle root.

No API keys. No Spotify login. Just proof.

## Install

```bash
pip install wzrd-listen
```

## Quick start

```bash
# Check setup
wzrd-listen doctor

# Witness live playback
wzrd-listen watch --summary

# Run a synthetic demo session
wzrd-listen demo --source spotify --track "Nujabes - Feather" --checkpoints 3 --summary
```

On first run, a device identity is created at `~/.config/wzrd-listen/device.json`. This key is your identity - no account required.

## Supported platforms

- **macOS**: Spotify, Music.app (via osascript)
- **Linux**: Any MPRIS player via playerctl (`apt install playerctl`)

## What happens

1. `wzrd-listen doctor` checks your player and API reachability
2. `wzrd-listen watch` polls your active player, sends checkpoints to the listen API
3. Session finalizes with a Merkle root - a cryptographic proof of your listening
4. View your proof profile at `https://twzrd.xyz/listen/{your-device-key}`

## Environment variables

| Variable | Purpose |
|----------|---------|
| `WZRD_LISTEN_API_BASE_URL` | Override API base URL (default: `https://api.twzrd.xyz/v1/listen`) |
| `WZRD_LISTEN_CONFIG_DIR` | Override config dir for device identity |
| `WZRD_LISTEN_TIMEOUT_SECONDS` | HTTP timeout override |

## Trust model

- **Witness proof** = trust anchor (local observation, Merkle tree)
- **AI summary** = product value (co-listener arc)
- **Verifier verdict** = fraud resistance
- **On-chain mint** = deferred until the event model stabilizes
