",
+ )
+
+ def _fallback_title(self) -> str:
+ if self.extraction.chapters:
+ first_title = self.extraction.chapters[0].title
+ if first_title:
+ return first_title
+ return "Generated Audiobook"
+
+ def _determine_language(self) -> str:
+ language = self._combined_metadata.get("language")
+ if language:
+ return language
+ return "en"
+
+
+def build_epub3_package(
+ *,
+ output_path: Path,
+ book_id: str,
+ extraction: ExtractionResult,
+ metadata_tags: Dict[str, Any],
+ chapter_markers: Sequence[Dict[str, Any]],
+ chunk_markers: Sequence[Dict[str, Any]],
+ chunks: Iterable[Dict[str, Any]],
+ audio_path: Path,
+ speaker_mode: str = "single",
+ cover_image_path: Optional[Path] = None,
+ cover_image_mime: Optional[str] = None,
+) -> Path:
+ builder = EPUB3PackageBuilder(
+ output_path=output_path,
+ book_id=book_id,
+ extraction=extraction,
+ metadata_tags=metadata_tags,
+ chapter_markers=chapter_markers,
+ chunk_markers=chunk_markers,
+ chunks=chunks,
+ audio_path=audio_path,
+ speaker_mode=speaker_mode,
+ cover_image_path=cover_image_path,
+ cover_image_mime=cover_image_mime,
+ )
+ return builder.build()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+
+
+@dataclass
+class ChunkLookup:
+ by_id: Dict[str, Dict[str, Any]]
+ by_chapter: Dict[int, List[Dict[str, Any]]]
+
+
+def _normalize_metadata(metadata: Optional[Dict[str, Any]]) -> Dict[str, str]:
+ normalized: Dict[str, str] = {}
+ for key, value in (metadata or {}).items():
+ if value is None:
+ continue
+ normalized[str(key).lower()] = str(value)
+ return normalized
+
+
+def _combine_metadata(*sources: Dict[str, Any]) -> Dict[str, str]:
+ combined: Dict[str, str] = {}
+ for source in sources:
+ for key, value in (source or {}).items():
+ if value is None:
+ continue
+ combined[str(key).lower()] = str(value)
+ return combined
+
+
+def _split_authors(metadata: Dict[str, str]) -> List[str]:
+ candidates = []
+ for key in ("artist", "author", "authors", "album_artist", "creator"):
+ value = metadata.get(key)
+ if value:
+ candidates.extend(part.strip() for part in value.replace(";", ",").split(","))
+ return [author for author in candidates if author]
+
+
+def _calculate_total_duration(
+ chunk_markers: Sequence[Dict[str, Any]],
+ chapter_markers: Sequence[Dict[str, Any]],
+) -> Optional[float]:
+ candidates: List[float] = []
+ for marker in chunk_markers or []:
+ end_value = _safe_float(marker.get("end"))
+ if end_value is not None:
+ candidates.append(end_value)
+ for marker in chapter_markers or []:
+ end_value = _safe_float(marker.get("end"))
+ if end_value is not None:
+ candidates.append(end_value)
+ if not candidates:
+ return None
+ return max(candidates)
+
+
+def _write_mimetype(root: Path) -> None:
+ (root / "mimetype").write_text("application/epub+zip", encoding="utf-8")
+
+
+def _write_container_xml(root: Path) -> None:
+ meta_inf = root / "META-INF"
+ meta_inf.mkdir(parents=True, exist_ok=True)
+ container = meta_inf / "container.xml"
+ container.write_text(
+ (
+ "\n"
+ "\n"
+ " \n"
+ " \n"
+ " \n"
+ " \n"
+ ),
+ encoding="utf-8",
+ )
+
+
+def _build_chunk_lookup(chunks: Iterable[Dict[str, Any]]) -> ChunkLookup:
+ by_id: Dict[str, Dict[str, Any]] = {}
+ by_chapter: Dict[int, List[Dict[str, Any]]] = {}
+ for entry in chunks or []:
+ if not isinstance(entry, dict):
+ continue
+ chunk_id = entry.get("id")
+ if chunk_id:
+ by_id[str(chunk_id)] = dict(entry)
+ chapter_index = _safe_int(entry.get("chapter_index"))
+ by_chapter.setdefault(chapter_index, []).append(dict(entry))
+ return ChunkLookup(by_id=by_id, by_chapter=by_chapter)
+
+
+def _group_markers_by_chapter(markers: Iterable[Dict[str, Any]]) -> Dict[int, List[Dict[str, Any]]]:
+ grouped: Dict[int, List[Dict[str, Any]]] = {}
+ for entry in markers or []:
+ if not isinstance(entry, dict):
+ continue
+ chapter_index = _safe_int(entry.get("chapter_index"))
+ grouped.setdefault(chapter_index, []).append(dict(entry))
+ for chapter_index, items in grouped.items():
+ items.sort(key=lambda payload: (_safe_int(payload.get("chunk_index")), _safe_float(payload.get("start")) or 0.0))
+ return grouped
+
+
+def _find_chunk_by_index(
+ chapter_chunks: Sequence[Dict[str, Any]],
+ chunk_index: Optional[int],
+) -> Optional[Dict[str, Any]]:
+ if chunk_index is None:
+ return None
+ for entry in chapter_chunks:
+ if _safe_int(entry.get("chunk_index")) == chunk_index:
+ return entry
+ return None
+
+
+def _normalize_chunk_id(chunk_id: Optional[Any]) -> Optional[str]:
+ if chunk_id is None:
+ return None
+ text = str(chunk_id).strip()
+ if not text:
+ return None
+ safe = "".join(ch if ch.isalnum() or ch in {"_", "-"} else "_" for ch in text)
+ return safe[:120]
+
+
+def _render_chunk_html(chunk: ChunkOverlay) -> str:
+ escaped_id = html.escape(chunk.id)
+ speaker_attr = f" data-speaker=\"{html.escape(chunk.speaker_id)}\"" if chunk.speaker_id else ""
+ voice_attr = f" data-voice=\"{html.escape(chunk.voice)}\"" if chunk.voice else ""
+ paragraphs = _split_paragraphs(chunk.text)
+ if not paragraphs:
+ paragraphs = [" "]
+ return " \n{body}\n
".format(
+ id=escaped_id,
+ speaker=speaker_attr,
+ voice=voice_attr,
+ body="\n".join(f" {para}
" for para in paragraphs),
+ )
+
+
+def _split_paragraphs(text: str) -> List[str]:
+ if not text:
+ return []
+ segments = [segment.strip() for segment in text.replace("\r", "").split("\n\n")]
+ paragraphs: List[str] = []
+ for segment in segments:
+ if not segment:
+ continue
+ lines = [html.escape(line.strip()) for line in segment.split("\n") if line.strip()]
+ if not lines:
+ continue
+ if len(lines) == 1:
+ paragraphs.append(lines[0])
+ else:
+ paragraphs.append("{html.escape(book_id)} ",
+ f" {html.escape(title)} ",
+ f" {html.escape(language or 'en')} ",
+ ]
+
+ for author in authors or ["Unknown"]:
+ elements.append(f" {html.escape(author)} ")
+
+ if publisher:
+ elements.append(f" {html.escape(publisher)} ")
+
+ if description:
+ elements.append(f" {html.escape(description)} ")
+
+ if duration is not None:
+ elements.append(f"
+
Chunk granularity
+
+ {% for option in options.chunk_levels %}
+ {{ option.label }}
+ {% endfor %}
+
+
Controls how chapters are split into TTS-ready chunks.
+
+ Speaker mode
+
+ {% for option in options.speaker_modes %}
+ {{ option.label }}
+ {% endfor %}
+
+
+
+
+ Generate EPUB 3 (experimental)
+
+
Creates a synchronized EPUB alongside audio output.
+
diff --git a/abogen/web/templates/job_detail.html b/abogen/web/templates/job_detail.html
index 7ae11c9..189ace9 100644
--- a/abogen/web/templates/job_detail.html
+++ b/abogen/web/templates/job_detail.html
@@ -26,6 +26,10 @@
Chapter intro delay: {{ '%.1f'|format(job.chapter_intro_delay) }}sMax words per subtitle: {{ job.max_subtitle_words }}Project folder: {{ 'Yes' if job.save_as_project else 'No' }}
+
Chunk granularity: {{ job.chunk_level|replace('_', ' ')|title }}
+
Speaker mode: {{ job.speaker_mode|replace('_', ' ')|title }}
+
Speaker analysis threshold: {{ job.speaker_analysis_threshold }}
+
Generate EPUB 3: {{ 'Yes' if job.generate_epub3 else 'No' }}
@@ -45,7 +49,97 @@
+{% set analysis = job.speaker_analysis or {} %}
+{% if analysis %}
+{% set preview_template = options.speaker_pronunciation_sentence or "This is {{name}} speaking." %}
+
+ Speaker analysis
+
+
+ Summary
+ {% set stats = analysis.get('stats', {}) %}
+
+ Total chunks: {{ stats.get('total_chunks', '—') }}Explicit dialogue chunks: {{ stats.get('explicit_chunks', '—') }}Active speakers: {{ stats.get('active_speakers', '—') }}Unique speakers observed: {{ stats.get('unique_speakers', '—') }}Suppressed speakers: {{ stats.get('suppressed', 0) }}
+
+
+ Detected speakers
+ {% set speakers = analysis.get('speakers', {}) %}
+ {% set narrator_id = analysis.get('narrator', 'narrator') %}
+ {% if speakers %}
+
+ {% for speaker_id, payload in speakers.items() if speaker_id != narrator_id and not payload.get('suppressed') %}
+ {% set spoken_name = payload.get('pronunciation') or payload.get('label') or speaker_id|replace('_', ' ')|title %}
+ {% set preview_text = preview_template | replace("{{name}}", spoken_name) %}
+
+
+ {{ payload.get('label', speaker_id|replace('_', ' ')|title) }}
+
+ 🔊
+
+
+
+ {{ payload.get('count', 0) }} chunks
+ Confidence: {{ payload.get('confidence', 'low')|title }}
+ {% if payload.get('pronunciation') %}
+ Pronunciation: {{ payload.get('pronunciation') }}
+ {% endif %}
+
+ {% set quotes = payload.get('sample_quotes', []) %}
+ {% if quotes %}
+
+ Sample quotes
+
+ {% for quote in quotes %}
+ {{ quote }}
+ {% endfor %}
+
+
+ {% endif %}
+
+ {% endfor %}
+
+ {% else %}
+ No additional speakers detected.
+ {% endif %}
+ {% set suppressed = analysis.get('suppressed_details') or analysis.get('suppressed', []) %}
+ {% if suppressed %}
+
+ Suppressed speakers:
+ {% if suppressed[0] is string %}
+ {{ suppressed | join(', ') }}
+ {% else %}
+ {{ suppressed | map(attribute='label') | join(', ') }}
+ {% endif %}
+
+ {% endif %}
+
+
+{% endif %}
+
{% include "partials/logs.html" %}
{% endblock %}
+
+{% block scripts %}
+ {{ super() }}
+
+{% endblock %}
diff --git a/abogen/web/templates/prepare_job.html b/abogen/web/templates/prepare_job.html
index 7d57da6..9aa99aa 100644
--- a/abogen/web/templates/prepare_job.html
+++ b/abogen/web/templates/prepare_job.html
@@ -33,7 +33,88 @@
Chapter intro delay
{{ '%.1f'|format(pending.chapter_intro_delay) }} seconds
+
+
Chunk granularity
+ {{ pending.chunk_level|replace('_', ' ')|title }}
+
+
+
Speaker mode
+ {{ pending.speaker_mode|replace('_', ' ')|title }}
+
+
+
Speaker analysis threshold
+ {{ pending.speaker_analysis_threshold }} {{ 'mention' if pending.speaker_analysis_threshold == 1 else 'mentions' }}
+
+
+
EPUB 3 package
+ {% if pending.generate_epub3 %}Enabled{% else %}Disabled{% endif %}
+
+ {% set analysis = pending.speaker_analysis or {} %}
+ {% set analysis_speakers = analysis.get('speakers', {}) %}
+ {% if analysis_speakers %}
+ {% set active = namespace(items=[]) %}
+ {% for sid, payload in analysis_speakers.items() %}
+ {% if sid != 'narrator' and not payload.get('suppressed') %}
+ {% set _ = active.items.append(payload) %}
+ {% endif %}
+ {% endfor %}
+
+
Detected speakers
+ {% if active.items %}
+
+ {% for speaker in active.items|sort(attribute='label') %}
+ {{ speaker.label }} · {{ speaker.count }} lines · confidence {{ speaker.confidence|title }}
+ {% else %}
+
No additional speakers met the threshold yet. All dialogue will use the narrator voice.
+ {% endif %}
+
+
Speaker pronunciation guide
+
Add a phonetic spelling (IPA or plain text) so pronunciations sound right. Leave blank to use the written label.
+
+
Metadata
@@ -110,11 +191,39 @@
{% endfor %}
+
+
Chunk granularity
+
+ {% for option in options.chunk_levels %}
+ {{ option.label }}
+ {% endfor %}
+
+
Paragraphs work well for long-form narration; sentences give finer subtitle sync.
+
+
+ Speaker mode
+
+ {% for option in options.speaker_modes %}
+ {{ option.label }}
+ {% endfor %}
+
+
+
+
Speaker analysis minimum mentions
+
+
Only speakers that appear at least this many times will keep unique voices in multi-speaker mode.
+
+
+
+ Generate EPUB 3 (experimental)
+
+
Queue conversion
@@ -127,5 +236,6 @@
{% block scripts %}
{{ super() }}
+
{% endblock %}
diff --git a/abogen/web/templates/settings.html b/abogen/web/templates/settings.html
index f792090..c775efc 100644
--- a/abogen/web/templates/settings.html
+++ b/abogen/web/templates/settings.html
@@ -73,6 +73,10 @@
Save as Project With Metadata
+
+ Generate EPUB 3 (experimental)
+
Separate Chapter Format
@@ -83,6 +87,32 @@
+ Chunk Granularity
+
+ {% for option in options.chunk_levels %}
+ {{ option.label }}
+ {% endfor %}
+
+
+
+ Speaker Mode
+
+ {% for option in options.speaker_modes %}
+ {{ option.label }}
+ {% endfor %}
+
+
+
+
Speaker Analysis Minimum Mentions
+
+
Speakers detected fewer times than this fallback to the narrator voice.
+
+
Speaker Pronunciation Preview
+
+
Sentence template used when previewing name pronunciation. Include {{ '{{name}}' }} where the speaker name should be inserted.
+
Silence Between Chapters (Seconds)
diff --git a/docs/epub3_upgrade_plan.md b/docs/epub3_upgrade_plan.md
new file mode 100644
index 0000000..d343a5a
--- /dev/null
+++ b/docs/epub3_upgrade_plan.md
@@ -0,0 +1,208 @@
+# EPUB 3 Upgrade Plan
+
+## Overview
+Elevate Abogen to produce rich EPUB 3 packages with synchronized narration, configurable TTS chunking, and groundwork for multi-speaker voice assignment. This document records the objectives, architectural adjustments, data model changes, UI flows, and implementation phases required to deliver the upgrade.
+
+## Goals
+- Generate EPUB 3 output that preserves source metadata and embeds audio narration via media overlays.
+- Allow users to choose the chunking granularity (paragraph vs. sentence) used for TTS synthesis and media-overlay alignment.
+- Introduce speaker assignments for every chunk, starting with a single narrator but paving the way for multi-speaker control.
+- Prototype practical, lightweight strategies for detecting likely speakers and estimating their dialogue frequency.
+
+## Non-goals / Out-of-scope
+- Full multi-speaker editing UI (beyond gating the option).
+- Automatic voice-casting or LLM-based dialogue attribution.
+- Desktop GUI resurrection (web UI remains primary).
+
+## Current Architecture Snapshot
+| Area | Notes |
+| --- | --- |
+| Text ingestion | `abogen/text_extractor.py` outputs `ExtractionResult` with chapter-level text.
+| Job prep UI | `web/routes.py` builds `PendingJob` objects and renders chapter selection.
+| Audio pipeline | `web/conversion_runner.py` creates per-job audio artifacts; chunking is effectively paragraph-level.
+| Metadata | `ExtractionResult.metadata` feeds into FF metadata and output tagging, but not yet into EPUB packaging.
+
+## Feature 1 – EPUB 3 Output with Narration
+### Requirements
+- Preserve original EPUB metadata (Dublin Core entries, TOC, cover art).
+- Package synthesized audio and SMIL media overlays aligned to chosen chunk granularity.
+- Provide EPUB as an additional selectable output alongside current audio/subtitle formats.
+
+### Proposed Components
+1. **`abogen/epub3/exporter.py`** (new module)
+ - Responsibilities: build XHTML spine with IDs, generate overlay SMIL files, write OPF manifest/spine, assemble zip package.
+ - Status: **Implemented** — `build_epub3_package` emits EPUB 3 archives with media overlays driven by chunk metadata.
+ - Dependencies: reuse `ebooklib` for reading source metadata; use `zipfile` for packaging; optional `lxml` for DOM manipulation.
+2. **`EPUB3PackageBuilder` class**
+ - Inputs: extraction payload, chunk collection (with IDs, speaker mapping, timing metadata), audio asset paths, source metadata.
+ - Outputs: path to generated EPUB.
+3. **Metadata preservation**
+ - Copy from source `ExtractionResult.metadata` and EPUB navigation if available.
+ - Ensure custom fields (e.g., chapter count) survive.
+4. **Media overlay generation**
+ - Create one SMIL per content doc or per chapter, depending on chunk count.
+ - `` nodes reference chunk IDs and audio clip times.
+5. **Configuration surface**
+ - Add “EPUB 3 (audio + text)” to output format selector (or a dedicated toggle under project settings).
+
+### Data Flow
+```
+extract_from_path -> Chapter payload
+ |-> chunker (sentence/paragraph)
+ |-> chunk IDs + audio segments (timestamps from runner)
+Conversion runner -> audio files + timing index
+EPUB3PackageBuilder -> manifest, spine, SMIL, zip
+```
+
+### Open Questions
+- Should we embed audio inside the EPUB or link externally? (Plan: embed to comply with spec.)
+- How to handle very large audio assets? Consider splitting per chapter to keep file sizes manageable.
+
+## Feature 2 – Configurable Chunking
+### Requirements
+- Users select chunking level (paragraph or sentence) before audio generation.
+- Pipeline produces stable, unique IDs for each chunk regardless of level.
+- Provide chunk metadata (text, speaker, offsets) to both TTS and EPUB exporter.
+
+### Proposed Architecture
+1. **Chunk Model**
+ ```python
+ @dataclass
+ class Chunk:
+ id: str
+ chapter_index: int
+ order: int
+ level: Literal["paragraph", "sentence"]
+ text: str
+ speaker_id: str
+ approx_characters: int
+ ```
+2. **Chunker Service (`abogen/chunking.py`)**
+ - Accepts chapter text and desired level.
+ - Uses spaCy (already bundled via `en-core-web-sm`) for sentence segmentation; fallback to regex when model unavailable.
+ - Emits `Chunk` objects with deterministic IDs (e.g., `chap{chapter_index:04d}_para{paragraph_idx:03d}_sent{sentence_idx:03d}`).
+3. **Integration points**
+ - `web/routes.py` -> apply chunker when building `PendingJob` instead of storing raw paragraphs only.
+ - `PendingJob` / `Job` dataclasses -> include `chunks` list and `chunk_level` enum.
+ - `conversion_runner` -> iterate over `chunks` when synthesizing audio, producing per-chunk audio and capturing actual duration for overlay.
+4. **Settings persistence**
+ - Extend config with `chunking_level` default; expose in UI (radio buttons or select).
+
+### Testing
+- Unit tests for chunk splitting across languages, punctuation, abbreviations.
+- Property-based tests ensuring concatenated chunks reproduce original text (except whitespace normalization).
+
+## Feature 3 – Speaker Assignment Foundations
+### Requirements
+- Every chunk must carry a `speaker_id` (default `narrator`).
+- UI offers new option: “Single Speaker” (proceeds) vs. “Multi-Speaker (Coming Soon)” (blocks and shows message).
+- Data model anticipates future multi-speaker support.
+
+### Implementation Outline
+1. **Data Model Changes**
+ - `Chunk.speaker_id` default `"narrator"`.
+ - `PendingJob` & `Job` store `speakers` metadata (dictionary of speaker descriptors).
+ - `JobResult` optionally includes `chunk_speakers.json` artifact for downstream use.
+2. **UI Adjustments**
+ - On upload form (`index.html` / JS), add selector for speaker mode.
+ - If “Multi-Speaker” chosen, display tooltip/modal: “Coming soon; please choose Single Speaker to continue.” disable submission.
+ - In `prepare_job.html`, display speaker info column (read-only for now).
+3. **Serialization**
+ - Update JSON API routes to include speaker data.
+ - Update queue/job detail templates to show chunk level & speaker summary.
+
+### Testing
+- Add web route tests ensuring multi-speaker path blocks progression.
+- Verify job persistence includes `speaker_id` fields.
+
+## Feature 4 – Speaker Detection Strategies
+### Objectives
+Build groundwork for lightweight, deterministic speaker inference to inform future multi-speaker mode.
+
+### User Stories
+1. **As a producer**, I can run an automated analysis on a book to see the list of likely speakers and how often they talk, so I can decide where multiple voices make sense.
+ - _Acceptance_: System outputs a JSON report containing speaker IDs/names, occurrence counts, representative excerpts, and confidence tier. Report stored with job artifacts and downloadable from job detail page.
+2. **As a producer**, I can set a minimum occurrence threshold so that infrequent speakers automatically fall back to the narrator voice.
+ - _Acceptance_: Analysis respects configurable threshold; speakers below it are tagged as `default_narrator` in the report.
+3. **As a developer/operator**, I can trigger the analysis via CLI or background task without blocking the main conversion pipeline.
+ - _Acceptance_: Command `abogen analyze-speakers