Spotizerr Authentication Utility

A command-line tool to help you authenticate and register a Spotify account with your Spotizerr instance. This utility simplifies the process by programmatically capturing Spotify session credentials and posting them to your Spotizerr backend.

Features

• Interactive Setup: Guides you through the process of connecting to your Spotizerr instance.
• API Credential Check: Automatically checks if your Spotizerr instance has the required Spotify API client_id and client_secret and prompts you to add them if they are missing.
• Spotify Connect Integration: Uses librespot-spotizerr-phoenix to create a temporary Spotify Connect device, allowing you to capture credentials securely by simply playing a song.
• Colored Output: Uses color-coded terminal output to highlight important information and make the process easier to follow.
• Clean Exit: Gracefully handles interruptions and ensures a clean shutdown.

Prerequisites

• Docker
• A running instance of Spotizerr.
• Spotify client_id and client_secret. You can get these by creating an application on the Spotify Developer Dashboard.

Usage

Run the script from your terminal:

docker run --network=host --rm -it spotizerrphoenix/spotizerr-auth

If docker doesn't work (it probably won't unless your on linux) you can still run it in bare metal.

Run the installer

Linux / macOS

python3 -m venv .venv && source .venv/bin/activate && pip install spotizerr-auth-phoenix

Windows (PowerShell)

python -m venv .venv; .venv\Scripts\Activate.ps1; pip install spotizerr-auth-phoenix

Windows (cmd.exe)

python -m venv .venv && .venv\Scripts\activate && pip install spotizerr-auth-phoenix

And then run

spotizerr-auth-phoenix

You will have to activate the virtual environment every time you want to use the tool.

The script will guide you through the following steps:

1. Enter Spotizerr URL: You'll be prompted for the base URL of your Spotizerr instance. You can press Enter to use the default (http://localhost:7171).

2. Configure API Credentials: The script checks if your Spotizerr instance is configured with a Spotify client_id and client_secret.

   • If they are missing, it will ask if you want to configure them.
   • Select y and enter your credentials when prompted. This is a one-time setup.

3. Enter Account Details:

   • Provide a name for the account to identify it in Spotizerr.
   • Enter your two-letter Spotify region code (e.g., US, DE, MX).

4. Authenticate via Spotify Connect:

   • The utility will ask you to name the temporary Spotify Connect device (default: randomized like Device - 8KQ2).
   • It will then start that device on your network.
   • Open Spotify on any device (phone, desktop), start playing a track, and use the "Connect to a device" feature to transfer playback to the new device.
   • Once you transfer playback, the script captures the session, creates a credentials.json file, and shuts down the Connect server.

5. Register with Spotizerr: The script automatically sends the captured credentials to your Spotizerr instance, creating or updating the account.

6. Cleanup: Finally, it will ask if you want to delete the credentials.json file. It's recommended to do so for security.

After these steps, your Spotify account will be registered in Spotizerr and ready to use.

How It Works

The script uses librespot-spotizerr's Zeroconf implementation to advertise a Spotify Connect device on the local network. When you transfer playback to this device, librespot-spotizerr handles the authentication with Spotify's servers and stores the session details (including the necessary refresh token) in a local credentials.json file. The advertised device name is the one you provide during the prompt.

Once this file is created, the script reads it and makes a POST request to the Spotizerr API endpoint /api/credentials/spotify/{accountName}. The request body is a JSON object containing the user's region and the contents of credentials.json, which Spotizerr then stores for future use.

The initial check for client_id and client_secret ensures that Spotizerr has the necessary global API credentials to perform metadata lookups and other API-dependent tasks.

Device Identity Prompts

Before starting Spotify Connect discovery, the tool prompts you for device identity fields. Press Enter to accept the defaults for the selected device type:

• Device name: Living Room Speaker
• Device type: SPEAKER
• Device ID: a random 40-character hex string (generated each run)
• Device software version: Spotify Connect 3.2.6
• System info string: Spotify Connect 3.2.6; Linux; Speaker

Valid device type values:

UNKNOWN, COMPUTER, TABLET, SMARTPHONE, SPEAKER, TV, AVR, STB, AUDIO_DONGLE, GAME_CONSOLE, CAST_VIDEO, CAST_AUDIO, AUTOMOBILE, SMARTWATCH, CHROMEBOOK, UNKNOWN_SPOTIFY, CAR_THING, OBSERVER, HOME_THING

Notes:

• The login handshake still reports OS as OS_UNKNOWN (hardcoded in the librespot library).
• Changing device_id between attempts will break decryption of the login blob.
• Preferred locale is derived from the Spotify region prompt.
• Defaults for device name/software/system info adjust based on the device type you choose.
• The device type prompt is used to select a realistic profile (name/software/system info) so the advertised device looks consistent.
• Device identity details are stored alongside the Spotify credentials in Spotizerr and reused for future librespot sessions.

Logging

The tool enables debug logging by default so you can see what it is sending. It logs:

• The device identity values that will be advertised and sent during authentication.
• HTTP requests to your Spotizerr server (URLs, payload keys, and response codes).
• Librespot and Zeroconf debug output from the underlying library.