Skip to content

Commit

Permalink
📝 update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@Gudsfile
Gudsfile committed Feb 8, 2025
1 parent 17a4eda commit 09a9ea6
Showing 1 changed file with 103 additions and 51 deletions.
154 changes: 103 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,79 @@

💿 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

💡 Inspired by:
- 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 <command to run>`.
🎉 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 <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.

```json
{
Expand All @@ -42,31 +91,65 @@ 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},
}
}
```

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 <command to run>`.

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.
Expand All @@ -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.
Expand All @@ -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 [email protected]:~
```

Install the project
```shell
ssh [email protected]
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.

0 comments on commit 09a9ea6

Please sign in to comment.