feat: stream/generate audio mode toggle

Add a user-selectable playback mode stored in user_settings:
- 'stream' (default): /api/audio-stream starts playing within seconds,
  saves to MinIO concurrently — low latency
- 'generate': queue runner task, poll until full audio is ready in
  MinIO, then play via presigned URL — legacy behaviour

UI toggles in two places:
- AudioPlayer idle pill: compact '· Stream / · Generate' inline next
  to voice name and estimated duration
- ListeningMode controls row: pill alongside Auto, Announce, Sleep;
  disabled and grayed out for CF AI voices (batch-only, no streaming)

startPlayback() now branches on audioStore.audioMode for non-CF AI
voices; generate mode uses the same runner task + progress bar flow
as CF AI but without the preview clip.

PocketBase: audio_mode text field added to user_settings on
pb.libnovel.cc (live) and in pb-init-v3.sh (create block +
add_field migration line).

backend/cmd/backend/main.go

@@ -198,6 +198,7 @@ func run() error {
 			TextGen:           textGenClient,
 			BookWriter:        store,
 			AIJobStore:        store,
+			BookAdminStore:    store,
 			Log:               log,
 		},
 	)

backend/internal/backend/handlers_books_admin.go

@@ -0,0 +1,117 @@
+package backend
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/libnovel/backend/internal/storage"
+)
+
+// handleAdminArchiveBook handles PATCH /api/admin/books/{slug}/archive.
+// Soft-deletes a book by setting archived=true in PocketBase and updating the
+// Meilisearch document so it is excluded from all public search results.
+// The book data is preserved and can be restored with the unarchive endpoint.
+func (s *Server) handleAdminArchiveBook(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+	if s.deps.BookAdminStore == nil {
+		jsonError(w, http.StatusServiceUnavailable, "book admin store not configured")
+		return
+	}
+
+	if err := s.deps.BookAdminStore.ArchiveBook(r.Context(), slug); err != nil {
+		if errors.Is(err, storage.ErrNotFound) {
+			jsonError(w, http.StatusNotFound, "book not found")
+			return
+		}
+		s.deps.Log.Error("archive book failed", "slug", slug, "err", err)
+		jsonError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	// Update the Meilisearch document so the archived flag takes effect
+	// immediately in search/catalogue results.
+	if meta, ok, err := s.deps.BookReader.ReadMetadata(r.Context(), slug); err == nil && ok {
+		if upsertErr := s.deps.SearchIndex.UpsertBook(r.Context(), meta); upsertErr != nil {
+			s.deps.Log.Warn("archive book: meili upsert failed", "slug", slug, "err", upsertErr)
+		}
+	}
+
+	s.deps.Log.Info("book archived", "slug", slug)
+	writeJSON(w, http.StatusOK, map[string]string{"slug": slug, "status": "archived"})
+}
+
+// handleAdminUnarchiveBook handles PATCH /api/admin/books/{slug}/unarchive.
+// Restores a previously archived book by clearing the archived flag, making it
+// publicly visible in search and catalogue results again.
+func (s *Server) handleAdminUnarchiveBook(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+	if s.deps.BookAdminStore == nil {
+		jsonError(w, http.StatusServiceUnavailable, "book admin store not configured")
+		return
+	}
+
+	if err := s.deps.BookAdminStore.UnarchiveBook(r.Context(), slug); err != nil {
+		if errors.Is(err, storage.ErrNotFound) {
+			jsonError(w, http.StatusNotFound, "book not found")
+			return
+		}
+		s.deps.Log.Error("unarchive book failed", "slug", slug, "err", err)
+		jsonError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	// Sync the updated archived=false state back to Meilisearch.
+	if meta, ok, err := s.deps.BookReader.ReadMetadata(r.Context(), slug); err == nil && ok {
+		if upsertErr := s.deps.SearchIndex.UpsertBook(r.Context(), meta); upsertErr != nil {
+			s.deps.Log.Warn("unarchive book: meili upsert failed", "slug", slug, "err", upsertErr)
+		}
+	}
+
+	s.deps.Log.Info("book unarchived", "slug", slug)
+	writeJSON(w, http.StatusOK, map[string]string{"slug": slug, "status": "active"})
+}
+
+// handleAdminDeleteBook handles DELETE /api/admin/books/{slug}.
+// Permanently removes all data for a book:
+//   - PocketBase books record and all chapters_idx records
+//   - All MinIO chapter markdown objects and the cover image
+//   - Meilisearch document
+//
+// This operation is irreversible. Use the archive endpoint for soft-deletion.
+func (s *Server) handleAdminDeleteBook(w http.ResponseWriter, r *http.Request) {
+	slug := r.PathValue("slug")
+	if slug == "" {
+		jsonError(w, http.StatusBadRequest, "missing slug")
+		return
+	}
+	if s.deps.BookAdminStore == nil {
+		jsonError(w, http.StatusServiceUnavailable, "book admin store not configured")
+		return
+	}
+
+	if err := s.deps.BookAdminStore.DeleteBook(r.Context(), slug); err != nil {
+		if errors.Is(err, storage.ErrNotFound) {
+			jsonError(w, http.StatusNotFound, "book not found")
+			return
+		}
+		s.deps.Log.Error("delete book failed", "slug", slug, "err", err)
+		jsonError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	// Remove from Meilisearch — best-effort (log on failure, don't fail request).
+	if err := s.deps.SearchIndex.DeleteBook(r.Context(), slug); err != nil {
+		s.deps.Log.Warn("delete book: meili delete failed", "slug", slug, "err", err)
+	}
+
+	s.deps.Log.Info("book deleted", "slug", slug)
+	writeJSON(w, http.StatusOK, map[string]string{"slug": slug, "status": "deleted"})
+}

backend/internal/backend/server.go

@@ -91,6 +91,9 @@ type Dependencies struct {
 	// AIJobStore tracks long-running AI generation jobs in PocketBase.
 	// If nil, job persistence is disabled (jobs still run but are not recorded).
 	AIJobStore bookstore.AIJobStore
+	// BookAdminStore provides admin-only operations: archive, unarchive, hard-delete.
+	// If nil, the admin book management endpoints return 503.
+	BookAdminStore bookstore.BookAdminStore
 	// Log is the structured logger.
 	Log *slog.Logger
 }
@@ -247,6 +250,11 @@ func (s *Server) ListenAndServe(ctx context.Context) error {
 	// Admin data repair endpoints
 	mux.HandleFunc("POST /api/admin/dedup-chapters/{slug}", s.handleDedupChapters)
 
+	// Admin book management (soft-delete / hard-delete)
+	mux.HandleFunc("PATCH /api/admin/books/{slug}/archive", s.handleAdminArchiveBook)
+	mux.HandleFunc("PATCH /api/admin/books/{slug}/unarchive", s.handleAdminUnarchiveBook)
+	mux.HandleFunc("DELETE /api/admin/books/{slug}", s.handleAdminDeleteBook)
+
 	// Admin chapter split (imported books)
 	mux.HandleFunc("POST /api/admin/books/{slug}/split-chapters", s.handleAdminSplitChapters)
 

backend/internal/bookstore/bookstore.go

@@ -216,6 +216,27 @@ type BookImporter interface {
 	Import(ctx context.Context, objectKey, fileType string) ([]Chapter, error)
 }
 
+// BookAdminStore covers admin-only operations for managing books in the catalogue.
+// All methods require admin authorisation at the HTTP handler level.
+type BookAdminStore interface {
+	// ArchiveBook sets archived=true on a book record, hiding it from all
+	// public search and catalogue responses. Returns ErrNotFound when the
+	// slug does not exist.
+	ArchiveBook(ctx context.Context, slug string) error
+
+	// UnarchiveBook clears archived on a book record, making it publicly
+	// visible again. Returns ErrNotFound when the slug does not exist.
+	UnarchiveBook(ctx context.Context, slug string) error
+
+	// DeleteBook permanently removes all data for a book:
+	//   - PocketBase books record
+	//   - All PocketBase chapters_idx records
+	//   - All MinIO chapter markdown objects ({slug}/chapter-*.md)
+	//   - MinIO cover image (covers/{slug}.jpg)
+	// The caller is responsible for also deleting the Meilisearch document.
+	DeleteBook(ctx context.Context, slug string) error
+}
+
 // ImportFileStore uploads raw import files to object storage.
 // Kept separate from BookImporter so the HTTP handler can upload the file
 // without a concrete type assertion, regardless of which Producer is wired.

backend/internal/domain/domain.go

@@ -24,6 +24,9 @@ type BookMeta struct {
 	// updated in PocketBase. Populated on read; not sent on write (PocketBase
 	// manages its own updated field).
 	MetaUpdated int64 `json:"meta_updated,omitempty"`
+	// Archived is true when the book has been soft-deleted by an admin.
+	// Archived books are excluded from all public search and catalogue responses.
+	Archived bool `json:"archived,omitempty"`
 }
 
 // CatalogueEntry is a lightweight book reference returned by catalogue pages.

backend/internal/meili/client.go

@@ -32,11 +32,15 @@ type Client interface {
 	// BookExists reports whether a book with the given slug is already in the
 	// index. Used by the catalogue refresh to skip re-indexing known books.
 	BookExists(ctx context.Context, slug string) bool
+	// DeleteBook removes a book document from the search index by slug.
+	DeleteBook(ctx context.Context, slug string) error
 	// Search returns up to limit books matching query.
+	// Archived books are always excluded.
 	Search(ctx context.Context, query string, limit int) ([]domain.BookMeta, error)
 	// Catalogue queries books with optional filters, sort, and pagination.
 	// Returns books, the total hit count for pagination, and a FacetResult
 	// with available genre and status values from the index.
+	// Archived books are always excluded.
 	Catalogue(ctx context.Context, q CatalogueQuery) ([]domain.BookMeta, int64, FacetResult, error)
 }
 
@@ -99,7 +103,7 @@ func Configure(host, apiKey string) error {
 		return fmt.Errorf("meili: update searchable attributes: %w", err)
 	}
 
-	filterable := []interface{}{"status", "genres"}
+	filterable := []interface{}{"status", "genres", "archived"}
 	if _, err := idx.UpdateFilterableAttributes(&filterable); err != nil {
 		return fmt.Errorf("meili: update filterable attributes: %w", err)
 	}
@@ -128,6 +132,9 @@ type bookDoc struct {
 	// MetaUpdated is the Unix timestamp (seconds) of the last PocketBase update.
 	// Used for sort=update ("recently updated" ordering).
 	MetaUpdated int64 `json:"meta_updated"`
+	// Archived is true when the book has been soft-deleted by an admin.
+	// Used as a filter to exclude archived books from all search results.
+	Archived bool `json:"archived"`
 }
 
 func toDoc(b domain.BookMeta) bookDoc {
@@ -144,6 +151,7 @@ func toDoc(b domain.BookMeta) bookDoc {
 		Rank:          b.Ranking,
 		Rating:        b.Rating,
 		MetaUpdated:   b.MetaUpdated,
+		Archived:      b.Archived,
 	}
 }
 
@@ -161,6 +169,7 @@ func fromDoc(d bookDoc) domain.BookMeta {
 		Ranking:       d.Rank,
 		Rating:        d.Rating,
 		MetaUpdated:   d.MetaUpdated,
+		Archived:      d.Archived,
 	}
 }
 
@@ -184,13 +193,24 @@ func (c *MeiliClient) BookExists(_ context.Context, slug string) bool {
 	return err == nil && doc.Slug != ""
 }
 
+// DeleteBook removes a book document from the index by slug.
+// The operation is fire-and-forget (Meilisearch processes tasks asynchronously).
+func (c *MeiliClient) DeleteBook(_ context.Context, slug string) error {
+	if _, err := c.idx.DeleteDocument(slug, nil); err != nil {
+		return fmt.Errorf("meili: delete book %q: %w", slug, err)
+	}
+	return nil
+}
+
 // Search returns books matching query, up to limit results.
+// Archived books are always excluded.
 func (c *MeiliClient) Search(_ context.Context, query string, limit int) ([]domain.BookMeta, error) {
 	if limit <= 0 {
 		limit = 20
 	}
 	res, err := c.idx.Search(query, &meilisearch.SearchRequest{
-		Limit: int64(limit),
+		Limit:  int64(limit),
+		Filter: "archived = false",
 	})
 	if err != nil {
 		return nil, fmt.Errorf("meili: search %q: %w", query, err)
@@ -231,17 +251,15 @@ func (c *MeiliClient) Catalogue(_ context.Context, q CatalogueQuery) ([]domain.B
 		Facets: []string{"genres", "status"},
 	}
 
-	// Build filter
-	var filters []string
+	// Build filter — always exclude archived books
+	filters := []string{"archived = false"}
 	if q.Genre != "" && q.Genre != "all" {
 		filters = append(filters, fmt.Sprintf("genres = %q", q.Genre))
 	}
 	if q.Status != "" && q.Status != "all" {
 		filters = append(filters, fmt.Sprintf("status = %q", q.Status))
 	}
-	if len(filters) > 0 {
-		req.Filter = strings.Join(filters, " AND ")
-	}
+	req.Filter = strings.Join(filters, " AND ")
 
 	// Map UI sort tokens to Meilisearch sort expressions.
 	switch q.Sort {
@@ -318,7 +336,8 @@ func sortStrings(s []string) {
 type NoopClient struct{}
 
 func (NoopClient) UpsertBook(_ context.Context, _ domain.BookMeta) error { return nil }
-func (NoopClient) BookExists(_ context.Context, _ string) bool           { return false }
+func (NoopClient) BookExists(_ context.Context, _ string) bool            { return false }
+func (NoopClient) DeleteBook(_ context.Context, _ string) error           { return nil }
 func (NoopClient) Search(_ context.Context, _ string, _ int) ([]domain.BookMeta, error) {
 	return nil, nil
 }

backend/internal/runner/helpers.go

@@ -19,3 +19,53 @@ func stripMarkdown(src string) string {
 	src = regexp.MustCompile(`\n{3,}`).ReplaceAllString(src, "\n\n")
 	return strings.TrimSpace(src)
 }
+
+// chunkText splits text into chunks of at most maxChars characters, breaking
+// at sentence boundaries (". ", "! ", "? ", "\n") so that the TTS service
+// receives natural prose fragments rather than mid-sentence cuts.
+//
+// If a single sentence exceeds maxChars it is included as its own chunk —
+// never silently truncated.
+func chunkText(text string, maxChars int) []string {
+	if len(text) <= maxChars {
+		return []string{text}
+	}
+
+	// Sentence-boundary delimiters — we split AFTER these sequences.
+	// Order matters: longer sequences first.
+	delimiters := []string{".\n", "!\n", "?\n", ". ", "! ", "? ", "\n\n", "\n"}
+
+	var chunks []string
+	remaining := text
+
+	for len(remaining) > 0 {
+		if len(remaining) <= maxChars {
+			chunks = append(chunks, strings.TrimSpace(remaining))
+			break
+		}
+
+		// Find the last sentence boundary within the maxChars window.
+		window := remaining[:maxChars]
+		cutAt := -1
+		for _, delim := range delimiters {
+			idx := strings.LastIndex(window, delim)
+			if idx > 0 && idx+len(delim) > cutAt {
+				cutAt = idx + len(delim)
+			}
+		}
+
+		if cutAt <= 0 {
+			// No boundary found — hard-break at maxChars to avoid infinite loop.
+			cutAt = maxChars
+		}
+
+		chunk := strings.TrimSpace(remaining[:cutAt])
+		if chunk != "" {
+			chunks = append(chunks, chunk)
+		}
+		remaining = strings.TrimSpace(remaining[cutAt:])
+	}
+
+	return chunks
+}
+

backend/internal/runner/runner.go

@@ -656,7 +656,7 @@ func (r *Runner) runAudioTask(ctx context.Context, task domain.AudioTask) {
 			return
 		}
 		var genErr error
-		audioData, genErr = r.deps.Kokoro.GenerateAudio(ctx, text, task.Voice)
+		audioData, genErr = kokoroGenerateChunked(ctx, r.deps.Kokoro, text, task.Voice, log)
 		if genErr != nil {
 			fail(fmt.Sprintf("kokoro generate: %v", genErr))
 			return
@@ -685,6 +685,31 @@ func (r *Runner) runAudioTask(ctx context.Context, task domain.AudioTask) {
 	log.Info("runner: audio task finished", "key", key)
 }
 
+// kokoroGenerateChunked splits text into ~1 000-character sentence-boundary
+// chunks, calls Kokoro.GenerateAudio for each, and concatenates the raw MP3
+// bytes. This avoids EOF / timeout failures that occur when the Kokoro
+// FastAPI server receives very large inputs (e.g. a full imported PDF chapter).
+//
+// Concatenating raw MP3 frames is valid — MP3 is a frame-based format and
+// standard players handle multi-segment files correctly.
+func kokoroGenerateChunked(ctx context.Context, k kokoro.Client, text, voice string, log *slog.Logger) ([]byte, error) {
+	const chunkSize = 1000
+
+	chunks := chunkText(text, chunkSize)
+	log.Info("runner: kokoro chunked generation", "chunks", len(chunks), "total_chars", len(text))
+
+	var combined []byte
+	for i, chunk := range chunks {
+		data, err := k.GenerateAudio(ctx, chunk, voice)
+		if err != nil {
+			return nil, fmt.Errorf("chunk %d/%d: %w", i+1, len(chunks), err)
+		}
+		combined = append(combined, data...)
+		log.Info("runner: kokoro chunk done", "chunk", i+1, "of", len(chunks), "bytes", len(data))
+	}
+	return combined, nil
+}
+
 // runImportTask executes one PDF/EPUB import task.
 // Preferred path: when task.ChaptersKey is set, it reads pre-parsed chapters
 // JSON from MinIO (written by the backend at upload time) and ingests them.

backend/internal/storage/store.go

@@ -55,6 +55,7 @@ var _ bookstore.CoverStore = (*Store)(nil)
 var _ bookstore.TranslationStore = (*Store)(nil)
 var _ bookstore.AIJobStore = (*Store)(nil)
 var _ bookstore.ChapterImageStore = (*Store)(nil)
+var _ bookstore.BookAdminStore = (*Store)(nil)
 var _ taskqueue.Producer = (*Store)(nil)
 var _ taskqueue.Consumer = (*Store)(nil)
 var _ taskqueue.Reader = (*Store)(nil)
@@ -226,6 +227,7 @@ type pbBook struct {
 	Ranking       int      `json:"ranking"`
 	Rating        float64  `json:"rating"`
 	Updated       string   `json:"updated"`
+	Archived      bool     `json:"archived"`
 }
 
 func (b pbBook) toDomain() domain.BookMeta {
@@ -246,6 +248,7 @@ func (b pbBook) toDomain() domain.BookMeta {
 		Ranking:       b.Ranking,
 		Rating:        b.Rating,
 		MetaUpdated:   metaUpdated,
+		Archived:      b.Archived,
 	}
 }
 
@@ -275,7 +278,7 @@ func (s *Store) ReadMetadata(ctx context.Context, slug string) (domain.BookMeta,
 }
 
 func (s *Store) ListBooks(ctx context.Context) ([]domain.BookMeta, error) {
-	items, err := s.pb.listAll(ctx, "books", "", "title")
+	items, err := s.pb.listAll(ctx, "books", "archived=false", "title")
 	if err != nil {
 		return nil, err
 	}
@@ -376,6 +379,84 @@ func (s *Store) ReindexChapters(ctx context.Context, slug string) (int, error) {
 	return count, nil
 }
 
+// ── BookAdminStore ────────────────────────────────────────────────────────────
+
+// ArchiveBook sets archived=true on the book record for slug.
+func (s *Store) ArchiveBook(ctx context.Context, slug string) error {
+	book, err := s.getBookBySlug(ctx, slug)
+	if err == ErrNotFound {
+		return ErrNotFound
+	}
+	if err != nil {
+		return fmt.Errorf("ArchiveBook: %w", err)
+	}
+	return s.pb.patch(ctx, fmt.Sprintf("/api/collections/books/records/%s", book.ID),
+		map[string]any{"archived": true})
+}
+
+// UnarchiveBook clears archived on the book record for slug.
+func (s *Store) UnarchiveBook(ctx context.Context, slug string) error {
+	book, err := s.getBookBySlug(ctx, slug)
+	if err == ErrNotFound {
+		return ErrNotFound
+	}
+	if err != nil {
+		return fmt.Errorf("UnarchiveBook: %w", err)
+	}
+	return s.pb.patch(ctx, fmt.Sprintf("/api/collections/books/records/%s", book.ID),
+		map[string]any{"archived": false})
+}
+
+// DeleteBook permanently removes all data for a book:
+//   - PocketBase books record
+//   - All PocketBase chapters_idx records for the slug
+//   - All MinIO chapter markdown objects ({slug}/chapter-*.md)
+//   - MinIO cover image (covers/{slug}.jpg)
+func (s *Store) DeleteBook(ctx context.Context, slug string) error {
+	// 1. Fetch the book record to get its PocketBase ID.
+	book, err := s.getBookBySlug(ctx, slug)
+	if err == ErrNotFound {
+		return ErrNotFound
+	}
+	if err != nil {
+		return fmt.Errorf("DeleteBook: fetch: %w", err)
+	}
+
+	// 2. Delete all chapters_idx records.
+	filter := fmt.Sprintf(`slug=%q`, slug)
+	items, err := s.pb.listAll(ctx, "chapters_idx", filter, "")
+	if err != nil && err != ErrNotFound {
+		return fmt.Errorf("DeleteBook: list chapters_idx: %w", err)
+	}
+	for _, raw := range items {
+		var rec struct {
+			ID string `json:"id"`
+		}
+		if json.Unmarshal(raw, &rec) == nil && rec.ID != "" {
+			if delErr := s.pb.delete(ctx, fmt.Sprintf("/api/collections/chapters_idx/records/%s", rec.ID)); delErr != nil {
+				s.log.Warn("DeleteBook: delete chapters_idx record failed", "slug", slug, "id", rec.ID, "err", delErr)
+			}
+		}
+	}
+
+	// 3. Delete MinIO chapter objects.
+	if err := s.mc.deleteObjects(ctx, s.mc.bucketChapters, slug+"/"); err != nil {
+		s.log.Warn("DeleteBook: delete chapter objects failed", "slug", slug, "err", err)
+	}
+
+	// 4. Delete MinIO cover image.
+	if err := s.mc.deleteObjects(ctx, s.mc.bucketBrowse, CoverObjectKey(slug)); err != nil {
+		s.log.Warn("DeleteBook: delete cover failed", "slug", slug, "err", err)
+	}
+
+	// 5. Delete the PocketBase books record.
+	if err := s.pb.delete(ctx, fmt.Sprintf("/api/collections/books/records/%s", book.ID)); err != nil {
+		return fmt.Errorf("DeleteBook: delete books record: %w", err)
+	}
+
+	return nil
+}
+
 // ── RankingStore ──────────────────────────────────────────────────────────────
 
 func (s *Store) WriteRankingItem(ctx context.Context, item domain.RankingItem) error {

scripts/pb-init-v3.sh

@@ -144,7 +144,8 @@ create "books" '{
     {"name":"total_chapters","type":"number"},
     {"name":"source_url",    "type":"text"},
     {"name":"ranking",       "type":"number"},
-    {"name":"meta_updated",  "type":"text"}
+    {"name":"meta_updated",  "type":"text"},
+    {"name":"archived",      "type":"bool"}
   ]}'
 
 create "chapters_idx" '{
@@ -255,6 +256,7 @@ create "user_settings" '{
     {"name":"font_family",     "type":"text"},
     {"name":"font_size",       "type":"number"},
     {"name":"announce_chapter","type":"bool"},
+    {"name":"audio_mode",      "type":"text"},
     {"name":"updated",         "type":"text"}
   ]}'
 
@@ -389,6 +391,8 @@ add_field "user_settings"  "locale"                 "text"
 add_field "user_settings"  "font_family"            "text"
 add_field "user_settings"  "font_size"              "number"
 add_field "user_settings"  "announce_chapter"       "bool"
+add_field "user_settings"  "audio_mode"             "text"
+add_field "books"          "archived"               "bool"
 
 # ── 6. Indexes ────────────────────────────────────────────────────────────────
 add_index "chapters_idx" "idx_chapters_idx_slug_number" \

ui/src/lib/audio.svelte.ts

@@ -36,6 +36,14 @@ import type { Voice } from '$lib/types';
 
 export type AudioStatus = 'idle' | 'loading' | 'generating' | 'ready' | 'error';
 export type NextStatus = 'none' | 'prefetching' | 'prefetched' | 'failed';
+/**
+ * 'stream'   – Use /api/audio-stream: audio starts playing within seconds,
+ *              stream is saved to MinIO concurrently. No runner task needed.
+ * 'generate' – Legacy mode: queue a runner task, poll until done, then play
+ *              from the presigned MinIO URL. Needed for CF AI voices which
+ *              do not support native streaming.
+ */
+export type AudioMode = 'stream' | 'generate';
 
 class AudioStore {
 	// ── What is loaded ──────────────────────────────────────────────────────
@@ -46,6 +54,13 @@ class AudioStore {
 	voice = $state('af_bella');
 	speed = $state(1.0);
 
+	/**
+	 * Playback mode:
+	 * 'stream'   – pipe from /api/audio-stream (low latency, saves concurrently)
+	 * 'generate' – queue runner task, poll, then play presigned URL (CF AI / legacy)
+	 */
+	audioMode = $state<AudioMode>('stream');
+
 	/** Cover image URL for the currently loaded book. */
 	cover = $state('');
 

ui/src/lib/components/AudioPlayer.svelte

@@ -613,41 +613,95 @@
 				return;
 			}
 
-			// Slow path: audio not yet in MinIO.
-			//
-			// For Kokoro / PocketTTS: always use the streaming endpoint so audio
-			// starts playing within seconds. The stream handler checks MinIO first
-			// (fast redirect if already cached) and otherwise generates + uploads
-			// concurrently. Even if the async runner is already working on this
-			// chapter, the stream will redirect to MinIO the moment the runner
-			// finishes — no harmful double-generation occurs because the backend
-			// deduplications via AudioExists on the next request.
-			if (!voice.startsWith('cfai:')) {
-				// PocketTTS outputs raw WAV — skip the ffmpeg transcode entirely.
-				// WAV (PCM) is natively supported on all platforms including iOS Safari.
-				// Kokoro and CF AI output MP3 natively, so keep mp3 for those.
-				const isPocketTTS = voices.some((v) => v.id === voice && v.engine === 'pocket-tts');
-				const format = isPocketTTS ? 'wav' : 'mp3';
-				const qs = new URLSearchParams({ voice, format });
-				const streamUrl = `/api/audio-stream/${slug}/${chapter}?${qs}`;
-				// HEAD probe: check paywall without triggering generation.
-				const headRes = await fetch(streamUrl, { method: 'HEAD' }).catch(() => null);
-				if (headRes?.status === 402) {
+		// Slow path: audio not yet in MinIO.
+		//
+		// For Kokoro / PocketTTS in 'stream' mode: use the streaming endpoint so
+		// audio starts playing within seconds. The stream handler checks MinIO
+		// first (fast redirect if already cached) and otherwise generates +
+		// uploads concurrently.
+		//
+		// In 'generate' mode (user preference): queue a runner task and poll,
+		// same as CF AI — audio plays only after the full file is ready in MinIO.
+		if (!voice.startsWith('cfai:') && audioStore.audioMode === 'stream') {
+			// PocketTTS outputs raw WAV — skip the ffmpeg transcode entirely.
+			// WAV (PCM) is natively supported on all platforms including iOS Safari.
+			// Kokoro and CF AI output MP3 natively, so keep mp3 for those.
+			const isPocketTTS = voices.some((v) => v.id === voice && v.engine === 'pocket-tts');
+			const format = isPocketTTS ? 'wav' : 'mp3';
+			const qs = new URLSearchParams({ voice, format });
+			const streamUrl = `/api/audio-stream/${slug}/${chapter}?${qs}`;
+			// HEAD probe: check paywall without triggering generation.
+			const headRes = await fetch(streamUrl, { method: 'HEAD' }).catch(() => null);
+			if (headRes?.status === 402) {
+				audioStore.status = 'idle';
+				onProRequired?.();
+				return;
+			}
+			audioStore.audioUrl = streamUrl;
+			audioStore.status = 'ready';
+			maybeStartPrefetch();
+			return;
+		}
+
+		// Non-CF AI voices in 'generate' mode: queue runner task, show progress,
+		// wait for full audio in MinIO before playing (same as CF AI but no preview).
+		if (!voice.startsWith('cfai:')) {
+			audioStore.status = 'generating';
+			audioStore.isPreview = false;
+			startProgress();
+
+			if (!presignResult.enqueued) {
+				const res = await fetch(`/api/audio/${slug}/${chapter}`, {
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					body: JSON.stringify({ voice })
+				});
+
+				if (res.status === 402) {
 					audioStore.status = 'idle';
+					stopProgress();
 					onProRequired?.();
 					return;
 				}
-				audioStore.audioUrl = streamUrl;
-				audioStore.status = 'ready';
-				maybeStartPrefetch();
-				return;
+
+				if (!res.ok) throw new Error(`Generation failed: HTTP ${res.status}`);
+
+				if (res.status === 200) {
+					await res.body?.cancel();
+					await finishProgress();
+					const doneUrl = await tryPresign(slug, chapter, voice);
+					if (!doneUrl.ready) throw new Error('Audio generated but presign returned 404');
+					audioStore.audioUrl = doneUrl.url;
+					audioStore.status = 'ready';
+					restoreSavedAudioTime();
+					maybeStartPrefetch();
+					return;
+				}
+				// 202 — runner task enqueued, fall through to poll.
 			}
 
-			// CF AI voices: use preview/swap strategy.
-			// 1. Fetch a short ~1-2 min preview clip from the first text chunk
-			//    so playback starts immediately — no more waiting behind a spinner.
-			// 2. Meanwhile keep polling the full audio job; when it finishes,
-			//    swap the <audio> src to the full URL preserving currentTime.
+			const final = await pollAudioStatus(slug, chapter, voice);
+			if (final.status === 'failed') {
+				throw new Error(
+					`Generation failed: ${(final as { error?: string }).error ?? 'unknown error'}`
+				);
+			}
+
+			await finishProgress();
+			const doneUrl = await tryPresign(slug, chapter, voice);
+			if (!doneUrl.ready) throw new Error('Audio generated but presign returned 404');
+			audioStore.audioUrl = doneUrl.url;
+			audioStore.status = 'ready';
+			restoreSavedAudioTime();
+			maybeStartPrefetch();
+			return;
+		}
+
+		// CF AI voices: use preview/swap strategy.
+		// 1. Fetch a short ~1-2 min preview clip from the first text chunk
+		//    so playback starts immediately — no more waiting behind a spinner.
+		// 2. Meanwhile keep polling the full audio job; when it finishes,
+		//    swap the <audio> src to the full URL preserving currentTime.
 			audioStore.status = 'generating';
 			audioStore.isPreview = false;
 			startProgress();
@@ -1019,6 +1073,33 @@
 					{#if voices.length > 0}<span class="text-(--color-border) text-xs leading-none">·</span>{/if}
 					<span class="text-xs text-(--color-muted) leading-none tabular-nums">~{estimatedMinutes} min</span>
 				{/if}
+				<!-- Stream / Generate mode toggle -->
+				{#if !audioStore.voice.startsWith('cfai:')}
+					<span class="text-(--color-border) text-xs leading-none">·</span>
+					<button
+						type="button"
+						onclick={() => { audioStore.audioMode = audioStore.audioMode === 'stream' ? 'generate' : 'stream'; }}
+						class={cn(
+							'flex items-center gap-0.5 text-xs leading-none transition-colors',
+							audioStore.audioMode === 'stream'
+								? 'text-(--color-brand)'
+								: 'text-(--color-muted) hover:text-(--color-text)'
+						)}
+						title={audioStore.audioMode === 'stream' ? 'Stream mode — click to switch to generate' : 'Generate mode — click to switch to stream'}
+					>
+						{#if audioStore.audioMode === 'stream'}
+							<svg class="w-3 h-3 flex-shrink-0" fill="currentColor" viewBox="0 0 24 24">
+								<path d="M8 5v14l11-7z"/>
+							</svg>
+							Stream
+						{:else}
+							<svg class="w-3 h-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+								<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"/>
+							</svg>
+							Generate
+						{/if}
+					</button>
+				{/if}
 			</div>
 		</div>
 

ui/src/lib/components/ListeningMode.svelte

@@ -664,24 +664,57 @@
 				{/if}
 			</button>
 
-			<!-- Announce chapter pill (only meaningful when auto-next is on) -->
-			<button
-				type="button"
-				onclick={() => (audioStore.announceChapter = !audioStore.announceChapter)}
-				class={cn(
-					'flex items-center gap-1.5 px-3 py-1.5 rounded-full text-xs font-semibold border transition-colors',
-					audioStore.announceChapter
+		<!-- Announce chapter pill (only meaningful when auto-next is on) -->
+		<button
+			type="button"
+			onclick={() => (audioStore.announceChapter = !audioStore.announceChapter)}
+			class={cn(
+				'flex items-center gap-1.5 px-3 py-1.5 rounded-full text-xs font-semibold border transition-colors',
+				audioStore.announceChapter
+					? 'border-(--color-brand) bg-(--color-brand)/15 text-(--color-brand)'
+					: 'border-(--color-border) bg-(--color-surface-2) text-(--color-muted) hover:text-(--color-text)'
+			)}
+			aria-pressed={audioStore.announceChapter}
+			title={audioStore.announceChapter ? 'Chapter announcing on' : 'Chapter announcing off'}
+		>
+			<svg class="w-3.5 h-3.5" fill="currentColor" viewBox="0 0 24 24">
+				<path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02z"/>
+			</svg>
+			Announce
+		</button>
+
+		<!-- Stream / Generate mode toggle -->
+		<!-- CF AI voices are batch-only and always use generate mode regardless of this setting -->
+		<button
+			type="button"
+			onclick={() => {
+				if (!audioStore.voice.startsWith('cfai:')) {
+					audioStore.audioMode = audioStore.audioMode === 'stream' ? 'generate' : 'stream';
+				}
+			}}
+			disabled={audioStore.voice.startsWith('cfai:')}
+			class={cn(
+				'flex items-center gap-1.5 px-3 py-1.5 rounded-full text-xs font-semibold border transition-colors',
+				audioStore.voice.startsWith('cfai:')
+					? 'border-(--color-border) bg-(--color-surface-2) text-(--color-border) cursor-not-allowed opacity-50'
+					: audioStore.audioMode === 'stream'
 						? 'border-(--color-brand) bg-(--color-brand)/15 text-(--color-brand)'
 						: 'border-(--color-border) bg-(--color-surface-2) text-(--color-muted) hover:text-(--color-text)'
-				)}
-				aria-pressed={audioStore.announceChapter}
-				title={audioStore.announceChapter ? 'Chapter announcing on' : 'Chapter announcing off'}
-			>
+			)}
+			aria-pressed={audioStore.audioMode === 'stream'}
+			title={audioStore.voice.startsWith('cfai:') ? 'CF AI voices always use generate mode' : audioStore.audioMode === 'stream' ? 'Stream mode — audio starts instantly' : 'Generate mode — wait for full audio before playing'}
+		>
+			{#if audioStore.audioMode === 'stream' && !audioStore.voice.startsWith('cfai:')}
 				<svg class="w-3.5 h-3.5" fill="currentColor" viewBox="0 0 24 24">
-					<path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02z"/>
+					<path d="M8 5v14l11-7z"/>
 				</svg>
-				Announce
-			</button>
+			{:else}
+				<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+					<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"/>
+				</svg>
+			{/if}
+			{audioStore.audioMode === 'stream' && !audioStore.voice.startsWith('cfai:') ? 'Stream' : 'Generate'}
+		</button>
 
 			<!-- Sleep timer pill -->
 			<button

ui/src/lib/server/pocketbase.ts

@@ -76,6 +76,7 @@ export interface PBUserSettings {
 	font_family?: string;
 	font_size?: number;
 	announce_chapter?: boolean;
+	audio_mode?: string;
 	updated?: string;
 }
 
@@ -1013,7 +1014,7 @@ export async function getSettings(
 
 export async function saveSettings(
 	sessionId: string,
-	settings: { autoNext: boolean; voice: string; speed: number; theme?: string; locale?: string; fontFamily?: string; fontSize?: number; announceChapter?: boolean },
+	settings: { autoNext: boolean; voice: string; speed: number; theme?: string; locale?: string; fontFamily?: string; fontSize?: number; announceChapter?: boolean; audioMode?: string },
 	userId?: string
 ): Promise<void> {
 	const existing = await listOne<PBUserSettings & { id: string }>(
@@ -1033,6 +1034,7 @@ export async function saveSettings(
 	if (settings.fontFamily !== undefined) payload.font_family = settings.fontFamily;
 	if (settings.fontSize !== undefined) payload.font_size = settings.fontSize;
 	if (settings.announceChapter !== undefined) payload.announce_chapter = settings.announceChapter;
+	if (settings.audioMode !== undefined) payload.audio_mode = settings.audioMode;
 	if (userId) payload.user_id = userId;
 
 	if (existing) {

ui/src/routes/+layout.server.ts

@@ -17,7 +17,7 @@ export const load: LayoutServerLoad = async ({ locals, url, cookies }) => {
 		redirect(302, `/login`);
 	}
 
-	let settings = { autoNext: false, voice: 'af_bella', speed: 1.0, theme: 'amber', locale: 'en', fontFamily: 'system', fontSize: 1.0, announceChapter: false };
+	let settings = { autoNext: false, voice: 'af_bella', speed: 1.0, theme: 'amber', locale: 'en', fontFamily: 'system', fontSize: 1.0, announceChapter: false, audioMode: 'stream' };
 	try {
 		const row = await getSettings(locals.sessionId, locals.user?.id);
 		if (row) {
@@ -29,7 +29,8 @@ export const load: LayoutServerLoad = async ({ locals, url, cookies }) => {
 				locale: row.locale ?? 'en',
 				fontFamily: row.font_family ?? 'system',
 				fontSize: row.font_size || 1.0,
-				announceChapter: row.announce_chapter ?? false
+				announceChapter: row.announce_chapter ?? false,
+				audioMode: row.audio_mode ?? 'stream'
 			};
 		}
 	} catch (e) {

ui/src/routes/+layout.svelte

@@ -157,6 +157,7 @@
 				audioStore.voice = data.settings.voice;
 				audioStore.speed = data.settings.speed;
 				audioStore.announceChapter = data.settings.announceChapter ?? false;
+				audioStore.audioMode = (data.settings.audioMode === 'generate' ? 'generate' : 'stream');
 			}
 			// Always sync theme + font (profile page calls invalidateAll after saving)
 			currentTheme = data.settings.theme ?? 'amber';
@@ -179,6 +180,7 @@
 		const fontFamily = currentFontFamily;
 		const fontSize = currentFontSize;
 		const announceChapter = audioStore.announceChapter;
+		const audioMode = audioStore.audioMode;
 
 		// Skip saving until settings have been applied from the server AND
 		// at least one user-driven change has occurred after that.
@@ -189,7 +191,7 @@
 			fetch('/api/settings', {
 				method: 'PUT',
 				headers: { 'Content-Type': 'application/json' },
-				body: JSON.stringify({ autoNext, voice, speed, theme, fontFamily, fontSize, announceChapter })
+				body: JSON.stringify({ autoNext, voice, speed, theme, fontFamily, fontSize, announceChapter, audioMode })
 			}).catch(() => {});
 		}, 800) as unknown as number;
 	});

ui/src/routes/api/settings/+server.ts

@@ -5,7 +5,7 @@ import { log } from '$lib/server/logger';
 
 /**
  * GET /api/settings
- * Returns the current user's settings (auto_next, voice, speed, theme, locale, fontFamily, fontSize, announceChapter).
+ * Returns the current user's settings (auto_next, voice, speed, theme, locale, fontFamily, fontSize, announceChapter, audioMode).
  * Returns defaults if no settings record exists yet.
  */
 export const GET: RequestHandler = async ({ locals }) => {
@@ -19,7 +19,8 @@ export const GET: RequestHandler = async ({ locals }) => {
 			locale: settings?.locale ?? 'en',
 			fontFamily: settings?.font_family ?? 'system',
 			fontSize: settings?.font_size || 1.0,
-			announceChapter: settings?.announce_chapter ?? false
+			announceChapter: settings?.announce_chapter ?? false,
+			audioMode: settings?.audio_mode ?? 'stream'
 		});
 	} catch (e) {
 		log.error('settings', 'GET failed', { err: String(e) });
@@ -29,7 +30,7 @@ export const GET: RequestHandler = async ({ locals }) => {
 
 /**
  * PUT /api/settings
- * Body: { autoNext: boolean, voice: string, speed: number, theme?: string, locale?: string, fontFamily?: string, fontSize?: number, announceChapter?: boolean }
+ * Body: { autoNext: boolean, voice: string, speed: number, theme?: string, locale?: string, fontFamily?: string, fontSize?: number, announceChapter?: boolean, audioMode?: string }
  * Saves user preferences.
  */
 export const PUT: RequestHandler = async ({ request, locals }) => {
@@ -73,6 +74,12 @@ export const PUT: RequestHandler = async ({ request, locals }) => {
 		error(400, 'Invalid announceChapter — must be boolean');
 	}
 
+	// audioMode is optional — if provided it must be a known value
+	const validAudioModes = ['stream', 'generate'];
+	if (body.audioMode !== undefined && !validAudioModes.includes(body.audioMode)) {
+		error(400, `Invalid audioMode — must be one of: ${validAudioModes.join(', ')}`);
+	}
+
 	try {
 		await saveSettings(locals.sessionId, body, locals.user?.id);
 	} catch (e) {