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.

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]"

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 CONTRIBUTING.md.

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

Python Compatibility

Jukebox 1.0+ requires Python 3.11 or newer.

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

Readers

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.

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 a 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.

Contributing

Contributions are welcome! Found a bug, a typo, or something unclear? Open an issue or suggest an edit, with the pencil icon on GitHub or a pull request. See CONTRIBUTING.md.