Jukebox [gukebox]

Bring a physical experience back to music streaming with NFC tags.

Pick an album, place it on the reader, and the music starts playing. Remove it, and playback pauses automatically.

---

📋 Table of contents

Install • First steps • Usage • Readers • Players • The library file • Developer setup

---

Jukebox is an NFC-powered music player for connected speakers.

• 💿 Turn NFC tags into albums, playlists, or radio stations
• 🎵 Supports Spotify, Apple Music, and other music providers
• 🔊 Currently supports Sonos, with more speaker platforms planned
• 📡 Currently supports PN532-compatible NFC readers

💡 Inspired by

• https://github.com/hankhank10/vinylemulator
• https://github.com/zacharycohn/jukebox

Install

Install the package from PyPI.

Warning

The package name is gukebox with g instead of a j (due to a name already taken).

Note

The pn532 extra is optional but required for NFC reading, check compatibility.

Recommended installation

Use pip in a virtual environment.

1. If your Python version is 3.13 or newer and you want NFC support, install the system GPIO binding:

sudo apt update
sudo apt install python3-lgpio

2. Create a virtual environment:

# Python < 3.13
python3 -m venv jukebox

# Python >= 3.13 for NFC: use the system Python and include system packages
python3 -m venv --system-site-packages jukebox

source jukebox/bin/activate

3. Install gukebox into the virtual environment:

pip install "gukebox[pn532,ui]"

Important

For NFC on Python 3.13+, use the system Python that comes with your OS. A separately installed Python 3.13+ from uv, pyenv, Homebrew, or similar may not be able to import the system lgpio package, even when using --system-site-packages. If you already upgraded to a non-system Python 3.13+, use the system Python instead or use Python 3.12 or lower.

Alternative installations

• pipx can be used with --system-site-packages.
• uvx / uv tool install are not recommended for NFC on Python 3.13+ because they may select a non-system interpreter.
• For non-system Python 3.13+, you can still install via pip/uv/poetry/etc. but you must build the lgpio package from source and it may require other system packages.
• All releases can be downloaded and installed from the GitHub releases page.

Installation for development

For development read the Developer setup section.

git clone https://github.com/Gudsfile/jukebox.git
uv sync

Python Compatibility

Jukebox 1.0+ requires Python 3.11 or newer.

Python version	Compatible Jukebox versions	Notes
3.7	0.4.0 – 0.4.1	Legacy
3.8	0.4.0 – 0.5.4	Legacy
3.9 – 3.10	0.4.0 – 0.9.0 (incl. 1.0.0.dev13)	Legacy
3.11 – 3.12	0.4.0 – latest	Actively supported
3.13	0.5.3 – latest	Actively supported (see installation notes)

First steps

Initialize the library file with jukebox-admin or manually create it at ~/.config/jukebox/library.json.

Launch the web UI (requires the ui extra):

jukebox-admin ui

Usage

Start the jukebox with the jukebox command:

jukebox --player PLAYER --reader READER

🎉 With choosing the sonos player and pn532 reader, by approaching a NFC tag stored in the library.json file, you should hear the associated music begins.

Optional Parameters

Parameter	Description
--help	Show help message.
--player PLAYER	Player to use (sonos, dryrun).
--reader READER	Reader to use (pn532, dryrun).
--library	Path to the library file, default: ~/.config/jukebox/library.json.
--pause-delay SECONDS	Grace period before pausing when the NFC tag is removed. Fractional values such as 0.5 or 0.2 are supported, with a minimum of 0.2 seconds to avoid pausing on brief missed reads. Default: 0.25 seconds.
--pause-duration SECONDS	Maximum duration of a pause before resetting the queue. Default: 900 seconds (15 minutes).
--verbose	Enable verbose logging.
--version	Show version.

Readers

Name	Description
Dry Run (dryrun)	Simulates NFC tag reading via stdin. Input format: tag_id or tag_id duration_seconds.
Pn532 NFC (pn532)	Reads physical NFC tags. Works with a PN532 reader and NTAG2xx tags. Requires the pn532 extra and SPI enabled on the Raspberry Pi.

Note

See docs/readers.md for full setup, hardware requirements, and settings reference.

Players

Name	Description
Dry Run (dryrun)	Displays the events that a real speaker would have performed (playing …, pause, etc.).
Sonos (sonos)	Plays music through a Sonos speaker. Select by IP (--sonos-host), by name (--sonos-name), or let it auto-discover.

Note

See docs/players.md for the full configuration reference.

Admin CLI

Use jukebox-admin for admin workflows such as settings inspection and the admin API/UI servers.

settings

jukebox-admin settings show
jukebox-admin settings show --effective

api and ui

To use the api and ui commands, additional packages are required. You can install the package[extra] syntax regardless of the package manager you use, for example:

uv tool install gukebox[api]

# ui includes the api extra
uv tool install gukebox[ui]

When running from this repository with uv, include the extra on the command as well:

uv run --extra api jukebox-admin api
uv run --extra ui jukebox-admin ui

library

The library command lets you manage the library through a CLI or an interactive CLI:

jukebox-admin library add tag_id --uri /path/to/media.mp3

or to pull the tag_id currently on the reader:

jukebox-admin library add --from-current --uri /path/to/media.mp3

Other commands are available, use --help to see them.

The library file

The library.json file is a JSON file that maps each NFC tag to what to play. It is used by the jukebox command to find the corresponding metadata for each tag. The jukebox-admin library command helps you manage this file with a CLI, an interactive CLI, an API or a UI (see jukebox-admin --help).

By default, this file should be placed at ~/.config/jukebox/library.json. But you can use another path by creating a JUKEBOX_LIBRARY_PATH environment variable or with the --library argument.

{
  "discs": {
    "a:tag:uid": {
      "uri": "URI of a track, an album or a playlist on many providers",
      "option": { "shuffle": true }
    },
    "another:tag:uid": {
      "uri": "uri"
    },
    …
  }
}

The discs part is a dictionary containing NFC tag UIDs. Each UID is associated with an URI. URIs are the URIs of the music providers (Spotify, Apple Music, etc.) and relate to tracks, albums, playlists, etc.

metadata is an optional section where the names of the artist, album, song, or playlist are entered:

    "a:tag:uid": {
      "uri": "uri",
      "metadata": { "artist": "artist" }
    }

It is also possible to use the shuffle key to play the album in shuffle mode:

    "a:tag:uid": {
      "uri": "uri",
      "option": { "shuffle": true }
    }

To summarize, for example, if you have the following ~/.config/jukebox/library.json file:

{
  "discs": {
    "ta:g1:id": {
      "uri": "uri1",
      "metadata": { "artist": "a", "album": "a" }
    },
    "ta:g2:id": {
      "uri": "uri2",
      "metadata": { "playlist": "b" },
      "option": { "shuffle": true }
    }
  }
}

Then, the jukebox will find the metadata for the tag ta:g2:id and will send the uri2 to the speaker so that it plays playlist "b" in random order.

Developer setup

Install

Install the project by cloning it and using uv to install the dependencies:

git clone https://github.com/Gudsfile/jukebox.git
uv sync

To install dependencies for all extras (api, ui and pn532):

uv sync --extra api --extra ui # --extra pn532

Note

The pn532 extra requires compatible hardware and is intentionally excluded from this command.

If needed, you can use a .env file and uv run --env-file .env <command to run>. A .env.example file is available, you can copy it and modify it to use it.

Create a library.json file and complete it with the desired NFC tags and CDs. Take a look at library.example.json and the The library file section for more information.

Usage

Start the jukebox with uv and use --help to show help message

uv run jukebox --player PLAYER_TO_USE --reader READER_TO_USE

Use jukebox-admin for admin commands:

uv run jukebox-admin settings show

For the server-backed admin commands, include the matching extra:

uv run --extra api jukebox-admin api
uv run --extra ui jukebox-admin ui

Development commands

Command	Description
uv run ruff format	Format the code.
uv run ruff check	Check the code.
uv run ruff check --fix	Fix the code.
uv run pytest	Run the tests.

Pre-commit

prek is configured; you can install it to automatically run validations on each commit.

uv tool install prek
prek install

Contributing

Contributions are welcome! Feel free to open an issue or a pull request.