From 77fbe7420596dfdfb2384f929ccbbd328fcd754a Mon Sep 17 00:00:00 2001
From: Johan <johan@koke.email>
Date: Tue, 15 Sep 2026 11:32:13 +0100
Subject: [PATCH] Add README

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LYvjTEDeh9T6NqBDdCALMq
---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bf6c5b7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# dotjuice.thesinging.bible
+
+An [Omarchy](https://omarchy.org/) shell plugin that turns the top bar into a
+media player/streamer for [TheSinging.Bible](https://thesinging.bible) —
+the Bible sung in your choice of language, voice, and musical style.
+
+## What it does
+
+- Bar pill showing play/pause and the current track (e.g. "Genesis 1")
+- Click it for a popup player with full transport controls: loop, prev
+  chapter, rewind 10s, play/pause, forward 10s, next chapter, shuffle, and a
+  seek bar with elapsed/total time
+- The same selectors as the website, in the same order: **Book**, **Chapter**,
+  **Style**, **Voice**, **Language**
+- Remembers your last selection between restarts
+- Streams the site's public audio files directly (no login/API key needed)
+
+## Requirements
+
+- [Omarchy](https://omarchy.org/)
+- `mpv` (used under the hood for streaming/playback control over its JSON IPC
+  socket)
+
+## Install
+
+Copy (or clone) this directory to:
+
+```
+~/.config/omarchy/plugins/dotjuice.thesinging.bible/
+```
+
+The shell picks up plugins under `~/.config/omarchy/plugins/` automatically.
+Add the widget to your bar with:
+
+```bash
+omarchy bar put dotjuice.thesinging.bible --section right
+```
+
+(or `--section left` / `--section center`, wherever you'd like it). If it
+doesn't show up, force a rescan:
+
+```bash
+omarchy-shell shell rescanPlugins
+```
+
+## How it works
+
+- `Model.js` fetches `manifest.json` from thesinging.bible for the current
+  list of books, styles, voices, and languages, and builds the audio URL for
+  a given selection (`https://audio.thesinging.bible/<translation>/<voice>/<age>/<style>/<book>/<chapter>.mp3`).
+  Age (adult/child) isn't a user-facing selector — it's derived automatically
+  per selection, same as the website.
+- `BarWidget.qml` launches a background `mpv --idle` process per session and
+  drives it over its local JSON IPC socket for loading, play/pause, seeking,
+  and chapter navigation.
+- Last selection is persisted to
+  `~/.local/state/omarchy/plugins/dotjuice.thesinging.bible/state.json`.
+
+## Credit
+
+All audio and Bible content is © [TheSinging.Bible](https://thesinging.bible).
+This plugin is just a native desktop player pointed at their public API/audio
+— it doesn't ship or host any Bible content itself.