Sonos Play Scribbler

Forked from sonos-lastfm

This script automatically logs music playing on your Sonos speakers. Scrobbling to Last.Fm support comes from the upstream repo. Hacking away on other destinations, like a text log file, sqlite db, and Apache Kafka.

Features

• Automatic Sonos speaker discovery on your network
• Real-time track monitoring and scrobbling
• Smart duplicate scrobble prevention
• Multi-speaker support
• Local data persistence for tracking scrobble history
• Secure credential storage using system keyring (when available)
• Modern CLI interface with interactive setup

Installation

Option 1: Install from PyPI (Recommended)

# Basic installation
pip install sonos-lastfm

# Optional: Install keyring backend for secure credential storage
pip install keyring keyrings.alt

uv version

uv init --name my-project
uv add "soco-scribbler @ git+https://crossjam/soco-scribbler"
uv add keyring keyrings.alt

Option 2: Local Development Setup

1. Install uv (Python package installer):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Setup and run using Make commands:

   # Setup Python environment with uv
   make setup
   
   # Install dependencies
   make install
   
   # For development, install additional tools (optional)
   make install-dev
   
   # Optional: Install keyring backend for secure credential storage
   pip install keyring keyrings.alt

   Run make help to see all available commands.

Building the package

The project uses uv to drive packaging workflows. You can build both the source and wheel distributions locally with:

make build-package

Behind the scenes this ensures the build frontend is available and then runs python -m build through uv. The resulting artifacts are placed in the dist/ directory.

Usage

Quick Start

1. Run the interactive setup:

   sonos-lastfm --setup

   If you have a keyring backend installed, credentials will be stored securely. Otherwise, you'll be prompted to store them in your environment or .env file.

2. Start scrobbling:

   sonos-lastfm

Command Line Options

sonos-lastfm [OPTIONS] COMMAND [ARGS]...

Commands:
  run      Run the Sonos Last.fm scrobbler (default if no command specified)
  show     Show stored credentials (passwords/secrets masked)
  reset    Remove all stored credentials
  resetup  Remove existing credentials and run setup again
  test     Test Last.fm API connectivity and show user information

Options:
  -u, --username TEXT            Last.fm username
  -p, --password TEXT           Last.fm password
  -k, --api-key TEXT           Last.fm API key
  -s, --api-secret TEXT        Last.fm API secret
  -i, --interval INTEGER       Scrobbling check interval in seconds [default: 1]
  -r, --rediscovery INTEGER    Speaker rediscovery interval in seconds [default: 10]
  -t, --threshold FLOAT        Scrobble threshold percentage [default: 25.0]
  --setup                      Run interactive setup
  --help                       Show this message and exit

Credential Management

The CLI provides several commands to manage your Last.fm credentials:

1. Show stored credentials:

   sonos-lastfm show

   This will display your stored credentials with sensitive values masked.

2. Reset (remove) all credentials:

   sonos-lastfm reset

   This will remove all stored credentials from your system keyring.

3. Reconfigure credentials:

   sonos-lastfm resetup

   This will remove existing credentials and run the interactive setup again.

Testing Last.fm Connection

Before starting the scrobbler, you can test your Last.fm API connection:

sonos-lastfm test

This will:

1. Test the connection to Last.fm API
2. Show your user information (username, total scrobbles, registration date)
3. Display your most recent scrobbled track

Use this command to verify your credentials are working correctly before starting the scrobbler.

Local Logging with soco-scribbler

Prefer to keep a personal record without touching Last.fm? Run the logger mode:

soco-scribbler scribble --log-format text --stdout

The command monitors your Sonos players and writes each scrobble event to a log file. By default entries are appended to soco-scribbler.log.jsonl in the platform-specific log directory (macOS: ~/Library/Logs/soco-scribbler, Linux: ~/.local/state/soco-scribbler, Windows: %LOCALAPPDATA%\soco-scribbler\Logs). Override the location with --log-file and switch between jsonl and text output with --log-format. Use --no-stdout if you only want file output.

Initialize User Directories

Run the helper once to create (or verify) the platform-specific directories used for credentials, cached data, and logs:

soco-scribbler init

This prints the resolved locations so you know where each file is stored.

Configuration Methods

You can configure the scrobbler in several ways (in order of precedence):

1. Command line arguments:

   sonos-lastfm --username "your_username" --api-key "your_api_key"

2. Environment variables:

   export LASTFM_USERNAME=your_username
   export LASTFM_PASSWORD=your_password
   export LASTFM_API_KEY=your_api_key
   export LASTFM_API_SECRET=your_api_secret
   export SCROBBLE_INTERVAL=1
   export SPEAKER_REDISCOVERY_INTERVAL=10
   export SCROBBLE_THRESHOLD_PERCENT=25
   
   sonos-lastfm

3. Secure keyring storage (recommended if available):

   # Store credentials securely (requires keyring backend)
   sonos-lastfm --setup
   
   # Run with stored credentials
   sonos-lastfm

4. Environment file (.env): Create a .env file in the Soco Scribbler configuration directory
   (macOS: ~/Library/Application Support/soco-scribbler,
   Linux: ~/.config/soco-scribbler,
   Windows: %APPDATA%\soco-scribbler):

   LASTFM_USERNAME=your_username
   LASTFM_PASSWORD=your_password
   LASTFM_API_KEY=your_api_key
   LASTFM_API_SECRET=your_api_secret

   The CLI loads this file automatically on startup.

Docker Setup (Linux Only)

Note: Docker setup is not recommended on macOS due to network mode limitations affecting Sonos discovery.

1. Create a .env file with your Last.fm credentials:

   LASTFM_USERNAME=your_username
   LASTFM_PASSWORD=your_password
   LASTFM_API_KEY=your_api_key
   LASTFM_API_SECRET=your_api_secret

2. Run with Docker Compose:

   docker-compose up -d

Scrobbling Rules

The script follows configurable scrobbling rules:

• A track is scrobbled when either:
  • Configured percentage of the track has been played (default: 25%, range: 0-100), OR
  • 4 minutes (240 seconds) of the track have been played
• For repeated plays of the same track:
  • Enforces a 30-minute minimum interval between scrobbles of the same track
  • Prevents duplicate scrobbles during continuous play

Data Storage

• Credentials are stored securely in your system's keyring
• Scrobble history and currently playing information is stored in the application data directory (macOS: ~/Library/Application Support/soco-scribbler, Linux: ~/.local/share/soco-scribbler, Windows: %APPDATA%\soco-scribbler) as:
  • last_scrobbled.json
  • currently_playing.json
• Logger output defaults to the platform log directory (macOS: ~/Library/Logs/soco-scribbler, Linux: ~/.local/state/soco-scribbler, Windows: %LOCALAPPDATA%\soco-scribbler\Logs) in soco-scribbler.log.jsonl

Requirements

• Python 3.11+
• Sonos speakers on your network
• Last.fm account and API credentials
  • Get your API credentials at: https://www.last.fm/api/account/create
• Optional but recommended:
  • Keyring backend for secure credential storage:

    pip install keyring keyrings.alt

  • Without a keyring backend, credentials must be stored in environment variables or .env file

Troubleshooting

Common issues and solutions:

• No speakers found: Ensure your computer is on the same network as your Sonos system
• Scrobbling not working: Check your Last.fm credentials with sonos-lastfm --setup
• Missing scrobbles: Verify that both artist and title information are available for the track
• Keyring errors: If you see keyring-related errors, either:
  1. Install a keyring backend: pip install keyring keyrings.alt
  2. Use environment variables or .env file for credentials instead