Add Kitten TTS and resumable jobs

Add KittenML kitten-tts-micro-0.8 support, improve markdown cleaning, add resume-on-error with partial MP3 handling, and fix final MP3 merging for multi-chunk jobs.

.env.example

@@ -2,7 +2,11 @@ HOST=0.0.0.0
 PORT=7860
 MODEL_DIR=/app/models/supertonic-2
 SUPERTONIC_CACHE_DIR=/app/models/supertonic-2
+KITTEN_MODEL_NAME=KittenML/kitten-tts-micro-0.8
+KITTEN_CACHE_DIR=/app/models/hf-cache
 KOKORO_MODEL_DIR=/app/models/kokoro
+HF_HOME=/app/models/hf-cache
+HUGGINGFACE_HUB_CACHE=/app/models/hf-cache
 WORKSPACE_DIR=/tmp/tts-server
 JOB_DB_PATH=/tmp/tts-server/jobs.db
 PERSISTENT_OUTPUT_DIR=/data

Dockerfile

@@ -7,7 +7,11 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PORT=7860 \
     MODEL_DIR=/app/models/supertonic-2 \
     SUPERTONIC_CACHE_DIR=/app/models/supertonic-2 \
+    KITTEN_MODEL_NAME=KittenML/kitten-tts-micro-0.8 \
+    KITTEN_CACHE_DIR=/app/models/hf-cache \
     KOKORO_MODEL_DIR=/app/models/kokoro \
+    HF_HOME=/app/models/hf-cache \
+    HUGGINGFACE_HUB_CACHE=/app/models/hf-cache \
     WORKSPACE_DIR=/tmp/tts-server \
     JOB_DB_PATH=/tmp/tts-server/jobs.db \
     PERSISTENT_OUTPUT_DIR=/data \
@@ -29,7 +33,7 @@ RUN pip install -r requirements.txt
 
 COPY --chown=user:user . /app
 
-RUN mkdir -p /app/models/supertonic-2 /app/models/kokoro /tmp/tts-server /data && \
+RUN mkdir -p /app/models/supertonic-2 /app/models/kokoro /app/models/hf-cache /tmp/tts-server /data && \
     chown -R user:user /tmp/tts-server /data && \
     python -c "from supertonic import TTS; tts = TTS(model_dir='/app/models/supertonic-2', auto_download=True); print(f'Preloaded model at {tts.model_dir}')"
 
@@ -44,6 +48,12 @@ snapshot_download(
 print('Preloaded Kokoro assets into /app/models/kokoro')
 PY
 
+RUN python - <<'PY'
+from kittentts import KittenTTS
+KittenTTS(model_name='KittenML/kitten-tts-micro-0.8', cache_dir='/app/models/hf-cache', backend='cpu')
+print('Preloaded Kitten TTS assets into /app/models/hf-cache')
+PY
+
 USER user
 
 EXPOSE 7860

README.md

@@ -16,6 +16,7 @@ This directory is a Hugging Face Docker Space variant of the project.
 - Writes only final merged MP3 files to `/data`
 - Deletes temporary source, normalized, and chunk files after a successful merge
 - Keeps auth disabled by default so the public Space UI works immediately
+- Includes Kitten TTS alongside Supertonic and Kokoro, all running CPU-only
 
 ## Persistent storage behavior
 
@@ -33,6 +34,8 @@ Most important overrides:
 - `API_KEY=...` when auth is enabled
 - `PERSISTENT_OUTPUT_DIR=/data`
 - `WORKSPACE_DIR=/tmp/tts-server`
+- `KITTEN_MODEL_NAME=KittenML/kitten-tts-micro-0.8`
+- `KITTEN_CACHE_DIR=/app/models/hf-cache`
 
 ## Local run
 
@@ -55,5 +58,6 @@ Then open `http://localhost:7860`.
 ## Notes
 
 - Build-time model downloads stay inside the image under `/app/models`
+- Kitten TTS caches Hugging Face assets under `/app/models/hf-cache`
 - Runtime persistent storage is only used for final MP3s
 - ffmpeg is required for MP3 encoding and merging

app/api/jobs.py

@@ -9,14 +9,22 @@ from app.config import Settings, get_settings
 from app.schemas_jobs import JobListResponse, JobResponse
 from app.services.engine_registry import get_engine_registry
 from app.services.file_storage import JobStorage
-from app.services.job_store import create_job, delete_job, get_job, list_jobs, update_job
+from app.services.job_store import (
+    create_job,
+    delete_job,
+    get_job,
+    list_jobs,
+    update_job,
+)
+from app.services.text_cleaner import detect_type
 
 router = APIRouter(prefix="/jobs", tags=["jobs"])
 
 
 def _job_to_response(job) -> JobResponse:
     download_url = None
-    if job.status == "completed" and job.final_mp3_path:
+    partial_output_available = bool(job.final_mp3_path and job.status == "failed")
+    if job.final_mp3_path:
         download_url = f"/jobs/{job.id}/download"
     return JobResponse(
         id=job.id,
@@ -27,23 +35,28 @@ def _job_to_response(job) -> JobResponse:
         voice=job.voice,
         speed=job.speed,
         quality=job.quality,
+        resume_on_error=job.resume_on_error,
         total_chunks=job.total_chunks,
         completed_chunks=job.completed_chunks,
         progress_percent=job.progress_percent,
         status_message=job.status_message,
         error_message=job.error_message,
+        partial_output_available=partial_output_available,
         created_at=job.created_at,
         updated_at=job.updated_at,
         download_url=download_url,
     )
 
 
-@router.post("", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)])
+@router.post(
+    "", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)]
+)
 async def create_job_route(
     model: str = Form(...),
     voice: str = Form(...),
     speed: float = Form(1.0, ge=0.25, le=4.0),
     quality: str = Form("balanced"),
+    resume_on_error: bool = Form(False),
     title: str | None = Form(None),
     file: UploadFile | None = File(default=None),
     text: str | None = Form(default=None),
@@ -57,16 +70,22 @@ async def create_job_route(
         raise HTTPException(status_code=400, detail=f"Unknown model: {model}")
 
     if quality not in {"low", "balanced", "high"}:
-        raise HTTPException(status_code=400, detail="quality must be low, balanced, or high")
+        raise HTTPException(
+            status_code=400, detail="quality must be low, balanced, or high"
+        )
 
     if hasattr(engine, "supports_voice") and not engine.supports_voice(voice):
-        raise HTTPException(status_code=400, detail=f"Voice '{voice}' not available for model '{model}'")
+        raise HTTPException(
+            status_code=400, detail=f"Voice '{voice}' not available for model '{model}'"
+        )
 
     job_id = f"job_{uuid.uuid4().hex[:12]}"
     has_file = file is not None and bool(file.filename)
     has_text = bool(text and text.strip())
     if not has_file and not has_text:
-        raise HTTPException(status_code=400, detail="Either a file or text field is required")
+        raise HTTPException(
+            status_code=400, detail="Either a file or text field is required"
+        )
 
     filename = None
     content_bytes = None
@@ -74,7 +93,9 @@ async def create_job_route(
         filename = file.filename  # type: ignore[assignment]
         ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
         if ext not in {"txt", "md"}:
-            raise HTTPException(status_code=400, detail="Only .txt and .md files are supported")
+            raise HTTPException(
+                status_code=400, detail="Only .txt and .md files are supported"
+            )
         content_bytes = await file.read()
 
     storage = JobStorage()
@@ -82,36 +103,47 @@ async def create_job_route(
     source_path = None
     source_filename_val = filename  # default to uploaded filename
     if content_bytes is not None:
-        source_path = str(storage.save_upload(content_bytes, filename or "upload.txt", job_id))
+        source_path = str(
+            storage.save_upload(content_bytes, filename or "upload.txt", job_id)
+        )
     elif text and text.strip():
         # Pasted text — save as a file so the runner can load it
-        text_bytes = text.strip().encode("utf-8")
-        source_path = str(storage.save_upload(text_bytes, "pasted.txt", job_id))
-        source_filename_val = "pasted.txt"
+        normalized_text = text.strip()
+        text_bytes = normalized_text.encode("utf-8")
+        detected_source_type = detect_type(normalized_text)
+        source_filename_val = f"pasted.{detected_source_type}"
+        source_path = str(storage.save_upload(text_bytes, source_filename_val, job_id))
 
     title_value = title or (Path(filename).stem if filename else f"Job {job_id}")
     job = create_job(
         id=job_id,
         title=title_value,
         source_filename=source_filename_val,
-        source_type="md" if (source_filename_val and source_filename_val.endswith(".md")) else "txt",
+        source_type="md"
+        if (source_filename_val and source_filename_val.endswith(".md"))
+        else "txt",
         model=model,
         voice=voice,
         speed=speed,
         quality=quality,
+        resume_on_error=resume_on_error,
         source_path=source_path,
         output_dir=str(storage.get_job_dir(job_id)),
     )
     return _job_to_response(job)
 
 
-@router.get("", response_model=JobListResponse, dependencies=[Depends(require_bearer_auth)])
+@router.get(
+    "", response_model=JobListResponse, dependencies=[Depends(require_bearer_auth)]
+)
 async def list_jobs_route(limit: int = 20) -> JobListResponse:
     jobs = list_jobs(limit=limit)
     return JobListResponse(jobs=[_job_to_response(j) for j in jobs], total=len(jobs))
 
 
-@router.get("/{job_id}", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)])
+@router.get(
+    "/{job_id}", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)]
+)
 async def get_job_route(job_id: str) -> JobResponse:
     job = get_job(job_id)
     if job is None:
@@ -119,24 +151,47 @@ async def get_job_route(job_id: str) -> JobResponse:
     return _job_to_response(job)
 
 
-@router.post("/{job_id}/retry", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)])
+@router.post(
+    "/{job_id}/retry",
+    response_model=JobResponse,
+    dependencies=[Depends(require_bearer_auth)],
+)
 async def retry_job_route(job_id: str) -> JobResponse:
     job = get_job(job_id)
     if job is None:
         raise HTTPException(status_code=404, detail="Job not found")
     if job.status not in ("failed",):
         raise HTTPException(status_code=400, detail="Can only retry failed jobs")
-    return _job_to_response(update_job(job_id, status="queued", error_message=None, status_message=None))
+    next_message = (
+        "Queued to resume" if job.resume_on_error and job.completed_chunks else None
+    )
+    return _job_to_response(
+        update_job(
+            job_id,
+            status="queued",
+            error_message=None,
+            status_message=next_message,
+            final_mp3_path=None,
+        )
+    )
 
 
-@router.post("/{job_id}/cancel", response_model=JobResponse, dependencies=[Depends(require_bearer_auth)])
+@router.post(
+    "/{job_id}/cancel",
+    response_model=JobResponse,
+    dependencies=[Depends(require_bearer_auth)],
+)
 async def cancel_job_route(job_id: str) -> JobResponse:
     job = get_job(job_id)
     if job is None:
         raise HTTPException(status_code=404, detail="Job not found")
     if job.status in ("completed", "failed"):
-        raise HTTPException(status_code=400, detail="Cannot cancel completed or already-failed job")
-    return _job_to_response(update_job(job_id, status="cancelled", status_message="Cancelled by user"))
+        raise HTTPException(
+            status_code=400, detail="Cannot cancel completed or already-failed job"
+        )
+    return _job_to_response(
+        update_job(job_id, status="cancelled", status_message="Cancelled by user")
+    )
 
 
 @router.delete("/{job_id}", dependencies=[Depends(require_bearer_auth)])
@@ -154,8 +209,6 @@ async def download_job_route(job_id: str) -> FileResponse:
     job = get_job(job_id)
     if job is None:
         raise HTTPException(status_code=404, detail="Job not found")
-    if job.status != "completed":
-        raise HTTPException(status_code=400, detail="Job is not complete")
     if not job.final_mp3_path:
         raise HTTPException(status_code=404, detail="Output file not found")
 

app/config.py

@@ -6,11 +6,15 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 class Settings(BaseSettings):
-    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    )
 
     host: str = "0.0.0.0"
     port: int = 7860
     model_dir: str = "/app/models/supertonic-2"
+    kitten_model_name: str = "KittenML/kitten-tts-micro-0.8"
+    kitten_cache_dir: str = "/app/models/hf-cache"
     custom_voice_dir: str = "/app/voices"
     kokoro_model_dir: str = "/app/models/kokoro"
     kokoro_model_file: str = "model_q8f16.onnx"

app/main.py

@@ -14,6 +14,7 @@ from app.db import setup_database
 from app.errors import register_exception_handlers
 from app.services.engine_registry import EngineRegistry, set_engine_registry
 from app.services.job_worker import start_worker, stop_worker
+from app.services.kitten_engine import KittenEngine
 from app.services.kokoro_engine import KokoroEngine
 from app.services.model_assets import validate_kokoro_assets, validate_model_assets
 from app.services.supertonic_engine import SupertonicEngine
@@ -25,10 +26,14 @@ async def lifespan(app: FastAPI):
     validate_model_assets(settings.model_dir, allow_missing_voice_files=True)
     validate_kokoro_assets(settings.kokoro_model_dir, settings.kokoro_model_file)
     supertonic_engine = SupertonicEngine.from_settings(settings)
+    kitten_engine = KittenEngine.from_settings(settings)
     kokoro_engine = KokoroEngine.from_settings(settings)
     registry = EngineRegistry(
         model_to_engine={
-            **{model: supertonic_engine for model in supertonic_engine.public_model_ids},
+            **{
+                model: supertonic_engine for model in supertonic_engine.public_model_ids
+            },
+            **{model: kitten_engine for model in kitten_engine.public_model_ids},
             **{model: kokoro_engine for model in kokoro_engine.public_model_ids},
         }
     )

app/schemas_jobs.py

@@ -12,6 +12,7 @@ class CreateJobRequest(BaseModel):
     file_filename: Optional[str] = Field(default=None, description="Original filename")
     file_content: Optional[bytes] = Field(default=None, description="Raw file bytes")
     text: Optional[str] = None
+    resume_on_error: bool = False
 
     @model_validator(mode="after")
     def require_input(self) -> "CreateJobRequest":
@@ -48,11 +49,13 @@ class JobResponse(BaseModel):
     voice: str
     speed: float
     quality: str
+    resume_on_error: bool = False
     total_chunks: int
     completed_chunks: int
     progress_percent: float
     status_message: Optional[str]
     error_message: Optional[str]
+    partial_output_available: bool = False
     created_at: str
     updated_at: str
     download_url: Optional[str] = None

app/services/file_storage.py

@@ -5,9 +5,15 @@ import re
 
 
 class JobStorage:
-    def __init__(self, workspace_dir: str | None = None, persistent_output_dir: str | None = None):
-        self.workspace_dir = Path(workspace_dir or os.getenv("WORKSPACE_DIR", "/tmp/tts-server"))
-        self.persistent_output_dir = Path(persistent_output_dir or os.getenv("PERSISTENT_OUTPUT_DIR", "/data"))
+    def __init__(
+        self, workspace_dir: str | None = None, persistent_output_dir: str | None = None
+    ):
+        self.workspace_dir = Path(
+            workspace_dir or os.getenv("WORKSPACE_DIR", "/tmp/tts-server")
+        )
+        self.persistent_output_dir = Path(
+            persistent_output_dir or os.getenv("PERSISTENT_OUTPUT_DIR", "/data")
+        )
         self.jobs_dir = self.workspace_dir / "jobs"
 
     def init_dirs(self) -> None:
@@ -18,7 +24,10 @@ class JobStorage:
         return self.jobs_dir / job_id
 
     def get_persistent_output_path(self, job_id: str, filename: str) -> Path:
-        safe_name = re.sub(r"[^A-Za-z0-9._-]+", "-", Path(filename).name).strip(".-") or f"{job_id}.mp3"
+        safe_name = (
+            re.sub(r"[^A-Za-z0-9._-]+", "-", Path(filename).name).strip(".-")
+            or f"{job_id}.mp3"
+        )
         if not safe_name.endswith(".mp3"):
             safe_name = f"{safe_name}.mp3"
         return self.persistent_output_dir / f"{job_id}-{safe_name}"
@@ -35,12 +44,32 @@ class JobStorage:
         path.write_text(text, encoding="utf-8")
         return path
 
-    def save_chunk(self, audio_bytes: bytes, job_id: str, chunk_index: int, ext: str) -> Path:
-        path = self.get_job_dir(job_id) / "chunks" / f"{chunk_index:03d}.{ext.lstrip('.')}"
+    def save_chunk(
+        self, audio_bytes: bytes, job_id: str, chunk_index: int, ext: str
+    ) -> Path:
+        path = self.get_chunk_path(job_id, chunk_index, ext)
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_bytes(audio_bytes)
         return path
 
+    def get_chunk_path(self, job_id: str, chunk_index: int, ext: str) -> Path:
+        return (
+            self.get_job_dir(job_id) / "chunks" / f"{chunk_index:03d}.{ext.lstrip('.')}"
+        )
+
+    def list_chunk_paths(self, job_id: str, ext: str = "mp3") -> list[Path]:
+        return sorted(
+            (self.get_job_dir(job_id) / "chunks").glob(f"*.{ext.lstrip('.')}")
+        )
+
+    def clear_chunks(self, job_id: str, ext: str | None = None) -> None:
+        chunk_dir = self.get_job_dir(job_id) / "chunks"
+        if not chunk_dir.exists():
+            return
+        pattern = "*" if ext is None else f"*.{ext.lstrip('.')}"
+        for path in chunk_dir.glob(pattern):
+            path.unlink(missing_ok=True)
+
     def save_final(self, audio_bytes: bytes, job_id: str, filename: str) -> str:
         path = self.get_persistent_output_path(job_id, filename)
         path.write_bytes(audio_bytes)

app/services/job_runner.py

@@ -37,6 +37,28 @@ def _slugify_filename(value: str) -> str:
     return slug or uuid.uuid4().hex
 
 
+def _merge_chunks_to_output(chunk_paths: list[Path], final_path: Path) -> None:
+    if not chunk_paths:
+        raise JobRunnerError("No chunk audio available to merge")
+    if len(chunk_paths) == 1:
+        final_path.parent.mkdir(parents=True, exist_ok=True)
+        final_path.write_bytes(chunk_paths[0].read_bytes())
+        return
+    merge_mp3s(chunk_paths, final_path)
+
+
+def _load_existing_chunk_paths(
+    storage: JobStorage, job_id: str, completed_chunks: int
+) -> list[Path]:
+    chunk_paths: list[Path] = []
+    for chunk_index in range(1, completed_chunks + 1):
+        path = storage.get_chunk_path(job_id, chunk_index, "mp3")
+        if not path.exists():
+            return []
+        chunk_paths.append(path)
+    return chunk_paths
+
+
 def run_job(job_id: str) -> None:
     """Main entry point — processes job_id synchronously."""
     storage = JobStorage()
@@ -65,7 +87,7 @@ def run_job(job_id: str) -> None:
         storage.save_normalized(cleaned, job_id)
 
         update_job(job_id, status="chunking", status_message="Chunking text…")
-        chunks = chunk_text(cleaned, job.model)
+        chunks = chunk_text(cleaned, job.model, already_cleaned=True)
         if not chunks:
             raise JobRunnerError("Text chunking produced no chunks")
 
@@ -76,11 +98,35 @@ def run_job(job_id: str) -> None:
         engine = registry.get_engine(job.model)
 
         chunk_paths: list[Path] = []
-        for i, chunk in enumerate(chunks, start=1):
+        start_chunk = 1
+        if job.resume_on_error and job.completed_chunks > 0:
+            chunk_paths = _load_existing_chunk_paths(
+                storage, job_id, job.completed_chunks
+            )
+            if chunk_paths and job.completed_chunks <= len(chunks):
+                start_chunk = job.completed_chunks + 1
+                update_job(
+                    job_id,
+                    progress_percent=round(
+                        10.0 + (job.completed_chunks / len(chunks)) * 80.0, 1
+                    ),
+                    status_message=f"Resuming from chunk {start_chunk}/{len(chunks)}",
+                )
+            else:
+                chunk_paths = []
+                start_chunk = 1
+
+        if not job.resume_on_error or start_chunk == 1:
+            storage.clear_chunks(job_id, "mp3")
+            if job.final_mp3_path:
+                Path(job.final_mp3_path).unlink(missing_ok=True)
+            update_job(job_id, completed_chunks=0, final_mp3_path=None)
+
+        for i in range(start_chunk, len(chunks) + 1):
+            chunk = chunks[i - 1]
             pct = 10.0 + (i / len(chunks)) * 80.0
             update_job(
                 job_id,
-                completed_chunks=i,
                 progress_percent=round(pct, 1),
                 status_message=f"Chunk {i}/{len(chunks)}",
             )
@@ -98,6 +144,7 @@ def run_job(job_id: str) -> None:
             )
             chunk_path = storage.save_chunk(audio_bytes, job_id, i, "mp3")
             chunk_paths.append(chunk_path)
+            update_job(job_id, completed_chunks=i)
 
         update_job(
             job_id,
@@ -109,10 +156,7 @@ def run_job(job_id: str) -> None:
         title_slug = _slugify_filename(job.title or job.id)
         final_path = storage.get_persistent_output_path(job_id, f"{title_slug}.mp3")
 
-        if len(chunk_paths) == 1:
-            final_path.write_bytes(chunk_paths[0].read_bytes())
-        else:
-            merge_mp3s(chunk_paths, final_path)
+        _merge_chunks_to_output(chunk_paths, final_path)
 
         storage.cleanup_temp_job(job_id)
 
@@ -124,9 +168,38 @@ def run_job(job_id: str) -> None:
             final_mp3_path=str(final_path),
         )
     except Exception as exc:
-        if "final_path" in locals() and isinstance(final_path, Path):
+        partial_output_path = None
+        current_job = get_job(job_id) or job
+        if current_job.resume_on_error and current_job.completed_chunks > 0:
+            try:
+                chunk_paths = _load_existing_chunk_paths(
+                    storage, job_id, current_job.completed_chunks
+                )
+                if chunk_paths:
+                    title_slug = _slugify_filename(current_job.title or current_job.id)
+                    final_path = storage.get_persistent_output_path(
+                        job_id, f"{title_slug}.mp3"
+                    )
+                    _merge_chunks_to_output(chunk_paths, final_path)
+                    partial_output_path = str(final_path)
+            except Exception:
+                partial_output_path = None
+        elif "final_path" in locals() and isinstance(final_path, Path):
             final_path.unlink(missing_ok=True)
+
+        resume_hint = (
+            " Retry to resume from the last completed chunk."
+            if current_job.resume_on_error and current_job.completed_chunks > 0
+            else ""
+        )
+        partial_hint = (
+            " Partial MP3 is available for download." if partial_output_path else ""
+        )
         update_job(
-            job_id, status="failed", status_message="Failed", error_message=str(exc)
+            job_id,
+            status="failed",
+            status_message="Failed",
+            error_message=f"{exc}{partial_hint}{resume_hint}",
+            final_mp3_path=partial_output_path,
         )
         raise

app/services/job_store.py

@@ -26,6 +26,7 @@ class JobRecord:
     normalized_text_path: Optional[str]
     output_dir: Optional[str]
     final_mp3_path: Optional[str]
+    resume_on_error: bool
     total_chunks: int
     completed_chunks: int
     progress_percent: float
@@ -67,6 +68,7 @@ def init_db() -> None:
             normalized_text_path TEXT,
             output_dir TEXT,
             final_mp3_path TEXT,
+            resume_on_error INTEGER NOT NULL DEFAULT 0,
             total_chunks INTEGER DEFAULT 0,
             completed_chunks INTEGER DEFAULT 0,
             progress_percent REAL DEFAULT 0.0,
@@ -76,12 +78,27 @@ def init_db() -> None:
             updated_at TEXT NOT NULL
         )
         """)
+        _ensure_columns(
+            conn,
+            {
+                "resume_on_error": "INTEGER NOT NULL DEFAULT 0",
+            },
+        )
+
+
+def _ensure_columns(conn: sqlite3.Connection, expected_columns: dict[str, str]) -> None:
+    existing = {row[1] for row in conn.execute("PRAGMA table_info(jobs)").fetchall()}
+    for name, ddl in expected_columns.items():
+        if name not in existing:
+            conn.execute(f"ALTER TABLE jobs ADD COLUMN {name} {ddl}")
 
 
 def _row_to_job(row: sqlite3.Row | None) -> JobRecord | None:
     if row is None:
         return None
-    return JobRecord(**dict(row))
+    data = dict(row)
+    data["resume_on_error"] = bool(data.get("resume_on_error", 0))
+    return JobRecord(**data)
 
 
 def create_job(**kwargs) -> JobRecord:
@@ -96,6 +113,7 @@ def create_job(**kwargs) -> JobRecord:
         "normalized_text_path": None,
         "output_dir": None,
         "final_mp3_path": None,
+        "resume_on_error": False,
         "total_chunks": 0,
         "completed_chunks": 0,
         "progress_percent": 0.0,

app/services/kitten_engine.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from app.config import Settings
+from app.errors import OpenAICompatibleError
+from app.services.supertonic_engine import SynthesisResult
+
+try:
+    from kittentts import KittenTTS
+except ImportError:  # pragma: no cover
+    KittenTTS = None
+
+
+@dataclass(frozen=True)
+class KittenVoiceSpec:
+    alias: str
+    canonical_name: str
+    provider_voice_id: str
+    source: str = "builtin"
+    style_path: str = ""
+
+
+class KittenEngine:
+    public_model_ids = [
+        "kitten-tts-micro-0.8",
+        "kitten-tts-micro",
+        "kitten-tts",
+        "kitten",
+    ]
+    primary_model_id = "kitten-tts-micro-0.8"
+    sample_rate = 24000
+    voice_aliases = {
+        "bella": {"canonical_name": "Bella", "provider_voice_id": "expr-voice-2-f"},
+        "jasper": {"canonical_name": "Jasper", "provider_voice_id": "expr-voice-2-m"},
+        "luna": {"canonical_name": "Luna", "provider_voice_id": "expr-voice-3-f"},
+        "bruno": {"canonical_name": "Bruno", "provider_voice_id": "expr-voice-3-m"},
+        "rosie": {"canonical_name": "Rosie", "provider_voice_id": "expr-voice-4-f"},
+        "hugo": {"canonical_name": "Hugo", "provider_voice_id": "expr-voice-4-m"},
+        "kiki": {"canonical_name": "Kiki", "provider_voice_id": "expr-voice-5-f"},
+        "leo": {"canonical_name": "Leo", "provider_voice_id": "expr-voice-5-m"},
+    }
+
+    def __init__(self, tts: object | None, model_name: str) -> None:
+        self.tts = tts
+        self.model_name = model_name
+
+    @classmethod
+    def from_settings(cls, settings: Settings) -> "KittenEngine":
+        if KittenTTS is None:
+            return cls(tts=None, model_name=settings.kitten_model_name)
+        try:
+            tts = KittenTTS(
+                model_name=settings.kitten_model_name,
+                cache_dir=settings.kitten_cache_dir,
+                backend="cpu",
+            )
+            return cls(tts=tts, model_name=settings.kitten_model_name)
+        except Exception as exc:  # pragma: no cover
+            raise OpenAICompatibleError(
+                status_code=500,
+                message=f"Failed to initialize Kitten TTS engine: {exc}",
+                error_type="server_error",
+                code="engine_init_failed",
+            ) from exc
+
+    def list_voice_bindings(self) -> list[dict[str, str]]:
+        return [
+            {
+                "alias": voice,
+                "canonical_name": spec["canonical_name"],
+                "provider_voice_id": spec["provider_voice_id"],
+                "source": "builtin",
+                "style_path": "",
+                "model": self.primary_model_id,
+            }
+            for voice, spec in self.voice_aliases.items()
+        ]
+
+    def supports_voice(self, voice: str) -> bool:
+        return voice.strip().lower() in self.voice_aliases
+
+    def synthesize(
+        self,
+        *,
+        text: str,
+        voice: str,
+        speed: float,
+        quality: str,
+        model_name: str,
+        lang: str,
+    ) -> SynthesisResult:
+        del quality, model_name, lang
+        if self.tts is None:
+            raise OpenAICompatibleError(
+                status_code=500,
+                message="Kitten TTS engine is not available.",
+                error_type="server_error",
+                code="engine_unavailable",
+            )
+        normalized_voice = voice.strip().lower()
+        if normalized_voice not in self.voice_aliases:
+            raise OpenAICompatibleError(
+                status_code=400,
+                message=f"Unsupported Kitten voice '{voice}'.",
+                param="voice",
+                code="unsupported_voice",
+            )
+        if speed <= 0:
+            raise OpenAICompatibleError(
+                status_code=400,
+                message="Kitten speed must be greater than 0.",
+                param="speed",
+                code="invalid_speed",
+            )
+        try:
+            provider_voice_id = self.voice_aliases[normalized_voice][
+                "provider_voice_id"
+            ]
+            audio = self.tts.generate(
+                text, voice=provider_voice_id, speed=speed, clean_text=False
+            )
+        except Exception as exc:
+            raise OpenAICompatibleError(
+                status_code=500,
+                message=f"Speech synthesis failed: {exc}",
+                error_type="server_error",
+                code="synthesis_failed",
+            ) from exc
+        return SynthesisResult(waveform=np.asarray(audio), sample_rate=self.sample_rate)

app/services/mp3_merger.py

@@ -17,9 +17,32 @@ def merge_mp3s(chunk_paths: list[Path], output_path: Path) -> None:
     output_path.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=True) as f:
         for p in chunk_paths:
-            escaped = p.as_posix().replace("'", "'\\''")
+            escaped = p.resolve().as_posix().replace("'", "'\\''")
             f.write(f"file '{escaped}'\n")
         f.flush()
-        subprocess.run([
-            "ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", f.name, "-c", "copy", str(output_path)
-        ], check=True, capture_output=True)
+        try:
+            subprocess.run(
+                [
+                    "ffmpeg",
+                    "-y",
+                    "-loglevel",
+                    "error",
+                    "-f",
+                    "concat",
+                    "-safe",
+                    "0",
+                    "-i",
+                    f.name,
+                    "-vn",
+                    "-c:a",
+                    "libmp3lame",
+                    "-q:a",
+                    "2",
+                    str(output_path),
+                ],
+                check=True,
+                capture_output=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            stderr = exc.stderr.decode("utf-8", errors="ignore").strip()
+            raise RuntimeError(stderr or "ffmpeg failed to merge mp3 chunks") from exc

app/services/text_chunker.py

@@ -12,6 +12,8 @@ def get_chunk_size_limit(model: str) -> int:
     m = (model or "").lower()
     if "supertonic" in m:
         return 4500
+    if "kitten" in m:
+        return 3000
     if "kokoro" in m:
         return 2000
     return 3000
@@ -39,11 +41,15 @@ def _split_with_limit(text: str, limit: int) -> list[str]:
             if current:
                 chunks.extend(_split_with_limit(current, limit))
             return chunks
-    return [text[i:i + limit].strip() for i in range(0, len(text), limit) if text[i:i + limit].strip()]
+    return [
+        text[i : i + limit].strip()
+        for i in range(0, len(text), limit)
+        if text[i : i + limit].strip()
+    ]
 
 
-def chunk_text(text: str, model: str) -> list[dict]:
-    cleaned = clean(text)
+def chunk_text(text: str, model: str, already_cleaned: bool = False) -> list[dict]:
+    cleaned = text if already_cleaned else clean(text)
     limit = get_chunk_size_limit(model)
     chunks: list[str] = []
     for para in _PARA_SPLIT.split(cleaned):

app/services/text_cleaner.py

@@ -1,4 +1,6 @@
+import html
 import re
+import unicodedata
 from typing import Literal
 
 
@@ -15,8 +17,11 @@ _LINK = re.compile(r"\[([^\]]+)\]\((?:[^()\s]+|\([^()]*\))*\)")
 _IMAGE = re.compile(r"!\[[^\]]*\]\((?:[^()\s]+|\([^()]*\))*\)")
 _HR = re.compile(r"^\s*(?:---+|\*\*\*+|___+)\s*$", re.MULTILINE)
 _HTML = re.compile(r"<[^>]+>")
-_MD_ATTRIBUTE_BLOCK = re.compile(r"\{[^{}\n]*\}")
-_UNSUPPORTED_MD_SYMBOLS = re.compile(r"[\^{}]")
+_MD_ATTRIBUTE_BLOCK = re.compile(r"\{\s*[.#][^{}\n]*\}")
+_FOOTNOTE_REF = re.compile(r"\[\^([^\]]+)\]")
+_FOOTNOTE_DEF = re.compile(r"^\[\^([^\]]+)\]:\s*(.+)$", re.MULTILINE)
+_CARET_WRAP = re.compile(r"\^([^\^\n]+)\^")
+_ZERO_WIDTH = re.compile(r"[\u200b-\u200f\ufeff]")
 
 
 _PUNCT = str.maketrans(
@@ -39,7 +44,10 @@ _PUNCT = str.maketrans(
 
 
 def _txt_clean(text: str) -> str:
+    text = html.unescape(text or "")
+    text = unicodedata.normalize("NFKC", text)
     text = text.translate(_PUNCT)
+    text = _ZERO_WIDTH.sub("", text)
     text = _CONTROL_CHARS.sub("", text)
     lines = []
     for line in text.splitlines():
@@ -59,6 +67,9 @@ def clean_markdown(text: str) -> str:
     text = _FENCED_CODE.sub("\n", text)
     text = _IMAGE.sub("", text)
     text = _LINK.sub(r"\1", text)
+    text = _FOOTNOTE_DEF.sub(r"\2", text)
+    text = _FOOTNOTE_REF.sub(r"\1", text)
+    text = _CARET_WRAP.sub(r"\1", text)
     text = _INLINE_CODE.sub(r"\1", text)
     text = _ATX_HEADING.sub(r"Section: \1", text)
     text = _SETEXT_HEADING.sub(r"Section: \1", text)
@@ -70,8 +81,7 @@ def clean_markdown(text: str) -> str:
     text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)
     text = re.sub(r"__(.+?)__", r"\1", text)
     text = re.sub(r"\*(.+?)\*", r"\1", text)
-    text = re.sub(r"_(.+?)_", r"\1", text)
-    text = _UNSUPPORTED_MD_SYMBOLS.sub(" ", text)
+    text = re.sub(r"(?<!\w)_(?!\s)(.+?)(?<!\s)_(?!\w)", r"\1", text)
     return _txt_clean(text)
 
 

app/templates/index.html

@@ -38,6 +38,9 @@
   .field input:focus, .field select:focus, .field textarea:focus { outline: none; border-color: var(--accent); }
   .field textarea { resize: vertical; min-height: 120px; display: none; }
   .field .helper { margin-top: 0.35rem; font-size: 0.78rem; color: var(--text-muted); }
+  .check-row { display: flex; align-items: flex-start; gap: 0.6rem; }
+  .check-row input[type="checkbox"] { width: auto; margin-top: 0.2rem; }
+  .check-row label { margin-bottom: 0; }
   .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
   .speed-wrap { display: flex; align-items: center; gap: 0.75rem; }
   .speed-wrap input[type="range"] { flex: 1; accent-color: var(--accent); }
@@ -128,6 +131,15 @@
         </div>
       </div>
     </div>
+    <div class="field">
+      <div class="check-row">
+        <input type="checkbox" id="resumeOnErrorCheckbox" />
+        <div>
+          <label for="resumeOnErrorCheckbox">Resume from the last completed chunk if conversion fails</label>
+          <div class="helper">Keeps completed chunk MP3s, creates a partial merged MP3 on failure, and lets retry continue from where it stopped.</div>
+        </div>
+      </div>
+    </div>
   </div>
 
   <div style="text-align:right;"><button class="btn btn-primary" id="startBtn">Start conversion</button></div>
@@ -157,6 +169,7 @@
   const fileInfo = document.getElementById('fileInfo');
   const uploadError = document.getElementById('uploadError');
   const apiKeyInput = document.getElementById('apiKeyInput');
+  const resumeOnErrorCheckbox = document.getElementById('resumeOnErrorCheckbox');
   const authError = document.getElementById('authError');
   const jobsList = document.getElementById('jobsList');
   const emptyJobs = document.getElementById('emptyJobs');
@@ -246,6 +259,7 @@
     if (!model || !voice) return showError('Please select a model and voice');
     const formData = new FormData();
     formData.append('model', model); formData.append('voice', voice); formData.append('quality', quality); formData.append('speed', String(speed));
+    formData.append('resume_on_error', resumeOnErrorCheckbox.checked ? 'true' : 'false');
     if (selectedFile) formData.append('file', selectedFile, selectedFile.name);
     else if (textInput.value.trim()) formData.append('text', textInput.value.trim());
     else return showError('Please upload a file or paste text');

app/templates/job.html

@@ -89,13 +89,14 @@
     <span class="detail-label">Voice</span><span class="detail-value">{{ job.voice }}</span>
     <span class="detail-label">Speed</span><span class="detail-value">{{ job.speed }}×</span>
     <span class="detail-label">Quality</span><span class="detail-value">{{ job.quality }}</span>
+    <span class="detail-label">Resume on error</span><span class="detail-value">{{ 'Yes' if job.resume_on_error else 'No' }}</span>
     {% if job.total_chunks > 0 %}<span class="detail-label">Chunks</span><span class="detail-value">{{ job.completed_chunks }} / {{ job.total_chunks }}</span>{% endif %}
     <span class="detail-label">Created</span><span class="detail-value">{{ job.created_at[:19] | replace('T', ' ') }}</span>
   </div>
 </div>
 <div class="actions" id="actions">
-  {% if job.status == 'completed' %}<button type="button" class="btn btn-primary" id="downloadBtn">Download MP3</button>{% endif %}
-  {% if job.status == 'failed' %}<button class="btn btn-secondary" id="retryBtn">Retry</button>{% endif %}
+  {% if job.final_mp3_path %}<button type="button" class="btn btn-primary" id="downloadBtn">{{ 'Download partial MP3' if job.status == 'failed' else 'Download MP3' }}</button>{% endif %}
+  {% if job.status == 'failed' %}<button class="btn btn-secondary" id="retryBtn">{{ 'Resume conversion' if job.resume_on_error and job.completed_chunks else 'Retry' }}</button>{% endif %}
   {% if job.status not in ('completed', 'failed', 'cancelled') %}<button class="btn btn-danger" id="cancelBtn">Cancel</button>{% endif %}
   {% if job.status in ('completed', 'failed', 'cancelled') %}<button class="btn btn-secondary" id="deleteBtn">Delete</button>{% endif %}
 </div>

requirements.txt

@@ -6,6 +6,7 @@ numpy==1.26.4
 supertonic==1.1.2
 onnxruntime==1.22.1
 huggingface_hub==0.34.4
+kittentts @ https://github.com/KittenML/KittenTTS/releases/download/0.8.1/kittentts-0.8.1-py3-none-any.whl
 phonemizer-fork==3.3.2
 espeakng-loader==0.2.4
 pytest==8.4.1

tests/test_job_store.py

@@ -22,16 +22,19 @@ class TestJobStore:
                 voice="alloy",
                 speed=1.0,
                 quality="balanced",
+                resume_on_error=True,
             )
             assert job.id == "test-001"
             assert job.status == "queued"
             assert job.model == "supertonic-2"
             assert job.voice == "alloy"
+            assert job.resume_on_error is True
 
             fetched = job_store_module.get_job("test-001")
             assert fetched is not None
             assert fetched.id == "test-001"
             assert fetched.status == "queued"
+            assert fetched.resume_on_error is True
         finally:
             job_store_module.DB_PATH = original
 

tests/test_models.py

@@ -11,16 +11,21 @@ def test_models_is_public_by_default() -> None:
 
 def test_models_success() -> None:
     with TestClient(app) as client:
-        response = client.get("/v1/models", headers={"Authorization": "Bearer changeme"})
+        response = client.get(
+            "/v1/models", headers={"Authorization": "Bearer changeme"}
+        )
     assert response.status_code == 200
     ids = [item["id"] for item in response.json()["data"]]
     assert "supertonic-2" in ids
+    assert "kitten-tts-micro-0.8" in ids
     assert "kokoro" in ids
 
 
 def test_voices_success() -> None:
     with TestClient(app) as client:
-        response = client.get("/v1/voices", headers={"Authorization": "Bearer changeme"})
+        response = client.get(
+            "/v1/voices", headers={"Authorization": "Bearer changeme"}
+        )
     assert response.status_code == 200
     aliases = {item["alias"] for item in response.json()["data"]}
     assert "alloy" in aliases
@@ -28,9 +33,22 @@ def test_voices_success() -> None:
     assert "grace" in aliases
 
 
+def test_kitten_voices_success() -> None:
+    with TestClient(app) as client:
+        response = client.get(
+            "/v1/voices?model=kitten-tts-micro-0.8",
+            headers={"Authorization": "Bearer changeme"},
+        )
+    assert response.status_code == 200
+    rows = response.json()["data"]
+    assert {item["alias"] for item in rows} >= {"bella", "jasper", "luna"}
+
+
 def test_kokoro_voices_success() -> None:
     with TestClient(app) as client:
-        response = client.get("/v1/voices?model=kokoro", headers={"Authorization": "Bearer changeme"})
+        response = client.get(
+            "/v1/voices?model=kokoro", headers={"Authorization": "Bearer changeme"}
+        )
     assert response.status_code == 200
     rows = response.json()["data"]
     assert any(item["model"] == "kokoro" for item in rows)

tests/test_schemas_jobs.py

@@ -23,8 +23,10 @@ class TestCreateJobRequest:
             voice="af_sarah",
             speed=1.5,
             text="Some text to convert",
+            resume_on_error=True,
         )
         assert req.text == "Some text to convert"
+        assert req.resume_on_error is True
 
     def test_rejects_empty_input(self):
         try:
@@ -52,21 +54,32 @@ class TestCreateJobRequest:
             voice="alloy",
             speed=1.0,
             quality="  Balanced  ",
+            text="hello",
         )
         assert req.quality == "balanced"
 
     def test_rejects_invalid_quality(self):
         try:
-            CreateJobRequest(model="supertonic-2", voice="alloy", speed=1.0, quality="ultra")
+            CreateJobRequest(
+                model="supertonic-2",
+                voice="alloy",
+                speed=1.0,
+                quality="ultra",
+                text="hello",
+            )
             assert False, "expected ValidationError"
         except ValidationError:
             assert True
 
     def test_speed_bounds(self):
-        req = CreateJobRequest(model="supertonic-2", voice="alloy", speed=0.5, text="hello")
+        req = CreateJobRequest(
+            model="supertonic-2", voice="alloy", speed=0.5, text="hello"
+        )
         assert req.speed == 0.5
         try:
-            CreateJobRequest(model="supertonic-2", voice="alloy", speed=5.0, text="hello")
+            CreateJobRequest(
+                model="supertonic-2", voice="alloy", speed=5.0, text="hello"
+            )
             assert False, "expected ValidationError"
         except ValidationError:
             assert True
@@ -83,17 +96,20 @@ class TestJobResponse:
             voice="alloy",
             speed=1.0,
             quality="balanced",
+            resume_on_error=True,
             total_chunks=10,
             completed_chunks=4,
             progress_percent=40.0,
             status_message="Chunk 4/10",
             error_message=None,
+            partial_output_available=False,
             created_at="2025-01-01T12:00:00Z",
             updated_at="2025-01-01T12:01:00Z",
             download_url=None,
         )
         assert resp.id == "job_abc123"
         assert resp.progress_percent == 40.0
+        assert resp.resume_on_error is True
         assert resp.download_url is None
 
     def test_completed_job_has_download_url(self):
@@ -106,11 +122,13 @@ class TestJobResponse:
             voice="alloy",
             speed=1.0,
             quality="balanced",
+            resume_on_error=False,
             total_chunks=1,
             completed_chunks=1,
             progress_percent=100.0,
             status_message="Done",
             error_message=None,
+            partial_output_available=False,
             created_at="2025-01-01T12:00:00Z",
             updated_at="2025-01-01T12:05:00Z",
             download_url="/jobs/job_done/download",

tests/test_speech_response.py

@@ -20,15 +20,21 @@ class FakeEngine:
 
 def fake_registry() -> EngineRegistry:
     engine = FakeEngine()
-    return EngineRegistry(model_to_engine={
-        "supertonic-2": engine,
-        "tts-1": engine,
-        "tts-1-hd": engine,
-        "gpt-4o-mini-tts": engine,
-        "kokoro": engine,
-        "kokoro-onnx": engine,
-        "kokoro-82m": engine,
-    })
+    return EngineRegistry(
+        model_to_engine={
+            "supertonic-2": engine,
+            "tts-1": engine,
+            "tts-1-hd": engine,
+            "gpt-4o-mini-tts": engine,
+            "kitten-tts-micro-0.8": engine,
+            "kitten-tts-micro": engine,
+            "kitten-tts": engine,
+            "kitten": engine,
+            "kokoro": engine,
+            "kokoro-onnx": engine,
+            "kokoro-82m": engine,
+        }
+    )
 
 
 def test_speech_returns_wav(monkeypatch) -> None:
@@ -112,3 +118,23 @@ def test_kokoro_model_route(monkeypatch) -> None:
         assert response.headers["content-type"].startswith("audio/wav")
     finally:
         app.dependency_overrides.clear()
+
+
+def test_kitten_model_route(monkeypatch) -> None:
+    app.dependency_overrides[get_engine_registry] = fake_registry
+    try:
+        with TestClient(app) as client:
+            response = client.post(
+                "/v1/audio/speech",
+                headers={"Authorization": "Bearer changeme"},
+                json={
+                    "model": "kitten-tts-micro-0.8",
+                    "input": "hello",
+                    "voice": "bella",
+                    "response_format": "wav",
+                },
+            )
+        assert response.status_code == 200
+        assert response.headers["content-type"].startswith("audio/wav")
+    finally:
+        app.dependency_overrides.clear()

tests/test_text_chunker.py

@@ -11,6 +11,9 @@ class TestGetChunkSizeLimit:
     def test_kokoro_limit(self):
         assert get_chunk_size_limit("kokoro") == 2000
 
+    def test_kitten_limit(self):
+        assert get_chunk_size_limit("kitten-tts-micro-0.8") == 3000
+
     def test_kokoro_onnx(self):
         assert get_chunk_size_limit("kokoro-onnx") == 2000
 
@@ -64,3 +67,8 @@ class TestChunkText:
     def test_empty_text_returns_empty_list(self):
         chunks = chunk_text("", "supertonic-2")
         assert len(chunks) == 0
+
+    def test_already_cleaned_skips_second_markdown_pass(self):
+        text = "Keep {literal braces}"
+        chunks = chunk_text(text, "supertonic-2", already_cleaned=True)
+        assert chunks[0]["text"] == text

tests/test_text_cleaner.py

@@ -103,6 +103,16 @@ class TestCleanMarkdown:
         assert "}" not in result
         assert "Paragraph with" in result
 
+    def test_preserves_literal_braces_and_normalizes_entities(self):
+        result = clean_markdown("Keep {braces} & full-width：text")
+        assert "{braces}" in result
+        assert "&" not in result
+
+    def test_removes_markdown_footnote_reference_but_keeps_content(self):
+        result = clean_markdown("Paragraph[^1]\n\n[^1]: Footnote content")
+        assert "[^1]" not in result
+        assert "Footnote content" in result
+
 
 class TestClean:
     def test_routes_to_markdown_cleaner(self):