gukebox 0.3.0a0__tar.gz

gukebox-0.3.0a0/.gitignore

@@ -0,0 +1,14 @@
+.env
+.python-version
+
+.venv
+venv
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+built-package/
+*.egg-info
+dist/
+
+library.json
+library/

gukebox-0.3.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gudsfile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gukebox-0.3.0a0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: gukebox
+Version: 0.3.0a0
+Summary: A Jukebox to play music on speakers using 'CD' with NFC tag
+Project-URL: Repository, https://github.com/Gudsfile/jukebox
+Author: Gudsfile
+License-Expression: MIT
+License-File: LICENSE
+Keywords: discstore,jukebox,music,nfc
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.7
+Requires-Dist: pydantic==2.10.6; python_version >= '3.10'
+Requires-Dist: pydantic==2.5.3; python_version < '3.10'
+Requires-Dist: soco==0.30.11
+Requires-Dist: typing-extensions; python_version == '3.7.*'
+Provides-Extra: api
+Requires-Dist: fastapi==0.116.1; (python_version >= '3.8') and extra == 'api'
+Requires-Dist: uvicorn==0.33.0; (python_version >= '3.8' and python_version < '3.10') and extra == 'api'
+Requires-Dist: uvicorn==0.35.0; (python_version >= '3.10') and extra == 'api'
+Provides-Extra: ui
+Requires-Dist: fastui==0.7.0; (python_version >= '3.10') and extra == 'ui'
+Requires-Dist: jukebox[api]; extra == 'ui'
+Requires-Dist: python-multipart==0.0.20; (python_version >= '3.10') and extra == 'ui'
+Description-Content-Type: text/markdown
+
+# 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.

gukebox-0.3.0a0/Pn532-nfc-hat-code/raspberrypi/python/pn532/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    'pn532',
+    'i2c',
+    'spi',
+    'uart',
+    'PN532_I2C',
+    'PN532_SPI',
+    'PN532_UART'
+]
+from . import pn532
+from .i2c import PN532_I2C
+from .spi import PN532_SPI
+from .uart import PN532_UART

gukebox-0.3.0a0/Pn532-nfc-hat-code/raspberrypi/python/pn532/i2c.py

@@ -0,0 +1,156 @@
+# Waveshare PN532 NFC Hat control library.
+# Author: Yehui from Waveshare
+#
+# The MIT License (MIT)
+#
+# Copyright (c) 2015-2018 Adafruit Industries
+# Copyright (c) 2019 Waveshare
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+"""
+This module will let you communicate with a PN532 RFID/NFC chip
+using I2C on the Raspberry Pi.
+"""
+
+import fcntl
+import os
+import time
+import RPi.GPIO as GPIO
+from .pn532 import PN532, BusyError
+
+# pylint: disable=bad-whitespace
+# PN532 address without R/W bit, i.e. (0x48 >> 1)
+I2C_ADDRESS                    = 0x24
+I2C_CHANNEL                    = 1
+
+# ctypes defines for i2c, see <linux/i2c-dev.h>
+I2C_SLAVE                      = 1795
+
+
+class I2CDevice:
+    """Implements I2C device on ioctl"""
+    def __init__(self, channel, addr):
+        self.addr = addr
+        self.i2c = os.open('/dev/i2c-%d' % channel, os.O_RDWR)
+        if self.i2c < 0:
+            raise RuntimeError('i2c device does not exist')
+        if fcntl.ioctl(self.i2c, I2C_SLAVE, addr) < 0:
+            raise RuntimeError('i2c slave does not exist')
+
+    def write(self, buf):
+        """Wrapper method of os.write"""
+        return os.write(self.i2c, buf)
+
+    def read(self, count):
+        """Wrapper method of os.read"""
+        return os.read(self.i2c, count)
+
+
+class PN532_I2C(PN532):
+    """Driver for the PN532 connected over I2C."""
+    def __init__(self, irq=None, reset=None, req=None, debug=False):
+        """Create an instance of the PN532 class using I2C. Note that PN532
+        uses clock stretching. Optional IRQ pin (not used),
+        reset pin and debugging output.
+        """
+        self.debug = debug
+        self._irq = irq
+        self._req = req
+        GPIO.setmode(GPIO.BCM)
+        # With I2C, we recommend connecting RSTPD_N (reset) to a digital pin for manual
+        # harware reset
+        GPIO.setup(reset, GPIO.OUT)
+        # On Raspberry Pi, you must also connect a pin to P32 "H_Request" for hardware
+        # wakeup! this means we don't need to do the I2C clock-stretch thing
+        GPIO.setup(req, GPIO.OUT)
+        self._gpio_init(irq=irq, req=req, reset=reset)
+        self._i2c = I2CDevice(I2C_CHANNEL, I2C_ADDRESS)
+        super().__init__(debug=debug, reset=reset)
+
+    def _gpio_init(self, reset, irq=None, req=None):
+        self._irq = irq
+        self._req = req
+        GPIO.setmode(GPIO.BCM)
+        if reset:
+            GPIO.setup(reset, GPIO.OUT)
+            GPIO.output(reset, True)
+        if irq:
+            GPIO.setup(irq, GPIO.IN)
+        if req:
+            GPIO.setup(req, GPIO.OUT)
+            GPIO.output(req, True)
+
+    def _reset(self, pin):
+        """Perform a hardware reset toggle"""
+        GPIO.output(pin, True)
+        time.sleep(0.1)
+        GPIO.output(pin, False)
+        time.sleep(0.5)
+        GPIO.output(pin, True)
+        time.sleep(0.1)
+
+    def _wakeup(self): # pylint: disable=no-self-use
+        """Send any special commands/data to wake up PN532"""
+        if self._req:
+            GPIO.output(self._req, True)
+            time.sleep(0.1)
+            GPIO.output(self._req, False)
+            time.sleep(0.1)
+            GPIO.output(self._req, True)
+        time.sleep(0.5)
+
+    def _wait_ready(self, timeout=10):
+        """Poll PN532 if status byte is ready, up to `timeout` seconds"""
+        time.sleep(0.01) # required after _wait_ready()
+        status = bytearray(1)
+        timestamp = time.monotonic()
+        while (time.monotonic() - timestamp) < timeout:
+            try:
+                status[0] = self._i2c.read(1)[0]
+            except OSError:
+                self._wakeup()
+                continue
+            if status == b'\x01':
+                return True  # No longer busy
+            time.sleep(0.005)  # lets ask again soon!
+        # Timed out!
+        return False
+
+    def _read_data(self, count):
+        """Read a specified count of bytes from the PN532."""
+        try:
+            status = self._i2c.read(1)[0]
+            if status != 0x01:             # not ready
+                raise BusyError
+            frame = bytes(self._i2c.read(count+1))
+        except OSError as err:
+            if self.debug:
+                print(err)
+            return
+
+        if self.debug:
+            print("Reading: ", [hex(i) for i in frame[1:]])
+        else:
+            time.sleep(0.1)
+        return frame[1:]   # don't return the status byte
+
+    def _write_data(self, framebytes):
+        """Write a specified count of bytes to the PN532"""
+        self._i2c.write(framebytes)