feat(tts): add smart sentence continuation

introduce configurable smart sentence splitting with persisted state,
UI toggle, and EPUB/PDF contexts that send continuation metadata.
enhance TTS pipeline to merge cross-page sentences, manage carryover,
and trigger visual page changes during playback for smoother narration.

update README with kokoro quick-start guidance, remove the legacy
issues mapping doc, and add deterministic TTS mocks plus sample audio
for Playwright tests.

Author: richardr1126

README.md

@@ -36,9 +36,12 @@ OpenReader WebUI is a document reader with Text-to-Speech capabilities, offering
 - Recent version of Docker installed on your machine
 - A TTS API server (Kokoro-FastAPI, Orpheus-FastAPI, Deepinfra, OpenAI, etc.) running and accessible
 
+> **Note:** If you have good hardware, you can run [Kokoro-FastAPI with Docker locally](#🗣️-local-kokoro-fastapi-quick-start-cpu-or-gpu) (see below).
+
 ### 1. 🐳 Start the Docker container:
   ```bash
   docker run --name openreader-webui \
+    --restart unless-stopped \
     -p 3003:3003 \
     -v openreader_docstore:/app/docstore \
     ghcr.io/richardr1126/openreader-webui:latest
@@ -47,6 +50,7 @@ OpenReader WebUI is a document reader with Text-to-Speech capabilities, offering
   (Optionally): Set the TTS `API_BASE` URL and/or `API_KEY` to be default for all devices
   ```bash
   docker run --name openreader-webui \
+    --restart unless-stopped \
     -e API_KEY=none \
     -e API_BASE=http://host.docker.internal:8880/v1 \
     -p 3003:3003 \
@@ -72,36 +76,48 @@ docker rm openreader-webui && \
 docker pull ghcr.io/richardr1126/openreader-webui:latest
 ```
 
-### (Alternate) 🐳 Configuration with Docker Compose and Kokoro-FastAPI
+### 🗣️ Local Kokoro-FastAPI Quick-start (CPU or GPU)
 
-A complete example docker-compose file with Kokoro-FastAPI and OpenReader WebUI is available in [`docs/examples/docker-compose.yml`](docs/examples/docker-compose.yml). You can download and use it:
+You can run the Kokoro TTS API server directly with Docker. **We are not responsible for issues with Kokoro-FastAPI.** For best performance, use an NVIDIA GPU (for GPU version) or Apple Silicon (for CPU version).
 
-```bash
-# Download example docker-compose.yml
-curl --create-dirs -L -o openreader-compose/docker-compose.yml https://raw.githubusercontent.com/richardr1126/OpenReader-WebUI/main/docs/examples/docker-compose.yml
+> **Note:** When using these, set the `API_BASE` env var to `http://host.docker.internal:8880/v1` or `http://kokoro-tts:8880/v1`.
+> You can also use the example `docker-compose.yml` in `examples/docker-compose.yml` if you prefer Docker Compose.
 
-cd openreader-compose
-docker compose up -d
+**CPU Version:**
+```bash
+docker run -d \
+  --name kokoro-tts \
+  --restart unless-stopped \
+  -p 8880:8880 \
+  -e ONNX_NUM_THREADS=8 \
+  -e ONNX_INTER_OP_THREADS=4 \
+  -e ONNX_EXECUTION_MODE=parallel \
+  -e ONNX_OPTIMIZATION_LEVEL=all \
+  -e ONNX_MEMORY_PATTERN=true \
+  -e ONNX_ARENA_EXTEND_STRATEGY=kNextPowerOfTwo \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.4
 ```
 
-Or add OpenReader WebUI to your existing `docker-compose.yml`:
-```yaml
-services:
-  openreader-webui:
-    container_name: openreader-webui
-    image: ghcr.io/richardr1126/openreader-webui:latest
-    environment:
-      - API_BASE=http://host.docker.internal:8880/v1
-    ports:
-      - "3003:3003"
-    volumes:
-      - docstore:/app/docstore
-    restart: unless-stopped
-
-volumes:
-  docstore:
+**GPU Version:**
+```bash
+docker run -d \
+  --name kokoro-tts \
+  --gpus all \
+  --user 1001:1001 \
+  --restart unless-stopped \
+  -p 8880:8880 \
+  -e USE_GPU=true \
+  -e PYTHONUNBUFFERED=1 \
+  -e API_LOG_LEVEL=DEBUG \
+  ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.4
 ```
 
+> **Note:**
+> - These commands are for running the Kokoro TTS API server only. For issues or support, see the [Kokoro-FastAPI repository](https://github.com/remsky/Kokoro-FastAPI).
+> - The GPU version requires NVIDIA Docker support and works best with NVIDIA GPUs. The CPU version works best on Apple Silicon or modern x86 CPUs.
+> - Adjust environment variables as needed for your hardware and use case.
+
 ## Dev Installation
 
 ### Prerequisites

docs/issues-to-components.md

@@ -1,28 +1,17 @@
 import { defineConfig, devices } from '@playwright/test';
 
-/**
- * Read environment variables from file.
- * https://github.com/motdotla/dotenv
- */
-// import dotenv from 'dotenv';
-// import path from 'path';
-// dotenv.config({ path: path.resolve(__dirname, '.env') });
-
 /**
  * See https://playwright.dev/docs/test-configuration.
  */
 export default defineConfig({
   testDir: './tests',
   timeout: 30 * 1000,
   outputDir: './tests/results',
-  /* Run tests in files in parallel */
-  fullyParallel: true,
+  fullyParallel: false,
   /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
-  /* Retry on CI only */
   retries: process.env.CI ? 2 : 0,
-  /* Opt out of parallel tests on CI. */
-  workers: undefined,
+  workers: process.env.CI ? '100%' : '75%',
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   reporter: 'html',
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */

docs/examples/docker-compose.yml examples/docker-compose.ymldocs/examples/docker-compose.yml renamed to examples/docker-compose.yml

@@ -217,7 +217,7 @@ export async function POST(req: NextRequest) {
       console.log('TTS in-flight JOIN for key:', cacheKey.slice(0, 8));
       existing.consumers += 1;
 
-      const onAbort = (_evt: Event) => {
+      const onAbort = () => {
         existing.consumers = Math.max(0, existing.consumers - 1);
         if (existing.consumers === 0) {
           existing.controller.abort();
@@ -262,7 +262,7 @@ export async function POST(req: NextRequest) {
 
     inflightRequests.set(cacheKey, entry);
 
-    const onAbort = (_evt: Event) => {
+    const onAbort = () => {
       entry.consumers = Math.max(0, entry.consumers - 1);
       if (entry.consumers === 0) {
         entry.controller.abort();

playwright.config.ts

@@ -27,6 +27,7 @@ export function DocumentSettings({ isOpen, setIsOpen, epub, html }: {
     viewType,
     skipBlank,
     epubTheme,
+    smartSentenceSplitting,
     headerMargin,
     footerMargin,
     leftMargin,
@@ -308,6 +309,24 @@ export function DocumentSettings({ isOpen, setIsOpen, epub, html }: {
                         Automatically skip pages with no text content
                       </p>
                     </div>}
+                    {!html && (
+                      <div className="space-y-1">
+                        <label className="flex items-center space-x-2">
+                          <input
+                            type="checkbox"
+                            checked={smartSentenceSplitting}
+                            onChange={(e) => updateConfigKey('smartSentenceSplitting', e.target.checked)}
+                            className="form-checkbox h-4 w-4 text-accent rounded border-muted"
+                          />
+                          <span className="text-sm font-medium text-foreground">
+                            Smart sentence splitting
+                          </span>
+                        </label>
+                        <p className="text-sm text-muted pl-6">
+                          Merge sentences across page or section breaks for smoother TTS.
+                        </p>
+                      </div>
+                    )}
                     {epub && (
                       <div className="space-y-1">
                         <label className="flex items-center space-x-2">

src/app/api/tts/route.ts

@@ -239,4 +239,4 @@ export function PDFViewer({ zoomLevel }: PDFViewerProps) {
       </Document>
     </div>
   );
-}
+}

src/components/DocumentSettings.tsx

@@ -29,6 +29,7 @@ type ConfigValues = {
   ttsModel: string;
   ttsInstructions: string;
   savedVoices: SavedVoices;
+  smartSentenceSplitting: boolean;
 };
 
 /** Interface defining the configuration context shape and functionality */
@@ -41,6 +42,7 @@ interface ConfigContextType {
   voice: string;
   skipBlank: boolean;
   epubTheme: boolean;
+  smartSentenceSplitting: boolean;
   headerMargin: number;
   footerMargin: number;
   leftMargin: number;
@@ -73,6 +75,7 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
   const [voice, setVoice] = useState<string>('af_sarah');
   const [skipBlank, setSkipBlank] = useState<boolean>(true);
   const [epubTheme, setEpubTheme] = useState<boolean>(false);
+  const [smartSentenceSplitting, setSmartSentenceSplitting] = useState<boolean>(true);
   const [headerMargin, setHeaderMargin] = useState<number>(0.07);
   const [footerMargin, setFooterMargin] = useState<number>(0.07);
   const [leftMargin, setLeftMargin] = useState<number>(0.07);
@@ -103,6 +106,7 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
         const cachedAudioPlayerSpeed = await getItem('audioPlayerSpeed');
         const cachedSkipBlank = await getItem('skipBlank');
         const cachedEpubTheme = await getItem('epubTheme');
+        const cachedSmartSentenceSplitting = await getItem('smartSentenceSplitting');
         const cachedHeaderMargin = await getItem('headerMargin');
         const cachedFooterMargin = await getItem('footerMargin');
         const cachedLeftMargin = await getItem('leftMargin');
@@ -187,6 +191,7 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
         setAudioPlayerSpeed(parseFloat(cachedAudioPlayerSpeed || '1'));
         setSkipBlank(cachedSkipBlank === 'false' ? false : true);
         setEpubTheme(cachedEpubTheme === 'true');
+        setSmartSentenceSplitting(cachedSmartSentenceSplitting === 'false' ? false : true);
         setHeaderMargin(parseFloat(cachedHeaderMargin || '0.07'));
         setFooterMargin(parseFloat(cachedFooterMargin || '0.07'));
         setLeftMargin(parseFloat(cachedLeftMargin || '0.07'));
@@ -211,6 +216,9 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
         if (cachedEpubTheme === null) {
           await setItem('epubTheme', 'false');
         }
+        if (cachedSmartSentenceSplitting === null) {
+          await setItem('smartSentenceSplitting', 'true');
+        }
         if (cachedHeaderMargin === null) await setItem('headerMargin', '0.07');
         if (cachedFooterMargin === null) await setItem('footerMargin', '0.07');
         if (cachedLeftMargin === null) await setItem('leftMargin', '0.0');
@@ -353,6 +361,9 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
           case 'epubTheme':
             setEpubTheme(value as boolean);
             break;
+          case 'smartSentenceSplitting':
+            setSmartSentenceSplitting(value as boolean);
+            break;
           case 'headerMargin':
             setHeaderMargin(value as number);
             break;
@@ -388,6 +399,7 @@ export function ConfigProvider({ children }: { children: ReactNode }) {
       voice,
       skipBlank,
       epubTheme,
+      smartSentenceSplitting,
       headerMargin,
       footerMargin,
       leftMargin,
@@ -417,4 +429,4 @@ export function useConfig() {
     throw new Error('useConfig must be used within a ConfigProvider');
   }
   return context;
-}
+}