From c1a76480762b9265da913187129ee3e31d394c13 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 10:09:18 -0500 Subject: [PATCH] docs(user): reader audio section + kobo guide refresh to platform reality MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reader-guide.md gains the audiobook/episode player section (seek, prev/next episode, Bookmarks panel, Chapters list, Player settings with autoplay/speed/resume-rewind overrides, Shortcuts dialog) — the player existed with zero user docs. kobo-setup.md drops the stale 'not available yet, actively being developed' framing: the server side of native Kobo sync is implemented and documented (sync/initialization endpoints, bookmark + markup sync, shelf mappings, KEPUB sidecar config), so the guide now states exactly that, keeps stock-firmware rollout as the honest remaining piece, and keeps KOReader as the supported today-path. ui-controls.md: Player settings / Shortcuts & interactions / Chapters / Bookmarks entries (templ-entity fragments for ampersand labels). --- docs/developer/ui-controls.md | 21 ++++++++++++++++ docs/user/devices/kobo-setup.md | 43 +++++++++++++++++++-------------- docs/user/reader-guide.md | 25 ++++++++++++++++++- 3 files changed, 70 insertions(+), 19 deletions(-) diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index 30979624..89643e53 100644 --- a/docs/developer/ui-controls.md +++ b/docs/developer/ui-controls.md @@ -68,6 +68,27 @@ note: templ source stores the ampersand entity; the rendered label reads "Add & label: Download all episodes now where: Add Podcast Feed panel does: Grabs the feed's back catalog immediately on subscribe. + +label: Player settings +where: audio player → settings control +does: Opens the per-player preferences — Autoplay on open, Default playback speed, Resume rewind. +also: title="Settings" + +label: Shortcuts & interactions +where: audio player → the ? control +does: Lists every keyboard shortcut the player supports. +also: Shortcuts & interactions +note: templ source stores the ampersand entity + +label: Chapters +where: audio player → chapter-list control +does: Opens the chapter list and shows the current chapter position. +note: title attribute on the control + +label: Bookmarks +where: audio player → bookmarks control +does: Opens your markers for this title; tap one to jump back. +note: title attribute on the control ``` ## Collections diff --git a/docs/user/devices/kobo-setup.md b/docs/user/devices/kobo-setup.md index 56f945e9..411adcfc 100644 --- a/docs/user/devices/kobo-setup.md +++ b/docs/user/devices/kobo-setup.md @@ -1,34 +1,41 @@ # Kobo Device Setup Guide -> ## 🚧 Coming Soon -> -> Native Kobo sync is not available yet. It is actively being developed and this guide will be filled in as the feature lands. +There are two ways to use a Kobo with Bookhoard, and they can be chosen +independently per device: -## Using a Kobo With Bookhoard Today +| Way | Status | What you get | +| --- | --- | --- | +| **KOReader on the Kobo** | Works today, fully | Reading position, bookmarks, highlights, notes, OPDS wireless book delivery | +| **Stock Kobo firmware (native sync)** | Server support is complete; device-side enablement is the remaining piece | Reading position and stats, bookmarks/highlights/notes, shelf mappings (your collections as Kobo shelves), automatic EPUB → KEPUB conversion, and the Kobo's own sync experience | -You don't have to wait: **KOReader runs on Kobo hardware** and syncs fully with Bookhoard today — reading position, bookmarks, highlights, and notes, plus OPDS wireless book delivery. +## Using a Kobo today -See the **[KOReader Setup Guide](koreader-setup.md)** for complete instructions. +**KOReader runs on Kobo hardware** and syncs fully with Bookhoard right +now — the [KOReader Setup Guide](koreader-setup.md) walks the whole path +(plugin install, server approval, OPDS delivery, troubleshooting). -## What's Planned for Native Kobo Sync +## About native Kobo sync -When released, native Kobo sync will let stock Kobo firmware talk directly to Bookhoard: +The server side of the native protocol is implemented and documented: the +Kobo sync and initialization endpoints, bookmark and markup (highlight and +note) sync, shelf mappings that expose your collections as Kobo shelves, +and the KEPUB sidecar configuration used for conversion. What remains is +the device-side rollout, so stock-firmware sync is not yet something to +rely on for daily use — this guide will gain a full setup walkthrough when +that lands. -- **Reading position sync** — percentages, pages, and reading statistics -- **Bookmarks, highlights, and notes** — synced with the web and other devices -- **OPDS wireless delivery** — browse and download books directly on the Kobo -- **Automatic EPUB → KEPUB conversion** — for better Kobo rendering -- **Shelf mappings** — Bookhoard collections appearing as Kobo shelves - -The server-side protocol endpoints are already implemented and under test; the feature will be announced when it's ready for real devices. +Nothing about native sync takes anything away from KOReader: the two can +coexist, and a KOReader setup keeps working either way. ## FAQ **Q: Should I buy a Kobo to use with Bookhoard today?** -A: Kobo devices work great with Bookhoard via KOReader. Native (stock firmware) sync is coming soon. +A: Yes, via KOReader — it is the supported path today and covers sync plus +wireless book delivery. -**Q: What happens to my KOReader setup when native sync arrives?** -A: Nothing — KOReader will keep working. Native sync simply adds another option for people who prefer stock Kobo firmware. +**Q: Will I have to redo anything when native sync lands?** +A: No — KOReader keeps working; native sync just adds the stock-firmware +option. ## Additional Resources diff --git a/docs/user/reader-guide.md b/docs/user/reader-guide.md index 83a3c559..00746288 100644 --- a/docs/user/reader-guide.md +++ b/docs/user/reader-guide.md @@ -2,7 +2,8 @@ Bookhoard's built-in web reader works in any modern browser — desktop or mobile — and keeps your position, highlights, bookmarks, and notes in sync -with the Android app and KOReader. +with the Android app and KOReader. Audiobooks get their own player, covered +at the end of this guide. ## Opening a Book @@ -79,3 +80,25 @@ to jump to it. Position, highlights, bookmarks, and notes sync automatically through the server (see the [Sync Guide](sync-guide.md)). Close the tab whenever you like — the reader resumes exactly where you left off on any device. + +## Listening to audiobooks and podcast episodes + +Books with audio files, and podcast episodes, open in the audio player +instead of the page reader. It is one player for both: + +- The **seek bar** is your position; drag it, or use the **previous / + next episode** controls when you are playing a sequence +- **Bookmarks** opens a panel of your markers for this title — tap one to + jump back +- **Chapters** opens the chapter list (shows "currently chapter N of M"); + audiobooks with embedded chapters and podcast shows with chapter marks + both land here +- **Player settings** holds the per-player preferences: **Autoplay on + open**, **Default playback speed**, and **Resume rewind** (a few seconds + back when you resume — the defaults come from your + [profile](profile-guide.md) and this panel overrides them per player) +- The **Shortcuts & interactions** panel (the **?** control) lists every + keyboard shortcut + +Progress, bookmarks, and your speed carry across devices through the same +sync as everything else.