# 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](https://lavaforge.org/spotizerrphoenix/spotizerr-phoenix).
- Spotify `client_id` and `client_secret`. You can get these by creating an application on the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard).

## Usage

Run the script from your terminal:

```bash
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

<details>
<summary>Linux / macOS</summary>

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

</details>
    
<details>
<summary>Windows (PowerShell)</summary>

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

</details>

<details>
<summary>Windows (cmd.exe)</summary>

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

</details>

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.
