| Name | gukebox JSON |
| Version |
0.3.0b0
JSON |
| download |
| home_page | None |
| Summary | A Jukebox to play music on speakers using 'CD' with NFC tag |
| upload_time | 2025-08-12 01:27:25 |
| maintainer | None |
| docs_url | None |
| author | Gudsfile |
| requires_python | <3.13,>=3.7 |
| license | None |
| keywords |
jukebox
discstore
music
nfc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# My jukebox
💿 Play music on speakers using NFC tags.
🚧 At the moment:
- NFC tags - CDs must be pre-populated in a JSON file (`discstore` included with `jukebox` may 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 be modified 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:
- https://github.com/hankhank10/vinylemulator
- https://github.com/zacharycohn/jukebox
📋 Table of contents:
- [Install](#install)
- [Usage](#usage)
- [First steps](#first-steps)
- [Avaible players and readers](#avaible-players-and-readers)
- [Readers](#readers)
- [Players](#players)
- [The library file](#the-library-file)
- [Developer setup](#developer-setup)
## Notes
The project remains in Python 3.7 to make it easier to use on hardware like Raspberry Pi.
However, it works on Python versions 3.7+.
The `api` and `ui` extras are only available for Python versions 3.8+ and 3.10+.
## Install
### PyPI
Install the package from [PyPI](https://pypi.org/project/gukebox/).
> [!WARNING]
> The package name is `gukebox` with `g` instead of a `j` (due to a name already taken).
To invoke the tool without installing it you could use `uvx`:
```shell
uvx --from gukebox jukebox
```
It is recommended to installing `jukebox` into an isolated environment, e.g., with `uv tool install`:
```shell
uv tool install gukebox
```
or with `pipx`
```shell
pipx install gukebox
```
However you could install it with `pip`:
```shell
pip install gukebox
```
### GitHub Releases
All releases can be downloaded from the [GitHub releases page](https://github.com/Gudsfile/jukebox/releases).
## First steps
Set the `SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#available-players-and-readers)).
Create a `~/.jukebox/library.json` file and complete it with the desired artists and albums.
For this, you can use `discstore` installed with the package or write it manually.
### Using the discstore
To associate an URI with an NFC tag:
```shell
discstore add tag_id uri
```
Other 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:
```shell
# Python 3.8+ required
uv tool install gukebox[api]
# Python 3.10+ required, ui includes the api extra
uv tool install gukebox[ui]
```
### Manually
Complete your `~/.jukebox/library.json` file with each tag id and the expected media URI.
Take a look at `sample_library.json` and the [The library file](#the-library-file) section for more information.
## Usage
Start the jukebox with the `jukebox` command (show help message with `--help`)
```shell
jukebox PLAYER_TO_USE READER_TO_USE -l YOUR_LIBRARY_FILE
```
🎉 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.
## Avaible players and readers
### Readers
**Dry run** (`dryrun`)
Read a text entry.
**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](https://www.waveshare.com/wiki/PN532_NFC_HAT).
### Players
**Dry run** (`dryrun`)
Displays the events that a real speaker would have performed (`playing …`, `pause`, etc.).
**Sonos** (`sonos`)
Play music through a Sonos speaker.
`SONOS_HOST` environment variable must be set with the IP address of your Sonos Zone Player.
You could set the environment varible with `export 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 file
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 `discsstore` 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.
```json
{
"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:
```json
"a:tag:uid": {
"uri": "uri",
"metadata": { "artist": "artist" }
}
```
It is also possible to use the `shuffle` key to play the album in shuffle mode:
```json
"a:tag:uid": {
"uri": "uri",
"option": { "shuffle": true }
}
```
To summarize, for example, if you have the following `~/.jukebox/library.json` file:
```json
{
"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
Clone the project.
Installing dependencies with [uv](https://github.com/astral-sh/uv):
```shell
uv sync
```
Add `--all-extras` to install dependencies for all extras (`api` and `ui`).
Set the `SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#available-players-and-readers)).
To do this you can use a `.env` file and `uv run --env-file .env <command to run>`.
Create a `library.json` file and complete it with the desired NFC tags and CDs.
Take a look at `sample_library.json` and the [The library file](#the-library-file) section for more information.
### Usage
Start the jukebox with `uv` and use `--help` to show help message
```shell
uv run jukebox PLAYER_TO_USE READER_TO_USE
```
#### player (`players/utils.py`)
This part allows to play music through a player.
It is used by `app.py` but can be used separately.
Show help message
```shell
uv run player --help
```
Play a specific album
```shell
uv run player sonos play --artist "Your favorite artist" --album "Your favorite album by this artist"
```
Artist and album must be entered in the library's JSON file. This file can be specified with the `--library` parameter.
For the moment, the player can only play music through Sonos speakers.
A "dryrun" player is also available for testing the script without any speakers configured.
#### reader (`readers/utils.py`)
This part allows to read an input like a NFC tag.
It is used by `app.py` but can be used separately, even if it is useless.
Show help message
```shell
uv run reader --help
```
Read an input
```shell
uv run reader nfc
```
For the moment, this part can only works with PN532 NFC reader.
A "dryrun" reader is also available for testing the script without any NFC reader configured.
## Contributing
Contributions are welcome! Feel free to open an issue or a pull request.
Raw data
{
"_id": null,
"home_page": null,
"name": "gukebox",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.7",
"maintainer_email": null,
"keywords": "jukebox, discstore, music, nfc",
"author": "Gudsfile",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/66/90/fae5be191ee25aa5b297d06b8c739b4b5f8375e9abaac434c521116ca723/gukebox-0.3.0b0.tar.gz",
"platform": null,
"description": "# My jukebox\n\n\ud83d\udcbf Play music on speakers using NFC tags.\n\n\ud83d\udea7 At the moment:\n\n- NFC tags - CDs must be pre-populated in a JSON file (`discstore` included with `jukebox` may be of help to you)\n- supports many music providers (Spotify, Apple Music, etc.), just add the URIs to the JSON file\n- only works with Sonos speakers (there is a \"dryrun\" player for development), but code is designed to be modified to add new ones\n- **as soon as** the NFC tag is removed, the music pauses, then resumes when the NFC tag is replaced\n\n\ud83d\udca1 Inspired by:\n\n- https://github.com/hankhank10/vinylemulator\n- https://github.com/zacharycohn/jukebox\n\n\ud83d\udccb Table of contents:\n\n- [Install](#install)\n- [Usage](#usage)\n- [First steps](#first-steps)\n- [Avaible players and readers](#avaible-players-and-readers)\n - [Readers](#readers)\n - [Players](#players)\n- [The library file](#the-library-file)\n- [Developer setup](#developer-setup)\n\n## Notes\n\nThe project remains in Python 3.7 to make it easier to use on hardware like Raspberry Pi.\nHowever, it works on Python versions 3.7+.\nThe `api` and `ui` extras are only available for Python versions 3.8+ and 3.10+.\n\n## Install\n\n### PyPI\n\nInstall the package from [PyPI](https://pypi.org/project/gukebox/).\n\n> [!WARNING]\n> The package name is `gukebox` with `g` instead of a `j` (due to a name already taken).\n\nTo invoke the tool without installing it you could use `uvx`:\n\n```shell\nuvx --from gukebox jukebox\n```\n\nIt is recommended to installing `jukebox` into an isolated environment, e.g., with `uv tool install`:\n\n```shell\nuv tool install gukebox\n```\n\nor with `pipx`\n\n```shell\npipx install gukebox\n```\n\nHowever you could install it with `pip`:\n\n```shell\npip install gukebox\n```\n\n### GitHub Releases\n\nAll releases can be downloaded from the [GitHub releases page](https://github.com/Gudsfile/jukebox/releases).\n\n## First steps\n\nSet the `SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#available-players-and-readers)).\n\nCreate a `~/.jukebox/library.json` file and complete it with the desired artists and albums.\nFor this, you can use `discstore` installed with the package or write it manually.\n\n### Using the discstore\n\nTo associate an URI with an NFC tag:\n\n```shell\ndiscstore add tag_id uri\n```\n\nOther commands are available, use `--help` to see them.\n\nTo 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:\n\n```shell\n# Python 3.8+ required\nuv tool install gukebox[api]\n\n# Python 3.10+ required, ui includes the api extra\nuv tool install gukebox[ui]\n```\n\n### Manually\n\nComplete your `~/.jukebox/library.json` file with each tag id and the expected media URI.\nTake a look at `sample_library.json` and the [The library file](#the-library-file) section for more information.\n\n## Usage\n\nStart the jukebox with the `jukebox` command (show help message with `--help`)\n\n```shell\njukebox PLAYER_TO_USE READER_TO_USE -l YOUR_LIBRARY_FILE\n```\n\n\ud83c\udf89 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.\n\n## Avaible players and readers\n\n### Readers\n\n**Dry run** (`dryrun`)\nRead a text entry.\n\n**NFC** (`nfc`)\nRead an NFC tag and get its UID.\nThis project works with an NFC reader like the **PN532** and NFC tags like the **NTAG2xx**.\nIt is configured according to the [Waveshare PN532 wiki](https://www.waveshare.com/wiki/PN532_NFC_HAT).\n\n### Players\n\n**Dry run** (`dryrun`)\nDisplays the events that a real speaker would have performed (`playing \u2026`, `pause`, etc.).\n\n**Sonos** (`sonos`)\nPlay music through a Sonos speaker.\n`SONOS_HOST` environment variable must be set with the IP address of your Sonos Zone Player.\nYou could set the environment varible with `export SONOS_HOST=192.168.0.???` to use this speaker through the `jukebox` command.\nOr set it in a `.env` file to use the `uv run --env-file .env <command to run>` version.\n\n## The library file\n\nThe `library.json` file is a JSON file that contains the artists, albums and tags.\nIt is used by the `jukebox` command to find the corresponding metadata for each tag.\nAnd the `discsstore` command help you to managed this file with a CLI, an interactive CLI, an API or an UI (see `discstore --help`).\n\nBy 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.\n\n```json\n{\n \"discs\": {\n \"a:tag:uid\": {\n \"uri\": \"URI of a track, an album or a playlist on many providers\",\n \"option\": { \"shuffle\": true }\n },\n \"another:tag:uid\": {\n \"uri\": \"uri\"\n },\n \u2026\n }\n}\n```\n\nThe `discs` part is a dictionary containing NFC tag UIDs.\nEach UID is associated with an URI.\nURIs are the URIs of the music providers (Spotify, Apple Music, etc.) and relate to tracks, albums, playlists, etc.\n\n`metadata` is an optional section where the names of the artist, album, song, or playlist are entered:\n\n```json\n \"a:tag:uid\": {\n \"uri\": \"uri\",\n \"metadata\": { \"artist\": \"artist\" }\n }\n```\n\nIt is also possible to use the `shuffle` key to play the album in shuffle mode:\n\n```json\n \"a:tag:uid\": {\n \"uri\": \"uri\",\n \"option\": { \"shuffle\": true }\n }\n```\n\nTo summarize, for example, if you have the following `~/.jukebox/library.json` file:\n\n```json\n{\n \"discs\": {\n \"ta:g1:id\": {\n \"uri\": \"uri1\",\n \"metadata\": { \"artist\": \"a\", \"album\": \"a\" }\n },\n \"ta:g2:id\": {\n \"uri\": \"uri2\",\n \"metadata\": { \"playlist\": \"b\" },\n \"option\": { \"shuffle\": true }\n }\n }\n}\n```\n\nThen, 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.\n\n## Developer setup\n\n### Install\n\nClone the project.\n\nInstalling dependencies with [uv](https://github.com/astral-sh/uv):\n\n```shell\nuv sync\n```\n\nAdd `--all-extras` to install dependencies for all extras (`api` and `ui`).\n\nSet the `SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#available-players-and-readers)).\nTo do this you can use a `.env` file and `uv run --env-file .env <command to run>`.\n\nCreate a `library.json` file and complete it with the desired NFC tags and CDs.\nTake a look at `sample_library.json` and the [The library file](#the-library-file) section for more information.\n\n### Usage\n\nStart the jukebox with `uv` and use `--help` to show help message\n\n```shell\nuv run jukebox PLAYER_TO_USE READER_TO_USE\n```\n\n#### player (`players/utils.py`)\n\nThis part allows to play music through a player.\nIt is used by `app.py` but can be used separately.\n\nShow help message\n\n```shell\nuv run player --help\n```\n\nPlay a specific album\n\n```shell\nuv run player sonos play --artist \"Your favorite artist\" --album \"Your favorite album by this artist\"\n```\n\nArtist and album must be entered in the library's JSON file. This file can be specified with the `--library` parameter.\n\nFor the moment, the player can only play music through Sonos speakers.\nA \"dryrun\" player is also available for testing the script without any speakers configured.\n\n#### reader (`readers/utils.py`)\n\nThis part allows to read an input like a NFC tag.\nIt is used by `app.py` but can be used separately, even if it is useless.\n\nShow help message\n\n```shell\nuv run reader --help\n```\n\nRead an input\n\n```shell\nuv run reader nfc\n```\n\nFor the moment, this part can only works with PN532 NFC reader.\nA \"dryrun\" reader is also available for testing the script without any NFC reader configured.\n\n## Contributing\n\nContributions are welcome! Feel free to open an issue or a pull request.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Jukebox to play music on speakers using 'CD' with NFC tag",
"version": "0.3.0b0",
"project_urls": {
"Repository": "https://github.com/Gudsfile/jukebox"
},
"split_keywords": [
"jukebox",
" discstore",
" music",
" nfc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0599c31e4b252c617e2a521d6b412668d34b1dc565bbabf174c177b018e770b3",
"md5": "c3b35ad0f1b22a4e1524cc3668ae2da5",
"sha256": "e3b55e844a06edf1f9cd49a4fcdedaa5d6454a4bad7e3e43beff87b66f7d01bd"
},
"downloads": -1,
"filename": "gukebox-0.3.0b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3b35ad0f1b22a4e1524cc3668ae2da5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.7",
"size": 41146,
"upload_time": "2025-08-12T01:27:24",
"upload_time_iso_8601": "2025-08-12T01:27:24.605173Z",
"url": "https://files.pythonhosted.org/packages/05/99/c31e4b252c617e2a521d6b412668d34b1dc565bbabf174c177b018e770b3/gukebox-0.3.0b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6690fae5be191ee25aa5b297d06b8c739b4b5f8375e9abaac434c521116ca723",
"md5": "4d79a219fd1116ea083cbff0406dbdb4",
"sha256": "84a8f6c9c6470c9e57041efe07f68c25e48bc5b854f04cc2df84448254084724"
},
"downloads": -1,
"filename": "gukebox-0.3.0b0.tar.gz",
"has_sig": false,
"md5_digest": "4d79a219fd1116ea083cbff0406dbdb4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.7",
"size": 24103,
"upload_time": "2025-08-12T01:27:25",
"upload_time_iso_8601": "2025-08-12T01:27:25.645848Z",
"url": "https://files.pythonhosted.org/packages/66/90/fae5be191ee25aa5b297d06b8c739b4b5f8375e9abaac434c521116ca723/gukebox-0.3.0b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 01:27:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gudsfile",
"github_project": "jukebox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gukebox"
}
