sleepywaves/README.md

# Sleepywaves

A RFID powered musick/audiobook player with configurable tracklists and playing modes.

Place a tag onto the reader to start playing. Remove it to stop, or configure a timeout to stop automatically.


## Prerequisites / Recommended Setup

- Raspberry Pi (any with audio and SPI. 3A+ works fine)
- MFRC522 RFID reader module
- storage medium, e.g. USB stick. Works with SD if nothing else is available.
- dietpi with the following packages installed:
  - mpd - audio player
  - python3
    - pip3 install poetry
  - (mympd) - optional web control UI
  - (samba server) - optional file share server to easily copy new tracks
- enable SPI in dietpi-config


## Installation
Sleepywaves uses `poetry` to prepare the python environment. Install it with:

- Clone/download the repository
- Run `poetry install` to create a venv with the required python packages.
- See `sleepywaves.example.service` for a reference how a systemd unit file could look like


## Running
- Run `poetry shell` or use the python path from the poetry venv directly in the command below.
- Run `python sleepywaves.py -m <MEDIA DIR>`

Alternatively, start with systemd: `systemctl enable sleepywaves.service` and `systemctl start sleepywaves.service`.


## Tag / title configuration
A new config file is created in the media directory once a new tag is scanned.
It will be named `changeme_<tag id>.json`.
Remove the `changeme_` prefix, and configure the file as you wish.

Tracks are added to the `tracks` list in the file, and the start time in a track can be configured by
adding a `"<name>":<seconds>` pair to `start_times`.

Setting a timeout other than `0` will enable the sleep timer.
The player will stop after the configured time in seconds, even if the tag is still present on the reader.

These modes are supported:

| Play mode             | Description                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| sequence              | Start with the first track (at custom start time if configured), advance through the list one-by-one                                                                           |
| random                | Select a random track from `tracks` (at custom start time if configured) each time the tag is put on the reader, or after one track finishes playing                           |
| random_sequence       | Select a random track from `tracks` (at custom start time if configured) when the tag is put on the reader. After the track finishes, advance to the next in the `tracks` list |
| random_start_sequence | Select a random starting track and time from the list of `start_times`. Advance to the next track in `tracks` after it finishes playing                                        |

Setting `resume_track` to true will save the current playing position if the tag is removed, or the timer is reached.
Playback will continue at this point when the tag is put on the reader again.

Note: if a custom `start_times` entry is present for a track, all playback will start at this time (i.e. even if the
track is next-in-line for sequence play mode).

Note: the `random_start_sequence` mode is most useful for using audiobooks with chapters broken into shorter tracks and
the sleep timer feature. If the book e.g. has tracks of ~4 minutes, but the timeout is set to 8 minutes, it will start
at one of the configured start tracks and continue playing across the track breaks, but never start at the intermediate
tracks.


### Adding tracks to a title easily
Adding tracks to the renamed file can be automated with the add_tracks.py tool.
Run it as `python add_tracks.py -m <media dir> -t <tag id> -p <file name pattern>`
A pattern of `*Hobbit*.mp3` will find `<media dir>/Hobbit/chapter1.mp3` and similar.
Using the  `-o` flag will overwrite the track list in the title config file (*USE WITH CAUTION*). If not given, tracks will be appended to the existing tracklist.