Metadata-Version: 2.5
Name: tinyjukebox
Version: 0.49.0
Summary: RFID-controlled audio player for albums: state machines, ffmpeg/aplay playback, REST API and web page.
Project-URL: Homepage, https://github.com/tgd1975/tinyjukebox
Project-URL: Documentation, https://github.com/tgd1975/tinyjukebox/tree/master/docs
Author-email: Tobias Gawron-Deutsch <tobias@strix.at>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: audio player,kids,raspberry pi,rfid
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Environment :: Web Environment
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Home Automation
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.18
Requires-Dist: mutagen>=1.47
Requires-Dist: pyyaml>=6.0
Requires-Dist: segno>=1.6
Requires-Dist: tantamount<0.4,>=0.3.2
Provides-Extra: box
Requires-Dist: dbus-fast>=5.0; (sys_platform == 'linux') and extra == 'box'
Requires-Dist: pyalsaaudio>=0.11; (platform_machine == 'aarch64' or platform_machine == 'armv7l' or platform_machine == 'armv6l') and extra == 'box'
Requires-Dist: rpi-lgpio; (platform_machine == 'aarch64' or platform_machine == 'armv7l' or platform_machine == 'armv6l') and extra == 'box'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo.svg" alt="Tiny Jukebox" width="460">
</picture>

RFID-controlled music box for children: put a tag (a disc, a figure, a card – anything with an RFID chip) on the box,
and the linked album continues where it stopped last time. The tag is only ever read, never written; the UID is all
that counts.

<img src="docs/images/box-2026.jpg" alt="The box today: a white wooden case with a grille of rings at the front, on top the round lid with buttons, LED and a tag in its window" width="360">

## 1. What Tiny Jukebox does especially well

- **One library, any number of boxes.** `tinyjukebox-library` runs on a NAS or the PC and holds the tags, albums,
  radio stations and covers. Every box keeps a copy, fetches the albums it lacks, plays without the library,
  and the library shows what was played.
- **Updates with a way back.** A push to `master` that changes the software becomes a release. The library
  fetches it, a box tries the new version at its next start and goes back to the one before by itself if it fails.
- **Set up with one line, run like an appliance.** One line on a fresh Raspberry Pi OS turns it into a box – fetched
  from GitHub, or from the page of the library, which links the box to it at once. The library is a package for a
  Synology NAS, a Docker image or `pip install`. Backups run by a schedule, users and roles are managed on the web
  page.
- **Everything on one web page.** Link tags (also by scanning them with a phone), upload albums, set radio
  stations and volume limits, change covers – over HTTPS, in English and German, with a REST API behind it.
- **Bluetooth headset as a first-class way to listen.** Pairing with a button gesture, own start volume and maximum,
  pause when the connection is lost, headset buttons.
- **Reads reliably.** The RC522 is read by a small C++ program that recovers by itself after a crash or a reset of
  the chip, and playback keeps its position over a power cut.
- **Spotify and phones, built but not yet tried for real.** A tag can also play an entry of Spotify – an album, a
  playlist, a podcast – through Spotify Soloist, and the app for Android makes a phone a box
  ([app.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/app.md)). Spotify is tested on the PC and has not played on a box yet; the app ran in the
  Android emulator, not yet on a real phone ([roadmap.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/roadmap.md), section 1).

## 2. Software and hardware

The software is one Python process (one systemd service) with device drivers, state machines, player and web page
that exchange messages over an in-process queue – no broker, no further services. State machines run tags, album
playback, radio, Spotify and volume. Playback is `ffmpeg | aplay`: the position is saved, with next/previous, pause and
internet radio stations. An entry of Spotify plays through Spotify Soloist, which the box starts with a PipeWire of
its own; its sound goes to `aplay` as well. The app for Android phones (`app/`, Kotlin) makes a phone a box: it reads
the tag with NFC and plays its album or station with the data of the library ([app.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/app.md)).

**The software does not need a Raspberry Pi or a particular amplifier.** Our own box happens to be a Raspberry Pi 3
with an RC522, four buttons, an RGB LED and a Pimoroni Audio Amp SHIM; that is the platform we built and tested, not a
requirement of the application.

- **Sound:** any ALSA device and mixer control, set in the config. The Audio Amp SHIM is not mentioned in the code.
- **Core:** state machines, player, web page, REST API and library are plain Python on Linux; they run on a PC
  without any hardware (`--no-hardware`), which is also how the tests run.
- **Drivers:** buttons, LED, RFID reader and Bluetooth are drivers selected and wired in the config
  ([drivers.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/drivers.md)); the pins are config, not code.
- **RFID reader:** the driver starts any program that prints `ready`, `tag <UID>` and `removed`, one per line
  ([rfid-reader.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/rfid-reader.md)). The C++ `rfid-reader` for the RC522 on a Raspberry Pi is the one
  we ship; another reader or another board needs only such a program and the `command` of the driver.
- **What is tied to the Pi today:** the shipped GPIO drivers (`rpi-lgpio`) and `rfid-reader` (SPI through bcm2835).
  Bluetooth uses BlueZ and BlueALSA, which are not specific to the Pi.

The box runs the released version of its slot and works with the library on the NAS. The web page and the user
documentation are English and German; code and developer documentation are English.

## 3. History

The first box was built for Christmas 2019: RFID, presence detection and four buttons, from the start. The
circuit and the printed parts are in [`hardware/`](https://github.com/tgd1975/tinyjukebox/blob/master/hardware/README.md); the software has been rebuilt several times
since. The [changelog](https://github.com/tgd1975/tinyjukebox/blob/master/CHANGELOG.md) tells the story from 2018 on.

| The lid on its circuit, December 2019 | The first box at work, a figure on the lid as tag |
| --- | --- |
| <img src="docs/images/lid-on-circuit-2019.jpg" alt="The wired lid with the LED on, lying on the printed circuit next to the Pi" width="360"> | <img src="docs/images/box-open-figure-2019.jpg" alt="The first box with its back open and a figure standing on the lid" width="270"> |

The hardware has changed as well, while the box stayed in use:

| Inside in 2019: Pi Zero, separate amplifier, power bank | Inside today: Pi 3 with the Audio Amp SHIM, power bank |
| --- | --- |
| <img src="docs/images/inside-2019.jpg" alt="The inside of the first box: a Pi Zero on the right wall, a separate amplifier on the left, the speaker in the middle, rainbow ribbon cables and the power bank in a black frame at the bottom" width="360"> | <img src="docs/images/inside-2026.jpg" alt="The inside of the box today, from the back: the Pi 3 with the Audio Amp SHIM on the left wall, the speaker in the middle, the power bank in its frame below, the open back panel with the USB socket and the switch" width="360"> |

## 4. Documentation

All documents as one site, with search and a menu by reader: <https://tgd1975.github.io/tinyjukebox/>.

### 4.1 For users and administrators (English and German)

| Document | Content |
| --- | --- |
| Quick guide: [English](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/en/quick-guide.md), [Deutsch](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/de/quick-guide.md) | text of the quick guide card (A6, two sides): tags, buttons, LED, headset; web page |
| Manual: [English](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/en/manual.md), [Deutsch](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/de/manual.md) | the full manual: operating the box, LED, pause, Bluetooth headset, web page, MP3 albums, radio, Spotify, volume limits, users, troubleshooting, library |
| Administration: [English](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/en/admin.md), [Deutsch](https://github.com/tgd1975/tinyjukebox/blob/master/docs/user/de/admin.md) | setting up a box and the library, updates, users and access, backups, logs, configuration, troubleshooting – the complete details in the developer documents below |

### 4.2 For developers and hardware, the complete details for administrators (English)

| Document | Content |
| --- | --- |
| [Architecture](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/architecture.md) | components, state machines, volume, player, headset logic, data model, messages, framework, threads, latency measurement |
| [Drivers](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/drivers.md) | driver framework, buttons, LED, RFID driver, Bluetooth stack and driver |
| [rfid-reader](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/rfid-reader.md) | the C++ program that reads the RC522: interface, read loop, design decisions, build, tests |
| [REST API and web page](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/rest-api.md) | server, authentication, roles, endpoints, server-sent events |
| [Configuration](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/configuration.md) | command line, all keys of the config file |
| [The box](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/box.md) | hardware, pins, operating system, audio, file layout, service, robustness, decisions |
| [Library, synchronization and self-update](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/library.md) | the library on the NAS or the PC with its package, synchronization of the boxes and phones, the phone as reader, self-update with slots, play statistics, release pipeline, test bed, tests |
| [The app](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/app.md) | the app for Android phones: simple mode (a phone as a box), expert mode (the page of the library), pairing, presence of a tag, the cache of albums, Spotify, delivery, the code |
| [Deployment](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/deployment.md) | how software and setup reach the box, Ansible playbook, roles, variables, first setup, updates, changes on the box, acceptance checklist |
| [Operations](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/operations.md) | service, logs, users, albums, console, latency, diagnostics, backups |
| [Development](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/development.md) | setup, the box on the PC, repository layout, dependencies, tests, quality checks, conventions, releases, the app, the documentation site |
| [Style guide](https://github.com/tgd1975/tinyjukebox/blob/master/docs/style-guide/README.md) | name, logo, colours, type, shapes, the light of the box, how the documents are written |
| [Open points and roadmap](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/roadmap.md) | what is not verified yet, known gaps, envisioned changes |

Reference files: [example config](https://github.com/tgd1975/tinyjukebox/blob/master/docs/config.example.yaml), [config of the box](https://github.com/tgd1975/tinyjukebox/blob/master/deploy/config/tinyjukebox.yaml),
[config schema](https://github.com/tgd1975/tinyjukebox/blob/master/docs/config_schema.json). Hardware: [circuit and printed parts](https://github.com/tgd1975/tinyjukebox/blob/master/hardware/README.md),
[key data and data sheets](https://github.com/tgd1975/tinyjukebox/blob/master/docs/hardware/README.md).

## 5. Quick start

**A box:** write Raspberry Pi OS Lite (64-bit) with the Raspberry Pi Imager, log in over SSH and run

```bash
curl -fsSL https://github.com/tgd1975/tinyjukebox/releases/latest/download/install.sh | sudo bash
```

([deployment.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/deployment.md), section 5). **Library and a box without hardware to try it,** with
Docker – the two passwords are files next to `compose.yaml`:

```bash
cd deploy/docker && openssl rand -hex 12 > admin-password && openssl rand -hex 24 > bootstrap-password
docker compose up -d   # https://localhost:8866/ and https://localhost:8443/, user admin, the password in admin-password
```

or with Python: `pip install tinyjukebox`, then `tinyjukebox-library --data ~/library` and
`tinyjukebox --data ~/box --no-hardware --no-audio` ([library.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/library.md), section 3.9).

**Development**, on the PC, without hardware:

```bash
uv sync --all-groups
cp docs/config.example.yaml my-config.yaml                      # adjust the paths
uv run tinyjukebox -c my-config.yaml --no-hardware --no-audio   # web page: https://localhost:8443/
```

Checks:

```bash
uv run pytest --cov                     # tests (need ffmpeg; no sound card, no Pi hardware)
uv run ruff format --check . && uv run ruff check . && uv run mypy
```

Library and box on the PC: `./start_library.sh` and `./start_sim.sh`
([library.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/library.md), section 3.8).

Bring a change to the box: raise the version, add a section to `CHANGELOG.md`, push to `master`. The workflow
publishes the release and the box installs it by itself ([development.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/development.md),
section 8). System setup and config of our box come from the playbook, which runs the installer of the clone:

```bash
./update_box.sh
```

Prerequisite: [uv](https://docs.astral.sh/uv/). The project uses Python 3.13 (package: ≥ 3.11).

## 6. Licence

The code of this repository is under the MIT licence ([`LICENSE.txt`](https://github.com/tgd1975/tinyjukebox/blob/master/LICENSE.txt)); for the circuit see
[`hardware/README.md`](https://github.com/tgd1975/tinyjukebox/blob/master/hardware/README.md).

**The files of a release contain software of others** that is not in the repository: the slot archive for the boxes
(`tinyjukebox-box-…`), the package of the library for the NAS (`tinyjukebox-library-…`), which brings a slot and the
app along, and the app for phones (`tinyjukebox-app-…`).

| Software | In | Licence |
| --- | --- | --- |
| Python ([python-build-standalone](https://github.com/astral-sh/python-build-standalone)) | slot | PSF-2.0; the libraries built into it have their own licences |
| mutagen | slot, package | **GPL-2.0-or-later** |
| jsonschema with attrs, referencing, rpds-py and jsonschema-specifications; PyYAML | slot, package | MIT |
| tantamount, asyncscheduler (our own) | slot, package | MIT |
| segno | slot, package | BSD-3-Clause |
| Kotlin standard library, kotlinx.serialization; AndroidX (core, activity, webkit and what they need); Media3 (ExoPlayer, session) with Guava; ZXing and ZXing Android Embedded; Spotify App Remote SDK (fetched from Spotify's release on GitHub, checked by its checksum) with Gson | app | Apache-2.0 |
| typing-extensions | package | PSF-2.0 |
| dbus-fast | slot | MIT |
| rpi-lgpio | slot | BSD-3-Clause |
| lgpio | slot | Unlicense (public domain) |
| pyalsaaudio | slot | PSF-2.0 |
| bcm2835, linked into `rfid-reader` | slot | **GPL-3.0** |
| RPi-MFRC522, compiled into `rfid-reader` | slot | Unlicense (public domain) |

Python and the Python packages of others bring their licence texts along (`python/lib/python3.13/LICENSE.txt`, the
folders `*.dist-info/licenses/`); those of bcm2835 and RPi-MFRC522 are in the slot next to `rfid-reader`
(`bin/rfid-reader-licenses/`); the app shows the Apache licence in its settings. `app/gradle/libs.versions.toml` names
the libraries of the app and their versions. The sources: `uv.lock` names the Python packages and their versions,
`deploy/ansible/group_vars/all/main.yaml` the versions of bcm2835 and RPi-MFRC522 and where they come from,
`cpp/rfid-reader/` is the source of `rfid-reader` itself. This is a description, not a legal opinion.

## 7. Repository

| Folder | Content |
| --- | --- |
| `src/tinyjukebox/`, `tests/` | the application and its tests |
| `app/` | the app for Android phones (Kotlin, Gradle): a phone as a box, and the page of the library ([docs/developer/app.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/app.md)) |
| `cpp/rfid-reader/` | the RFID reader program of the box (C++), built with the slot of a release; `licenses/` holds the licence texts of the two libraries it is built with |
| `deploy/` | config, service units, the slot scripts of a box, the Ansible playbook that sets up the box, the package of the library for the NAS |
| `scripts/` | builds the slot, the installer, the image and the app of a release, the steps of the workflow, checks of both web pages, the documentation site (`site/`), `trust.sh` (the keys of DSM and of the library that the scripts on the PC accept) |
| `*.sh` in the root | `start_sim.sh`, `start_library.sh` (box and library on the PC), `update_box.sh` (playbook), `build_package.sh`, `fetch_release.sh`, `update_library.sh` (the package onto the NAS), `release.sh` (push, merge, install), `import_covers.sh` |
| `docs/` | documentation; `docs/hardware/` holds the key data of the components and the links to their data sheets, `docs/images/` the photos of the box and the logo |
| `hardware/` | the circuit of the box and printed parts |

The repository holds everything that belongs to the box and changes together. It has one version number
(`pyproject.toml`), set as git tag `vX.Y.Z`. What is deliberately not in the repository is listed in
[development.md](https://github.com/tgd1975/tinyjukebox/blob/master/docs/developer/development.md), section 3.
