-Design Thoughts
---------------
+Introduction
+------------
-Overall playlist behaviour?
+PlayerZ is a minimal jukebox application for playing local music
+files. It is very much a work in progress personal project.
- - Need a "current playlist"
- - When a playlist finishes, go back to the all playlist.
- - Also need a "scratch playlist"
+It consists of a small suite of separate programmes which communicate
+via posix message queues for security and robustness.
-System playlists
+Some of it's features or planned features:
-* default / all:shuffle
- All tracks, shuffled. The default playlist.
+ * Support hundreds of thousands of media files
+ * Support for removable media
+ * [planned, half implemented] support for auto-scanning removeable media
+ * Simple web-based interface using embedded web server
+ * Keyboard/remote control support for navigation
+ * [work in progress] vocal menu system using espeak
+ * Audio output is via ALSA.
-* queue
- User selected tracks, in order.
+Compile
+-------
-* junk
- The junk list, for later operations
+Requirements are libeze (see links), lmdb, libasound, and ffmpeg
+libraries. Plus some system libraries like libblkid.
-* user list
- A user playlist
+Edit the last line of dbindex.h to set the lmdb location, it should
+point to a directory on a local filesystem that already exists.
-Operations on Search
+Edit the Makefile to set the location of the libraries and build with:
-* Play Now
- Adds to the play queue and switches to it it isn't started.
+$ make
-* Add to List
- Add to specified playlist.
+Running
+-------
-Operations on Coming Up
+Music must be imported before it can be played.
-* Play Now
- Jumps to track
+Start the indexer service:
-* Junk
- Add to junk list (or should it be explicit?)
+ $ ./disk-indexer start
-* Remove (user playlist, queue)
- Remove from playlist
+Scan a directory (recursively):
+
+ $ ./disk-indexer add -r all-music /data/music
+
+Or to update later:
+
+ $ ./disk-indexer update all-music
+
+Wait for it to complete.
+
+List the disks to find the disk id:
+
+ $ ./disk-util --disks
+ id: 1
+ flags: 00000001
+ uuid: all-music
+ label: system
+ mount: /data/music
+ $
+
+Create the shuffle queue:
+
+ $ ./disk-util --lists-reset
+ $ ./disk-util --shuffle 1
+
+Start the player:
+
+ $ ./music-player
+
+Start the web interface service:
+
+ $ ./http-monitor
+
+And then navigate to:
+
+ http://localhost:8000/x/
+
+Or use audio-cmd to navigate:
+
+ $ ./audio-cmd pause
+ $ ./audio-cmd play
+ $ ./audio-cmd next
+ $ ./audio-cmd prev
+ $ ./audio-cmd seek <ms>
+ $ ./audio-cmd skip <ms>
+
+The remote/keyboard monitor is somewhat hardcoded to a mele airmouse,
+but if you want to try it you can start the input monitor. It needs
+to run as a user with access to the input device, I just use root for
+development.
+
+ $ sudo ./input-monitor
+
+There is also a service designed to monitor removable media and
+auto-index media files which directly monitors kernel UDEV events.
+I'm not sure of the status of this though as it didn't turn out to be
+as useful as I thought it would. It needs to run as a disks user so
+it can mount and unmount media, or root:
+
+ $ sudo ./disk-monitor
+
+Services
+--------
+
+disk-indexer
+
+ Performs indexing and updating of indexes for media content.
+
+disk-util
+
+ Tool for interacting with the database tables.
+
+music-player
+
+ The music player, obviously.
+
+audio-cmd
+
+ Tool for sending commands to the music player.
+
+http-monitor
+
+ Simple web server which includes the player interface.
+
+input-monitor
+
+ Monitor keyboard/remote inputs. Hardcoded to mele airmouse
+ but could be modified to handle other devices such as PS4
+ controllers.
+
+disk-monitor
+
+ Monitors KOBJECT_UVENT events from the Linux kernel for
+ removable media changes, mounts/unmounts devices, and requests
+ disks be indexed.
+
+Status
+------
+
+Code level is alpha - the music indexing and playing is very robust
+but requires much more work on the playlist designs.
+
+The playerz-1 branch is the one i'm using but master has an improved
+web interface.
+
+It needs more work on the playlist design. Currently it plays from a
+single (shuffled) playlist and you can jump to a single track from a
+search. The TODO file has some ideas on how to implement better
+jukebox facilities.
+
+It should probably use ffmpeg for audio output rather than directly
+using ALSA.
+
+A lot of things are hardcoded like the keyboard to monitor, the
+database location.
+
+The lmdb file fills up it's transaction space and needs manual
+resetting from time to time, use:
+
+ $ mdb_stat -rr <path-to-db>
+
+Links
+-----
+
+* playerz <https://www.zedzone.space/software/playerz.html>
+* libeze <https://www.zedzone.space/software/libeze.html>
+* FFmpeg <http://www.ffmpeg.org/>
+
+LICENSE
+-------
+
+ Copyright (C) 2019-2023 Michael Zucchi
+
+ This program is free software: you can redistribute it and/or
+ modify it under the terms of the GNU General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see
+ <http://www.gnu.org/licenses/>.