diff --git a/README.md b/README.md index 0dcf9ff..e231884 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ 💿 Play music on speakers using NFC tags. -🚧 For the moment: -- artist, album and URI must be pre-populated in a JSON file -- only works with Spotify URIs +🚧 At the moment: +- artist, album and URI must be pre-populated in a JSON file (supports playlists via a workaround) +- supports many music providers (Spotify, Apple Music, etc.), just add the URIs to the JSON file - only works with Sonos speakers (or a "dryrun" player), 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 @@ -12,20 +12,69 @@ - https://github.com/hankhank10/vinylemulator - https://github.com/zacharycohn/jukebox +📋 Table of contents: +- [Install](#install) +- [Usage](#usage) +- [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. +The project remains in Python 3.7 to make it easier to use on hardware like Raspberry Pi. ## Install -Installing dependencies with [uv](https://github.com/astral-sh/uv) +Install the package from the pre-built available on the [releases page](https://github.com/Gudsfile/jukebox/releases) ```shell -uv sync +JUKEBOX_RELEASE_VERSION=v0.1.0 pip3 install https://github.com/Gudsfile/jukebox/releases/download/$JUKEBOX_RELEASE_VERSION/jukebox-0.1.0.tar.gz +``` +The `jukebox-0.1.0.tar.gz` is for now fixed to the version `0.1.0`, don't change it, only replace the `JUKEBOX_RELEASE_VERSION` variable. + +Create a `library.json` file and complete it with the desired artists and albums. +Complete the `tags` part of the `library.json` file with each tag id and the expected artist and album. +Take a look at `sample_library.json` and the [The library file](#the-library-file) section for more information. + +Set the `SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#available-players-and-readers)). + +## 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 ``` -Add `SONOS_HOST` to env with IP address of your Sonos Zone Player. To do this you can use a `.env` and `uv run --env-file .env `. +🎉 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 an input that does nothing. + +**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`) +Play music through a speaker that does nothing. -Create a `library.json` file (`cp sample_library.json library.json`) and complete it with the desired artists and albums. +**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 ` 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. ```json { @@ -42,16 +91,26 @@ Create a `library.json` file (`cp sample_library.json library.json`) and complet } ``` -## Usage +The `library` part is a dictionary containing artists as keys. +Each artist is a dictionary containing albums as keys and URIs as values. +URIs are the URIs of the music providers (Spotify, Apple Music, etc.). -This script 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). +The `tags` part is a dictionary that contains the tags UIDs as keys and the corresponding metadata as values. +Metadata contains the artist and album names. -Complete the `tags` part of the `library.json` file with each tag id and the expected artist and album. +For example, if you have the following `library.json` file: ```json { - "library": {…}, + "library": { + "artist a": { + "album 1": "uri", + "album 2": "uri" + }, + "artist b": { + "album 2": "uri" + } + }, "tags": { "ta:g1:id": {"artist": "artist a", "album": "album 1"}, "ta:g2:id": {"artist": "artist a", "album": "album 2", "shuffle": true}, @@ -59,14 +118,38 @@ Complete the `tags` part of the `library.json` file with each tag id and the exp } ``` -Start the script (show help message with `--help`) +Then, the jukebox will find the metadata for the tag `ta:g1:id` and play the corresponding album. + +It is also possible to use the `shuffle` key to play the album in shuffle mode. + +💡 You can add `{"playlists": {"playlist-name": "playlist-uri"}}` to the `library` part and configure a tag with `{"artist": "playlists", "album": "playlist-name"}` to allow playing a playlist with the jukebox. + +## Developer setup + +### Install + +Clone the project. + +Installing dependencies with [uv](https://github.com/astral-sh/uv) +```shell +uv sync +``` + +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 `. + +Create a `library.json` file and complete it with the desired artists and albums. +Complete the `tags` part of the `library.json` file with each tag id and the expected artist and album. +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 ``` -🎉 By approaching a NFC tag stored in the `library.json` file, you should hear the associated music begin. - -### player (`players/utils.py`) +#### player (`players/utils.py`) This part allows to play music through a player. It is used by `app.py` but can be used separately. @@ -85,7 +168,7 @@ Artist and album must be entered in the library's JSON file. This file can be sp 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`) +#### 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. @@ -103,37 +186,6 @@ 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. -## Build and install on Raspberry Pi - -### Install +## Contributing -Build the project -```shell -uv build -``` - -Copy the tar.gz file to the Raspberry Pi -```shell -scp dist/jukebox-0.1.0-py3-none-any.tar.gz pi@raspberrypi.local:~ -``` - -Install the project -```shell -ssh pi@raspberrypi.local -pip install jukebox-0.1.0-py3-none-any.tar.gz -``` - -Add `SONOS_HOST` to env with IP address of your Sonos Zone Player. -```shell -export SONOS_HOST= -``` - -Create a `library.json` file and complete it with the desired artists and albums (take a look at `sample_library.json`). - -### Usage - -You can start the jukebox with the `jukebox` command. - -```shell -jukebox -l ~/library.json sonos nfc -``` +Contributions are welcome! Feel free to open an issue or a pull request.