💿 Play music on speakers using NFC tags.
🚧 At the moment:
- NFC tags - CDs must be pre-populated in a JSON file (
discstoreincluded withjukeboxmay be of help to you) - supports many music providers (Spotify, Apple Music, etc.), just add the URIs to the JSON file
- only works with Sonos speakers (there is a "dryrun" player for development), but code is designed to add new ones
- as soon as the NFC tag is removed, the music pauses, then resumes when the NFC tag is replaced
💡 Inspired by:
📋 Table of contents:
Python 3.7 is supported by Jukebox up to version 0.4.1.
Python 3.8 is supported by Jukebox up to version 0.5.4.
The ui extension is only available for Python versions 3.10 and above.
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 nfc extra is optional but required for NFC reading, check compatibility.
Use pip in a virtual environment.
- 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- 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- Install
gukeboxinto the virtual environment:
pip install "gukebox[nfc]"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.
pipxcan be used with--system-site-packages.uvx/uv tool installare 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
lgpiopackage from source and it may require other system packages. - All releases can be downloaded and installed from the GitHub releases page.
For development read the Developer setup section.
tl;dr:
git clone https://github.com/Gudsfile/jukebox.git
uv syncSet the JUKEBOX_SONOS_HOST environment variable with the IP address of your Sonos Zone Player (see Available players and readers).
Initialize the library file with discstore or manually create it at ~/.jukebox/library.json.
To associate an URI with an NFC tag:
discstore add tag_id --uri /path/to/media.mp3or to pull the tag_id currently on the reader:
discstore add --from-current --uri /path/to/media.mp3Other commands are available, use --help to see them.
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:
# Python 3.9+ required
uv tool install gukebox[api]
# Python 3.10+ required, 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 discstore api
uv run --extra ui discstore uiComplete your ~/.jukebox/library.json file with each tag id and the expected media URI.
Take a look at library.example.json and the The library file section for more information.
Start the jukebox with the jukebox command (show help message with --help)
jukebox PLAYER_TO_USE READER_TO_USE🎉 With choosing the sonos player and nfc 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. |
--library |
Path to the library file, default: ~/.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. |
Dry run (dryrun)
Read a text entry.
Allows you to simulate reading an NFC tag by writting the tag id in the console.
Expected syntax: tag_id or tag_id duration_seconds.
- tag_id: the full identifier of the tag, in the format required by the system
- duration_seconds: a non-negative number of seconds used to simulate how long the tag remains in place. Fractional values are allowed.
Complete example:
your:tag:uid 2.5
NFC (nfc)
Read an NFC tag and get its UID.
This project works with an NFC reader like the PN532 and NFC tags like the NTAG2xx.
It is configured according to the Waveshare PN532 wiki.
Don't forget to enable the SPI interface using the command sudo raspi-config, then go to: Interface Options > SPI > Enable > Yes.
Dry run (dryrun)
Displays the events that a real speaker would have performed (playing …, pause, etc.).
Sonos (sonos) 
JUKEBOX_SONOS_HOST environment variable must be set with the IP address of your Sonos Zone Player.
You could set the environment varible with export JUKEBOX_SONOS_HOST=192.168.0.??? to use this speaker through the jukebox command.
Or set it in a .env file to use the uv run --env-file .env <command to run> version.
The library.json file is a JSON file that contains the artists, albums and tags.
It is used by the jukebox command to find the corresponding metadata for each tag.
And the discstore command help you to managed this file with a CLI, an interactive CLI, an API or an UI (see discstore --help).
By default, this file should be placed at ~/.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 ~/.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.
Install the project by cloning it and using uv to install the dependencies:
git clone https://github.com/Gudsfile/jukebox.git
uv syncAdd --all-extras to install dependencies for all extras (api and ui).
Set the JUKEBOX_SONOS_HOST environment variable with the IP address of your Sonos Zone Player (see Available players and readers).
To do this 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.
Start the jukebox with uv and use --help to show help message
uv run jukebox PLAYER_TO_USE READER_TO_USEStart the discstore uv and use --help to show help message
uv run discstore --helpFor the server-backed commands, include the matching extra:
uv run --extra api discstore api
uv run --extra ui discstore uiOther commands are available:
| 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. |
Contributions are welcome! Feel free to open an issue or a pull request.