headvox 0.1.0__py3-none-any.whl

headvox/__init__.py

@@ -0,0 +1,33 @@
+"""HeadVox — turn a script into a talking-head voiceover with aligned captions.
+
+HeadVox reads a plain-text or Markdown script, synthesizes it segment by
+segment through a pluggable TTS backend, stitches the audio into a single
+track, and emits word-aligned subtitles plus a timing manifest you can use
+to drive a talking-head avatar or a video editor.
+
+Public API:
+    from headvox import synthesize, Script, get_backend
+
+Everything here is original work, released under the MIT License.
+"""
+from __future__ import annotations
+
+from .script import Script, Segment, split_script
+from .backends import TTSBackend, SegmentAudio, WordMark, get_backend, register_backend
+from .synth import synthesize, SynthResult, VoiceSettings
+
+__all__ = [
+    "Script",
+    "Segment",
+    "split_script",
+    "TTSBackend",
+    "SegmentAudio",
+    "WordMark",
+    "get_backend",
+    "register_backend",
+    "synthesize",
+    "SynthResult",
+    "VoiceSettings",
+]
+
+__version__ = "0.1.0"

headvox/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

headvox/backends/__init__.py

@@ -0,0 +1,79 @@
+"""Pluggable TTS backends.
+
+A backend turns a short piece of text into audio bytes plus optional word
+boundaries. Register your own with :func:`register_backend` and select it by
+name on the command line or through :func:`headvox.synthesize`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Protocol, runtime_checkable
+
+
+@dataclass
+class WordMark:
+    """A word and where it falls inside a segment's audio (milliseconds)."""
+
+    text: str
+    start_ms: int
+    end_ms: int
+
+
+@dataclass
+class SegmentAudio:
+    """Result of synthesizing one segment."""
+
+    audio: bytes
+    audio_format: str  # "mp3" or "wav"
+    duration_ms: int
+    words: List[WordMark] = field(default_factory=list)
+
+
+@runtime_checkable
+class TTSBackend(Protocol):
+    """Interface every backend implements."""
+
+    name: str
+
+    def synthesize_segment(self, text: str, settings) -> SegmentAudio:  # noqa: D401
+        ...
+
+
+_REGISTRY: Dict[str, Callable[..., TTSBackend]] = {}
+
+
+def register_backend(name: str, factory: Callable[..., TTSBackend]) -> None:
+    _REGISTRY[name.lower()] = factory
+
+
+def available_backends() -> List[str]:
+    return sorted(_REGISTRY)
+
+
+def get_backend(name: str, **kwargs) -> TTSBackend:
+    key = name.lower()
+    if key not in _REGISTRY:
+        raise ValueError(
+            f"unknown backend {name!r}; available: {', '.join(available_backends()) or '(none)'}"
+        )
+    return _REGISTRY[key](**kwargs)
+
+
+# Register the backends that ship with HeadVox. Imports are deferred inside the
+# factories so a missing optional dependency only fails when that backend is
+# actually used.
+
+def _edge_factory(**kw):
+    from .edge import EdgeBackend
+
+    return EdgeBackend(**kw)
+
+
+def _sine_factory(**kw):
+    from .sine import SineBackend
+
+    return SineBackend(**kw)
+
+
+register_backend("edge", _edge_factory)
+register_backend("sine", _sine_factory)

headvox/backends/edge.py

@@ -0,0 +1,73 @@
+"""Edge TTS backend.
+
+Wraps the `edge-tts` project (Microsoft Edge's online neural voices, free to
+use) behind HeadVox's backend interface. It returns MP3 audio and real
+word-boundary marks, which is what makes tight caption alignment possible.
+
+Install the optional dependency::
+
+    pip install "headvox[edge]"
+
+HeadVox does not bundle or re-host any voice model; it calls the same public
+service the `edge-tts` CLI uses.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import List, Optional
+
+from . import SegmentAudio, WordMark
+
+
+def _fmt_pct(v: float, unit: str = "%") -> str:
+    sign = "+" if v >= 0 else "-"
+    return f"{sign}{abs(int(round(v)))}{unit}"
+
+
+class EdgeBackend:
+    """TTS backend backed by edge-tts neural voices."""
+
+    name = "edge"
+
+    def __init__(self, proxy: Optional[str] = None) -> None:
+        try:
+            import edge_tts  # noqa: F401
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ImportError(
+                "the 'edge' backend needs edge-tts; install with "
+                "pip install \"headvox[edge]\""
+            ) from exc
+        self.proxy = proxy
+
+    def synthesize_segment(self, text: str, settings) -> SegmentAudio:
+        return asyncio.run(self._run(text, settings))
+
+    async def _run(self, text: str, settings) -> SegmentAudio:
+        import edge_tts
+
+        comm = edge_tts.Communicate(
+            text,
+            voice=settings.voice or "en-US-EmmaMultilingualNeural",
+            rate=_fmt_pct(settings.rate_pct),
+            volume=_fmt_pct(settings.volume_pct),
+            pitch=_fmt_pct(settings.pitch_hz, "Hz"),
+            boundary="WordBoundary",
+            proxy=self.proxy,
+        )
+        audio = bytearray()
+        words: List[WordMark] = []
+        async for chunk in comm.stream():
+            if chunk["type"] == "audio":
+                audio += chunk["data"]
+            elif chunk["type"] == "WordBoundary":
+                start = int(chunk["offset"] / 10_000)  # 100-ns ticks -> ms
+                dur = int(chunk["duration"] / 10_000)
+                words.append(WordMark(chunk["text"], start, start + dur))
+        duration_ms = words[-1].end_ms if words else 0
+        return SegmentAudio(
+            audio=bytes(audio),
+            audio_format="mp3",
+            duration_ms=duration_ms,
+            words=words,
+        )
+

headvox/backends/sine.py

@@ -0,0 +1,63 @@
+"""Offline "sine" backend.
+
+Produces a soft tone per word instead of speech. It needs no network and no
+extra packages, so it's what the test suite uses, and it's handy for checking
+pacing, caption layout, and video muxing before spending real TTS calls.
+"""
+from __future__ import annotations
+
+import io
+import math
+import struct
+import wave
+
+from . import SegmentAudio, WordMark
+from ..script import iter_words
+
+SAMPLE_RATE = 24_000
+
+
+class SineBackend:
+    name = "sine"
+
+    def __init__(self, ms_per_word: int = 260, ms_per_cjk: int = 210, gap_ms: int = 40) -> None:
+        self.ms_per_word = ms_per_word
+        self.ms_per_cjk = ms_per_cjk
+        self.gap_ms = gap_ms
+
+    def synthesize_segment(self, text: str, settings) -> SegmentAudio:
+        speed = max(0.25, 1.0 + settings.rate_pct / 100.0)
+        freq = 220.0 * (2 ** (settings.pitch_hz / 1200.0)) if settings.pitch_hz else 220.0
+        frames = bytearray()
+        words = []
+        t = 0
+        for tok in iter_words(text):
+            if not any(ch.isalnum() for ch in tok):
+                continue  # punctuation is silent
+            base = self.ms_per_cjk if len(tok) == 1 and ord(tok) > 0x2E80 else self.ms_per_word
+            dur = int(base / speed)
+            frames += _tone(freq, dur)
+            frames += _silence(self.gap_ms)
+            words.append(WordMark(tok, t, t + dur))
+            t += dur + self.gap_ms
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(SAMPLE_RATE)
+            w.writeframes(bytes(frames))
+        return SegmentAudio(buf.getvalue(), "wav", t, words)
+
+
+def _tone(freq: float, ms: int) -> bytes:
+    n = int(SAMPLE_RATE * ms / 1000)
+    fade = max(1, int(SAMPLE_RATE * 0.01))
+    out = bytearray()
+    for i in range(n):
+        env = min(1.0, i / fade, (n - i) / fade)
+        out += struct.pack("<h", int(6000 * env * math.sin(2 * math.pi * freq * i / SAMPLE_RATE)))
+    return bytes(out)
+
+
+def _silence(ms: int) -> bytes:
+    return b"\x00\x00" * int(SAMPLE_RATE * ms / 1000)

headvox/captions.py

@@ -0,0 +1,142 @@
+"""Caption building: word timings -> readable SRT / WebVTT cues.
+
+Cues never cross a segment boundary, prefer to break after punctuation, and
+respect a character budget where a CJK character counts as two columns. The
+cue text is sliced from the original script, so punctuation and casing survive
+even when the TTS engine reports bare words.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Sequence, Tuple
+
+from .script import _is_wide, _visual_len
+
+_BREAK_AFTER = set("。！？!?…，,；;：:、.")
+
+
+@dataclass
+class Cue:
+    index: int
+    start_ms: int
+    end_ms: int
+    text: str
+
+
+def _locate(text: str, words) -> List[Optional[Tuple[int, int]]]:
+    """Find each word's span in ``text``, scanning left to right."""
+    spans: List[Optional[Tuple[int, int]]] = []
+    cursor = 0
+    low = text.lower()
+    for w in words:
+        needle = w.text.strip().lower()
+        if not needle:
+            spans.append(None)
+            continue
+        idx = low.find(needle, cursor)
+        if idx == -1 or idx - cursor > 40:
+            spans.append(None)
+            continue
+        spans.append((idx, idx + len(needle)))
+        cursor = idx + len(needle)
+    return spans
+
+
+def _extend_punct(text: str, end: int) -> int:
+    while end < len(text) and (text[end] in _BREAK_AFTER or text[end] in "\"'”’」』）)】]"):
+        end += 1
+    return end
+
+
+def _join_words(tokens: Sequence[str]) -> str:
+    out = ""
+    for t in tokens:
+        if out and not (_is_wide(out[-1]) or _is_wide(t[0])):
+            out += " "
+        out += t
+    return out
+
+
+def build_cues(timed_segments, *, max_chars: int = 42, max_ms: int = 5000) -> List[Cue]:
+    cues: List[Cue] = []
+    budget = max_chars
+    for seg in timed_segments:
+        words = seg.words
+        if not words:
+            cues.append(Cue(len(cues) + 1, seg.start_ms, seg.end_ms, seg.text))
+            continue
+        spans = _locate(seg.text, words)
+        group: List[int] = []
+
+        def flush(group_idx: List[int], last_in_segment: bool) -> None:
+            first, last = group_idx[0], group_idx[-1]
+            s_span, e_span = spans[first], spans[last]
+            if s_span and e_span:
+                start_char = 0 if first == 0 else s_span[0]
+                end_char = len(seg.text) if last_in_segment else _extend_punct(seg.text, e_span[1])
+                text = seg.text[start_char:end_char].strip()
+            else:
+                text = _join_words([words[k].text for k in group_idx])
+            start = words[first].start_ms
+            end = seg.end_ms if last_in_segment else words[last].end_ms
+            cues.append(Cue(len(cues) + 1, start, max(end, start + 200), text))
+
+        def breaks_after(k: int) -> bool:
+            sp = spans[k]
+            return bool(sp) and sp[1] < len(seg.text) and seg.text[sp[1]] in _BREAK_AFTER
+
+        for i, w in enumerate(words):
+            group.append(i)
+            if i + 1 >= len(words):
+                break
+            cur_len = _visual_len(_join_words([words[k].text for k in group]))
+            nxt_len = _visual_len(_join_words([words[k].text for k in group] + [words[i + 1].text]))
+            dur = w.end_ms - words[group[0]].start_ms
+            if cur_len >= budget * 0.6 and breaks_after(i):
+                flush(group, False)
+                group = []
+            elif nxt_len > budget or dur >= max_ms:
+                # back up to the last punctuation in this cue when there is one,
+                # so lines end on a natural phrase instead of mid-word
+                cut = next((j for j in range(len(group) - 1, 0, -1) if breaks_after(group[j - 1])), None)
+                if cut is not None and cut < len(group):
+                    flush(group[:cut], False)
+                    group = group[cut:]
+                else:
+                    flush(group, False)
+                    group = []
+        if group:
+            flush(group, True)
+
+    # make cues contiguous enough to read, without overlapping
+    for a, b in zip(cues, cues[1:]):
+        if b.start_ms - a.end_ms < 120:
+            a.end_ms = max(a.start_ms + 200, b.start_ms - 1)
+    return cues
+
+
+def _ts(ms: int, sep: str) -> str:
+    h, rem = divmod(max(0, ms), 3_600_000)
+    m, rem = divmod(rem, 60_000)
+    s, ms = divmod(rem, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d}{sep}{ms:03d}"
+
+
+def to_srt(cues: Sequence[Cue]) -> str:
+    return "\n".join(
+        f"{c.index}\n{_ts(c.start_ms, ',')} --> {_ts(c.end_ms, ',')}\n{c.text}\n" for c in cues
+    )
+
+
+def to_vtt(cues: Sequence[Cue]) -> str:
+    body = "\n".join(f"{_ts(c.start_ms, '.')} --> {_ts(c.end_ms, '.')}\n{c.text}\n" for c in cues)
+    return "WEBVTT\n\n" + body
+
+
+def write_srt(cues: Sequence[Cue], path: Path) -> None:
+    Path(path).write_text(to_srt(cues), "utf-8")
+
+
+def write_vtt(cues: Sequence[Cue], path: Path) -> None:
+    Path(path).write_text(to_vtt(cues), "utf-8")

headvox/cli.py

@@ -0,0 +1,132 @@
+"""Command line interface: ``headvox script.md -o out/ --voice ...``"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .backends import available_backends
+from .script import Script
+from .synth import VoiceSettings, default_cache_dir, synthesize
+
+PRESET_VOICES = {
+    "zh-female": "zh-CN-XiaoxiaoNeural",
+    "zh-male": "zh-CN-YunxiNeural",
+    "en-female": "en-US-AvaMultilingualNeural",
+    "en-male": "en-US-AndrewMultilingualNeural",
+    "ja-female": "ja-JP-NanamiNeural",
+    "ja-male": "ja-JP-KeitaNeural",
+}
+
+
+def _signed(v: str) -> float:
+    return float(v.rstrip("%").rstrip("Hz").rstrip("hz"))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="headvox",
+        description="Turn a script into a talking-head voiceover with aligned SRT/VTT captions.",
+    )
+    p.add_argument("script", help="script file (.md or .txt), or '-' for stdin")
+    p.add_argument("-o", "--out", default="headvox-out", help="output directory (default: headvox-out)")
+    p.add_argument("-n", "--name", default="voiceover", help="base name for output files")
+    p.add_argument("-b", "--backend", default="edge", choices=available_backends())
+    p.add_argument("-v", "--voice", default="zh-female",
+                   help=f"voice id or preset ({', '.join(PRESET_VOICES)})")
+    p.add_argument("--rate", type=_signed, default=0, help="speed change in percent, e.g. +8 or -5")
+    p.add_argument("--pitch", type=_signed, default=0, help="pitch change in Hz, e.g. +2")
+    p.add_argument("--volume", type=_signed, default=0, help="volume change in percent")
+    p.add_argument("--format", default="mp3", choices=["mp3", "wav", "m4a"])
+    p.add_argument("--plain", action="store_true", help="treat input as plain text, not Markdown")
+    p.add_argument("--max-len", type=int, default=120, help="longest segment sent to TTS")
+    p.add_argument("--sentence-pause", type=int, default=250, help="ms between sentences")
+    p.add_argument("--paragraph-pause", type=int, default=700, help="ms between paragraphs")
+    p.add_argument("--caption-chars", type=int, default=42, help="caption width (CJK char = 2)")
+    p.add_argument("--no-cache", action="store_true", help="always call the TTS backend")
+    p.add_argument("--proxy", default=None, help="HTTP proxy for online backends")
+    p.add_argument("--video", help="video to put the voiceover on")
+    p.add_argument("--burn-subs", action="store_true", help="render captions into the picture")
+    p.add_argument("--no-subs", action="store_true", help="don't attach captions to the video")
+    p.add_argument("--music", help="background music, looped and ducked under the voice")
+    p.add_argument("--music-volume", type=float, default=0.12)
+    p.add_argument("--fit", choices=["loop", "audio"], default="loop",
+                   help="loop the video to the voiceover length, or cut at the shorter one")
+    p.add_argument("--dry-run", action="store_true", help="only print how the script will be segmented")
+    p.add_argument("-q", "--quiet", action="store_true")
+    p.add_argument("--version", action="version", version=f"headvox {__version__}")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    raw = sys.stdin.read() if args.script == "-" else Path(args.script).read_text("utf-8")
+    script = Script.from_text(
+        raw,
+        markdown=not args.plain,
+        max_len=args.max_len,
+        sentence_pause_ms=args.sentence_pause,
+        paragraph_pause_ms=args.paragraph_pause,
+    )
+    if not script.segments:
+        print("headvox: the script has nothing to say", file=sys.stderr)
+        return 2
+
+    if args.dry_run:
+        for i, s in enumerate(script.segments, 1):
+            print(f"{i:>3}. [{s.pause_after_ms:>4} ms] {s.text}")
+        return 0
+
+    settings = VoiceSettings(
+        voice=PRESET_VOICES.get(args.voice, args.voice),
+        rate_pct=args.rate, pitch_hz=args.pitch, volume_pct=args.volume,
+    )
+    backend_opts = {}
+    if args.backend == "edge":
+        backend_opts["proxy"] = args.proxy or os.environ.get("HEADVOX_PROXY")
+
+    def progress(i, total, seg):
+        if args.quiet:
+            return
+        bar = "#" * int(20 * i / total)
+        print(f"\r[{bar:<20}] {i}/{total}", end="" if i < total else "\n", file=sys.stderr, flush=True)
+
+    try:
+        res = synthesize(
+            script, args.out,
+            backend=args.backend, settings=settings, name=args.name,
+            audio_format=args.format,
+            cache_dir=None if args.no_cache else default_cache_dir(),
+            caption_max_chars=args.caption_chars,
+            backend_options=backend_opts, progress=progress,
+        )
+    except Exception as exc:  # surface a clean message on the CLI
+        print(f"\nheadvox: {exc}", file=sys.stderr)
+        return 1
+
+    outputs = [res.audio_path, res.srt_path, res.vtt_path, res.manifest_path]
+    if args.video:
+        from .video import mux
+
+        out_video = Path(args.out) / f"{args.name}.mp4"
+        try:
+            mux(args.video, res.audio_path, out_video,
+                subtitles=None if args.no_subs else res.srt_path,
+                burn=args.burn_subs, music=args.music,
+                music_volume=args.music_volume, fit=args.fit)
+        except Exception as exc:
+            print(f"headvox: {exc}", file=sys.stderr)
+            return 1
+        outputs.append(out_video)
+
+    if not args.quiet:
+        print(f"duration {res.duration_ms / 1000:.2f}s, {len(res.segments)} segments, {len(res.cues)} captions")
+        for o in outputs:
+            print(f"  {o}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

headvox/script.py

@@ -0,0 +1,232 @@
+"""Script parsing: Markdown/plain text -> speakable segments.
+
+Rules
+-----
+* Markdown formatting (headings, emphasis, links, code fences, list bullets,
+  block quotes, images, HTML tags) is stripped down to the words a narrator
+  would actually say.
+* Blank lines separate paragraphs. A paragraph break inserts a longer pause
+  than a sentence break.
+* Inline directives let the writer control pacing:
+      [pause]          -> default extra pause (600 ms)
+      [pause 1.5s]     -> 1.5 s pause
+      [pause 400ms]    -> 400 ms pause
+* Long sentences are split at the nearest clause punctuation so no single
+  TTS request (or caption) grows unwieldy. CJK and Latin punctuation are both
+  understood, so mixed Chinese/English scripts segment naturally.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, List
+
+# Sentence-ending punctuation (Latin + CJK). Closing quotes/brackets that
+# follow the terminator stay attached to the sentence.
+_SENT_END = r"[。！？!?…]+|(?<![0-9A-Z])\.(?=\s|$)"
+_CLOSERS = "\"'”’」』）)】]"
+_CLAUSE = "，,；;：:、—"
+
+_PAUSE_RE = re.compile(r"\[pause(?:\s+([0-9]*\.?[0-9]+)\s*(ms|s)?)?\]", re.IGNORECASE)
+
+DEFAULT_PAUSE_MS = 600
+
+
+@dataclass
+class Segment:
+    """One unit of speech sent to the TTS backend."""
+
+    text: str
+    pause_after_ms: int = 0
+    paragraph: int = 0
+
+    def __post_init__(self) -> None:
+        self.text = self.text.strip()
+
+
+@dataclass
+class Script:
+    segments: List[Segment] = field(default_factory=list)
+
+    @classmethod
+    def from_text(cls, text: str, **kw) -> "Script":
+        return cls(split_script(text, **kw))
+
+    @classmethod
+    def from_file(cls, path: str, **kw) -> "Script":
+        with open(path, "r", encoding="utf-8") as fh:
+            return cls.from_text(fh.read(), **kw)
+
+    @property
+    def text(self) -> str:
+        return " ".join(s.text for s in self.segments)
+
+    def __len__(self) -> int:  # pragma: no cover - trivial
+        return len(self.segments)
+
+    def __iter__(self):  # pragma: no cover - trivial
+        return iter(self.segments)
+
+
+# ---------------------------------------------------------------- markdown
+
+def strip_markdown(text: str) -> str:
+    """Reduce Markdown to narratable prose while keeping paragraph breaks."""
+    # fenced code blocks are not narrated
+    text = re.sub(r"```.*?```", "", text, flags=re.S)
+    text = re.sub(r"~~~.*?~~~", "", text, flags=re.S)
+    # HTML comments are author notes
+    text = re.sub(r"<!--.*?-->", "", text, flags=re.S)
+    # front matter
+    text = re.sub(r"\A---\n.*?\n---\n", "", text, flags=re.S)
+    out_lines = []
+    for line in text.splitlines():
+        s = line.strip()
+        s = re.sub(r"^#{1,6}\s+", "", s)  # headings
+        s = re.sub(r"^>\s?", "", s)  # quotes
+        s = re.sub(r"^([-*+]|\d+[.)])\s+", "", s)  # list bullets
+        s = re.sub(r"^\|.*\|$", "", s) if re.match(r"^\|[\s:-|]+\|$", s) else s  # table rules
+        s = s.replace("|", " ") if s.startswith("|") else s
+        s = re.sub(r"!\[[^\]]*\]\([^)]*\)", "", s)  # images
+        s = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", s)  # links -> label
+        s = re.sub(r"`([^`]*)`", r"\1", s)  # inline code
+        s = re.sub(r"(\*\*|__)(.+?)\1", r"\2", s)  # bold
+        s = re.sub(r"(?<![\w*])([*_])(?!\s)(.+?)(?<!\s)\1(?![\w*])", r"\2", s)  # italics
+        s = re.sub(r"~~(.+?)~~", r"\1", s)
+        s = re.sub(r"<[^>]+>", "", s)  # html tags
+        if re.fullmatch(r"[-*_]{3,}", s):  # horizontal rule
+            s = ""
+        out_lines.append(s)
+    return "\n".join(out_lines)
+
+
+# ---------------------------------------------------------------- splitting
+
+def _parse_pause(m: re.Match) -> int:
+    num, unit = m.group(1), (m.group(2) or "").lower()
+    if num is None:
+        return DEFAULT_PAUSE_MS
+    val = float(num)
+    if unit == "ms":
+        return int(round(val))
+    # bare numbers and "s" are seconds
+    return int(round(val * 1000))
+
+
+def _sentences(par: str) -> List[str]:
+    parts: List[str] = []
+    buf = ""
+    i = 0
+    pattern = re.compile(_SENT_END)
+    while i < len(par):
+        m = pattern.search(par, i)
+        if not m:
+            buf += par[i:]
+            break
+        end = m.end()
+        while end < len(par) and par[end] in _CLOSERS:
+            end += 1
+        buf += par[i:end]
+        parts.append(buf)
+        buf = ""
+        i = end
+    if buf.strip():
+        parts.append(buf)
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _visual_len(s: str) -> int:
+    """Approximate spoken length: CJK chars count double (≈ a Latin word)."""
+    n = 0
+    for ch in s:
+        n += 2 if _is_wide(ch) else 1
+    return n
+
+
+def _is_wide(ch: str) -> bool:
+    o = ord(ch)
+    return (
+        0x1100 <= o <= 0x115F
+        or 0x2E80 <= o <= 0xA4CF
+        or 0xAC00 <= o <= 0xD7A3
+        or 0xF900 <= o <= 0xFAFF
+        or 0xFE30 <= o <= 0xFE4F
+        or 0xFF00 <= o <= 0xFF60
+        or 0xFFE0 <= o <= 0xFFE6
+    )
+
+
+def _split_long(sentence: str, max_len: int) -> List[str]:
+    if _visual_len(sentence) <= max_len:
+        return [sentence]
+    # break at the clause punctuation closest to the middle
+    best = None
+    mid = len(sentence) / 2
+    for idx, ch in enumerate(sentence[:-1]):
+        if ch in _CLAUSE:
+            if best is None or abs(idx - mid) < abs(best - mid):
+                best = idx
+    if best is None:
+        # fall back to the space closest to the middle
+        for idx, ch in enumerate(sentence):
+            if ch == " " and (best is None or abs(idx - mid) < abs(best - mid)):
+                best = idx
+    if best is None:
+        # hard split (e.g. one huge CJK run with no punctuation)
+        cut = max(1, int(mid))
+        return _split_long(sentence[:cut], max_len) + _split_long(sentence[cut:], max_len)
+    left, right = sentence[: best + 1].strip(), sentence[best + 1 :].strip()
+    return [p for p in _split_long(left, max_len) + _split_long(right, max_len) if p]
+
+
+def split_script(
+    text: str,
+    *,
+    markdown: bool = True,
+    max_len: int = 120,
+    sentence_pause_ms: int = 250,
+    paragraph_pause_ms: int = 700,
+) -> List[Segment]:
+    """Split a script into :class:`Segment` objects ready for synthesis."""
+    if markdown:
+        text = strip_markdown(text)
+    text = text.replace("\r\n", "\n")
+    paragraphs = re.split(r"\n\s*\n", text)
+    segments: List[Segment] = []
+    for p_idx, par in enumerate(paragraphs):
+        par = " ".join(l.strip() for l in par.splitlines() if l.strip())
+        if not par:
+            continue
+        # walk through pause directives inside the paragraph
+        pos = 0
+        chunks: List[tuple] = []  # (text, extra_pause)
+        for m in _PAUSE_RE.finditer(par):
+            chunks.append((par[pos : m.start()], _parse_pause(m)))
+            pos = m.end()
+        chunks.append((par[pos:], 0))
+        par_segments: List[Segment] = []
+        for chunk_text, extra in chunks:
+            pieces: List[str] = []
+            for sent in _sentences(chunk_text):
+                pieces.extend(_split_long(sent, max_len))
+            for piece in pieces:
+                par_segments.append(Segment(piece, sentence_pause_ms, p_idx))
+            if extra:
+                if par_segments:
+                    par_segments[-1].pause_after_ms += extra
+                elif segments:
+                    segments[-1].pause_after_ms += extra
+        if par_segments:
+            par_segments[-1].pause_after_ms = max(
+                par_segments[-1].pause_after_ms, paragraph_pause_ms
+            )
+            segments.extend(par_segments)
+    if segments:
+        segments[-1].pause_after_ms = 0
+    return [s for s in segments if s.text]
+
+
+def iter_words(text: str) -> Iterable[str]:
+    """Tokenize for captioning: Latin words stay whole, CJK splits per char."""
+    for tok in re.findall(r"[A-Za-z0-9'’\-]+[.,!?;:]*|[^\sA-Za-z0-9]", text):
+        yield tok

headvox/synth.py

@@ -0,0 +1,240 @@
+"""Core pipeline: script -> per-segment TTS -> one audio track + captions."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional, Union
+
+from .backends import SegmentAudio, TTSBackend, WordMark, get_backend
+from .captions import Cue, build_cues, write_srt, write_vtt
+from .script import Script, Segment
+
+SAMPLE_RATE = 24_000
+BYTES_PER_MS = SAMPLE_RATE * 2 // 1000  # mono s16le
+
+
+@dataclass
+class VoiceSettings:
+    voice: Optional[str] = None
+    rate_pct: float = 0.0  # +10 -> 10% faster
+    pitch_hz: float = 0.0
+    volume_pct: float = 0.0
+
+    def key(self) -> str:
+        return json.dumps(asdict(self), sort_keys=True)
+
+
+@dataclass
+class TimedSegment:
+    index: int
+    text: str
+    start_ms: int
+    end_ms: int
+    pause_after_ms: int
+    words: List[WordMark] = field(default_factory=list)
+
+
+@dataclass
+class SynthResult:
+    audio_path: Path
+    srt_path: Path
+    vtt_path: Path
+    manifest_path: Path
+    duration_ms: int
+    segments: List[TimedSegment]
+    cues: List[Cue]
+    video_path: Optional[Path] = None
+
+
+# ---------------------------------------------------------------- ffmpeg
+
+def _need(tool: str) -> str:
+    path = shutil.which(tool)
+    if not path:
+        raise RuntimeError(
+            f"{tool} not found on PATH. HeadVox uses ffmpeg/ffprobe for audio; "
+            "install it from https://ffmpeg.org or your package manager."
+        )
+    return path
+
+
+def _decode_to_pcm(data: bytes, fmt: str) -> bytes:
+    """Decode any audio blob to mono 24 kHz s16le PCM."""
+    ffmpeg = _need("ffmpeg")
+    proc = subprocess.run(
+        [ffmpeg, "-hide_banner", "-loglevel", "error", "-f", fmt, "-i", "pipe:0",
+         "-ac", "1", "-ar", str(SAMPLE_RATE), "-f", "s16le", "pipe:1"],
+        input=data, capture_output=True, check=False,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"ffmpeg could not decode {fmt} audio: {proc.stderr.decode(errors='ignore')}")
+    return proc.stdout
+
+
+def _trim_silence_tail(pcm: bytes, threshold: int = 300, keep_ms: int = 60) -> bytes:
+    """Drop trailing near-silence some TTS engines pad onto each clip, so the
+    pauses HeadVox inserts are the pauses the listener actually hears."""
+    import array
+
+    a = array.array("h")
+    a.frombytes(pcm[: len(pcm) // 2 * 2])
+    end = len(a)
+    while end > 0 and abs(a[end - 1]) < threshold:
+        end -= 1
+    end = min(len(a), end + SAMPLE_RATE * keep_ms // 1000)
+    return a[:end].tobytes()
+
+
+def _encode(pcm: bytes, out: Path) -> None:
+    ffmpeg = _need("ffmpeg")
+    codec = ["-c:a", "libmp3lame", "-b:a", "128k"] if out.suffix.lower() == ".mp3" else []
+    if out.suffix.lower() == ".m4a":
+        codec = ["-c:a", "aac", "-b:a", "160k"]
+    proc = subprocess.run(
+        [ffmpeg, "-hide_banner", "-loglevel", "error", "-y", "-f", "s16le", "-ar", str(SAMPLE_RATE),
+         "-ac", "1", "-i", "pipe:0", *codec, str(out)],
+        input=pcm, capture_output=True, check=False,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"ffmpeg encode failed: {proc.stderr.decode(errors='ignore')}")
+
+
+# ---------------------------------------------------------------- cache
+
+class _Cache:
+    def __init__(self, root: Optional[Path]) -> None:
+        self.root = root
+        if root:
+            root.mkdir(parents=True, exist_ok=True)
+
+    def _key(self, backend: str, text: str, settings: VoiceSettings) -> str:
+        h = hashlib.sha256(f"{backend}\x00{settings.key()}\x00{text}".encode()).hexdigest()
+        return h[:32]
+
+    def get(self, backend, text, settings) -> Optional[SegmentAudio]:
+        if not self.root:
+            return None
+        k = self._key(backend, text, settings)
+        meta, blob = self.root / f"{k}.json", self.root / f"{k}.bin"
+        if not (meta.exists() and blob.exists()):
+            return None
+        m = json.loads(meta.read_text("utf-8"))
+        return SegmentAudio(
+            blob.read_bytes(), m["format"], m["duration_ms"], [WordMark(**w) for w in m["words"]]
+        )
+
+    def put(self, backend, text, settings, seg: SegmentAudio) -> None:
+        if not self.root:
+            return
+        k = self._key(backend, text, settings)
+        (self.root / f"{k}.bin").write_bytes(seg.audio)
+        (self.root / f"{k}.json").write_text(
+            json.dumps({"format": seg.audio_format, "duration_ms": seg.duration_ms,
+                        "words": [asdict(w) for w in seg.words]}, ensure_ascii=False),
+            "utf-8",
+        )
+
+
+# ---------------------------------------------------------------- main API
+
+def synthesize(
+    script: Union[Script, str],
+    out_dir: Union[str, Path],
+    *,
+    backend: Union[str, TTSBackend] = "edge",
+    settings: Optional[VoiceSettings] = None,
+    name: str = "voiceover",
+    audio_format: str = "mp3",
+    cache_dir: Optional[Union[str, Path]] = None,
+    caption_max_chars: int = 42,
+    caption_max_ms: int = 5000,
+    lead_in_ms: int = 150,
+    trim_tts_padding: bool = True,
+    backend_options: Optional[dict] = None,
+    progress: Optional[Callable[[int, int, Segment], None]] = None,
+) -> SynthResult:
+    """Render a script into ``<out_dir>/<name>.{mp3,srt,vtt,json}``."""
+    if isinstance(script, str):
+        script = Script.from_text(script)
+    if not script.segments:
+        raise ValueError("script is empty: nothing to say")
+    settings = settings or VoiceSettings()
+    tts = get_backend(backend, **(backend_options or {})) if isinstance(backend, str) else backend
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    cache = _Cache(Path(cache_dir) if cache_dir else None)
+
+    pcm = bytearray(b"\x00\x00" * (SAMPLE_RATE * lead_in_ms // 1000))
+    timed: List[TimedSegment] = []
+    total = len(script.segments)
+    for i, seg in enumerate(script.segments):
+        if progress:
+            progress(i, total, seg)
+        clip = cache.get(tts.name, seg.text, settings)
+        if clip is None:
+            clip = tts.synthesize_segment(seg.text, settings)
+            if not clip.audio:
+                raise RuntimeError(f"backend {tts.name!r} returned no audio for: {seg.text!r}")
+            cache.put(tts.name, seg.text, settings, clip)
+        clip_pcm = _decode_to_pcm(clip.audio, clip.audio_format)
+        if trim_tts_padding:
+            last_word = clip.words[-1].end_ms if clip.words else 0
+            trimmed = _trim_silence_tail(clip_pcm)
+            # never cut into the last spoken word
+            min_len = (last_word + 40) * BYTES_PER_MS
+            clip_pcm = trimmed if len(trimmed) >= min_len else clip_pcm[: max(len(trimmed), min_len)]
+        start_ms = len(pcm) // BYTES_PER_MS
+        pcm += clip_pcm
+        end_ms = len(pcm) // BYTES_PER_MS
+        words = [WordMark(w.text, start_ms + w.start_ms, min(end_ms, start_ms + w.end_ms)) for w in clip.words]
+        timed.append(TimedSegment(i, seg.text, start_ms, end_ms, seg.pause_after_ms, words))
+        pcm += b"\x00\x00" * (SAMPLE_RATE * seg.pause_after_ms // 1000)
+    pcm += b"\x00\x00" * (SAMPLE_RATE * 300 // 1000)  # gentle tail
+    if progress:
+        progress(total, total, script.segments[-1])
+
+    audio_path = out / f"{name}.{audio_format}"
+    _encode(bytes(pcm), audio_path)
+    duration_ms = len(pcm) // BYTES_PER_MS
+
+    cues = build_cues(timed, max_chars=caption_max_chars, max_ms=caption_max_ms)
+    srt_path, vtt_path = out / f"{name}.srt", out / f"{name}.vtt"
+    write_srt(cues, srt_path)
+    write_vtt(cues, vtt_path)
+
+    manifest_path = out / f"{name}.json"
+    manifest = {
+        "tool": "headvox",
+        "backend": tts.name,
+        "settings": asdict(settings),
+        "audio": audio_path.name,
+        "duration_ms": duration_ms,
+        "segments": [
+            {"index": t.index, "text": t.text, "start_ms": t.start_ms, "end_ms": t.end_ms,
+             "words": [asdict(w) for w in t.words]}
+            for t in timed
+        ],
+        "cues": [asdict(c) for c in cues],
+    }
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), "utf-8")
+    return SynthResult(audio_path, srt_path, vtt_path, manifest_path, duration_ms, timed, cues)
+
+
+def probe_duration_ms(path: Union[str, Path]) -> int:
+    ffprobe = _need("ffprobe")
+    p = subprocess.run(
+        [ffprobe, "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", str(path)],
+        capture_output=True, text=True, check=True,
+    )
+    return int(round(float(p.stdout.strip()) * 1000))
+
+
+def default_cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(Path.home(), ".cache")
+    return Path(base) / "headvox"
+

headvox/video.py

@@ -0,0 +1,91 @@
+"""Put the voiceover onto a talking-head (or b-roll) video with ffmpeg."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional, Union
+
+from .synth import _need, probe_duration_ms
+
+
+def _has_filter(name: str) -> bool:
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        return False
+    p = subprocess.run([ffmpeg, "-hide_banner", "-filters"], capture_output=True, text=True)
+    return any(line.split()[1:2] == [name] for line in p.stdout.splitlines() if line.strip())
+
+
+def _escape_filter_path(p: Path) -> str:
+    s = str(p.resolve()).replace("\\", "/")
+    return s.replace(":", r"\:").replace("'", r"\'")
+
+
+def mux(
+    video: Union[str, Path],
+    voiceover: Union[str, Path],
+    out: Union[str, Path],
+    *,
+    subtitles: Optional[Union[str, Path]] = None,
+    burn: bool = False,
+    music: Optional[Union[str, Path]] = None,
+    music_volume: float = 0.12,
+    fit: str = "loop",
+) -> Path:
+    """Combine ``video`` with ``voiceover``.
+
+    fit:
+      * ``loop``  — loop the video until the voiceover ends (good for short
+        avatar clips or b-roll).
+      * ``audio`` — cut at whichever ends first.
+    subtitles + burn=False embeds a soft subtitle track (toggle in players);
+    burn=True renders them into the picture (needs ffmpeg built with libass).
+    music is looped under the voice and ducked with sidechain compression.
+    """
+    ffmpeg = _need("ffmpeg")
+    video, voiceover, out = Path(video), Path(voiceover), Path(out)
+    dur_s = probe_duration_ms(voiceover) / 1000.0
+
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-y"]
+    if fit == "loop":
+        cmd += ["-stream_loop", "-1"]
+    cmd += ["-i", str(video), "-i", str(voiceover)]
+    n_inputs = 2
+    if music:
+        cmd += ["-stream_loop", "-1", "-i", str(music)]
+        n_inputs += 1
+    sub_input = None
+    if subtitles and not burn:
+        cmd += ["-i", str(subtitles)]
+        sub_input = n_inputs
+        n_inputs += 1
+
+    filters = []
+    vmap = "0:v:0"
+    if subtitles and burn:
+        if not _has_filter("subtitles"):
+            raise RuntimeError("burning subtitles needs ffmpeg built with libass; use soft subtitles instead")
+        filters.append(f"[0:v]subtitles='{_escape_filter_path(Path(subtitles))}'[v]")
+        vmap = "[v]"
+    amap = "1:a:0"
+    if music:
+        filters.append(f"[2:a]volume={music_volume}[bg]")
+        filters.append("[bg][1:a]sidechaincompress=threshold=0.05:ratio=8:attack=20:release=400[duck]")
+        filters.append("[1:a][duck]amix=inputs=2:duration=first:dropout_transition=0[a]")
+        amap = "[a]"
+    if filters:
+        cmd += ["-filter_complex", ";".join(filters)]
+    cmd += ["-map", vmap, "-map", amap]
+    if sub_input is not None:
+        cmd += ["-map", f"{sub_input}:s:0"]
+    vcodec = ["-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p"]
+    cmd += vcodec + ["-c:a", "aac", "-b:a", "160k"]
+    if sub_input is not None:
+        cmd += ["-c:s", "mov_text" if out.suffix.lower() in (".mp4", ".mov", ".m4v") else "srt"]
+    cmd += ["-t", f"{dur_s:.3f}"] if fit == "loop" else ["-shortest"]
+    cmd += ["-movflags", "+faststart", str(out)]
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    if p.returncode != 0:
+        raise RuntimeError(f"ffmpeg mux failed:\n{p.stderr}")
+    return out

headvox-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: headvox
+Version: 0.1.0
+Summary: Turn a script into a talking-head voiceover with word-aligned SRT/VTT captions. Chinese, English and Japanese, free neural voices, one command.
+Author: HeadVox contributors
+License: MIT
+Keywords: tts,text-to-speech,voiceover,talking-head,subtitles,srt,vtt,captions,edge-tts,chinese-tts,ai-voice,video,ffmpeg,youtube,shorts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Japanese
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: edge
+Requires-Dist: edge-tts>=7.0; extra == "edge"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# HeadVox
+
+**Turn a script into a talking‑head voiceover — with word‑aligned captions — in one command.**
+
+HeadVox reads a plain‑text or Markdown script, speaks it with a neural TTS voice,
+stitches the clips into a single track with natural pauses, and writes
+**SRT + WebVTT captions that line up with the audio**, plus a JSON timing manifest
+you can feed to a talking‑head avatar or a video editor. Point it at a video clip
+and it muxes the voiceover on, loops the clip to length, and attaches the subtitles.
+
+Chinese, English and Japanese work out of the box (mixed CJK/Latin scripts
+segment correctly). The voices come from the free [`edge-tts`](https://github.com/rany2/edge-tts)
+service; HeadVox does **not** bundle or re‑host any model.
+
+```bash
+pip install "headvox[edge]"
+headvox script.md -o out/ --voice zh-female --video avatar.mp4
+# -> out/voiceover.mp3  out/voiceover.srt  out/voiceover.vtt
+#    out/voiceover.json out/voiceover.mp4
+```
+
+---
+
+## Why
+
+Making a short explainer or a "talking head" clip usually means three fiddly
+steps: generate the audio, hand‑time the subtitles, and mux it onto video.
+HeadVox does all three from one script and keeps them in sync, so the captions
+actually match the voice instead of drifting a few hundred milliseconds off.
+
+## Features
+
+- **One command, three outputs** — audio, captions (SRT **and** VTT), and a timing manifest.
+- **Word‑aligned captions.** With the `edge` backend HeadVox uses real word
+  boundaries, then breaks lines at punctuation and a character budget
+  (a CJK character counts as two columns) so no caption runs off screen.
+- **Pacing you control.** Sentence and paragraph pauses are automatic; drop
+  `[pause]`, `[pause 1.5s]` or `[pause 400ms]` anywhere for a beat.
+- **Markdown‑aware.** Headings, emphasis, links, code fences and lists are
+  reduced to the words a narrator would actually say.
+- **Pluggable backends.** `edge` (online neural voices) and `sine` (offline,
+  no network, used by the tests and for dry runs). Register your own in a few lines.
+- **Caches** every clip, so re‑rendering after a tiny script edit is nearly free.
+- **Video muxing** with optional looped, ducked background music, and either
+  soft subtitles (toggleable) or burned‑in captions.
+- **Pure‑Python, tiny deps.** Only `ffmpeg`/`ffprobe` on your PATH, and
+  `edge-tts` if you use the online voices.
+
+## Install
+
+```bash
+pip install "headvox[edge]"   # online neural voices
+pip install headvox           # library + offline 'sine' backend only
+```
+
+You also need **ffmpeg** (with `ffprobe`) on your PATH — <https://ffmpeg.org/download.html>.
+
+## Usage
+
+```bash
+# Simplest: script in, files out
+headvox talk.md -o out/
+
+# Pick a voice and tweak the delivery
+headvox talk.md -o out/ --voice en-female --rate +6 --pitch +1
+
+# Put it on a clip, loop the clip to the voiceover length, duck some music under it
+headvox talk.md -o out/ --video avatar.mp4 --music bed.mp3
+
+# Burn captions into the picture instead of a soft track
+headvox talk.md -o out/ --video avatar.mp4 --burn-subs
+
+# See how the script will be segmented without calling any TTS
+headvox talk.md --dry-run
+```
+
+Voice presets: `zh-female`, `zh-male`, `en-female`, `en-male`, `ja-female`, `ja-male`
+— or pass any `edge-tts` voice id directly (e.g. `--voice zh-CN-YunxiNeural`).
+Run `edge-tts --list-voices` to see them all. Behind a proxy? Use `--proxy`
+or set `HEADVOX_PROXY`.
+
+### As a library
+
+```python
+from headvox import synthesize, Script, VoiceSettings
+
+res = synthesize(
+    Script.from_file("talk.md"),
+    "out/",
+    backend="edge",
+    settings=VoiceSettings(voice="zh-CN-XiaoxiaoNeural", rate_pct=5),
+)
+print(res.duration_ms, "ms,", len(res.cues), "captions")
+for cue in res.cues:
+    print(cue.start_ms, cue.text)
+```
+
+`synthesize()` returns paths to the audio, SRT, VTT and manifest, the total
+duration, and the per‑segment word timings.
+
+## Timing manifest
+
+`voiceover.json` holds everything downstream tools need to drive an avatar or
+re‑style captions:
+
+```json
+{
+  "tool": "headvox",
+  "backend": "edge",
+  "duration_ms": 19600,
+  "segments": [
+    {"index": 0, "text": "Hi everyone, and welcome back.",
+     "start_ms": 2398, "end_ms": 4049,
+     "words": [{"text": "Hi", "start_ms": 2398, "end_ms": 2560}, ...]}
+  ],
+  "cues": [{"index": 1, "start_ms": 262, "end_ms": 1573, "text": "HeadVox demo"}]
+}
+```
+
+## Write your own backend
+
+```python
+from headvox.backends import SegmentAudio, WordMark, register_backend
+
+class MyBackend:
+    name = "mine"
+    def synthesize_segment(self, text, settings):
+        audio, fmt, dur = my_tts(text, settings.voice)   # bytes, "wav"/"mp3", ms
+        return SegmentAudio(audio, fmt, dur, [WordMark("hi", 0, 200)])
+
+register_backend("mine", lambda **kw: MyBackend())
+```
+
+Then `headvox script.md -b mine`.
+
+## How it works
+
+1. **Parse** the script to speech segments, stripping Markdown and honouring pause directives.
+2. **Synthesize** each segment through the chosen backend (cached by text + voice settings).
+3. **Assemble** one 24 kHz track, trimming the padding some engines add so your pauses are exact.
+4. **Caption** from the word boundaries, breaking lines at punctuation within a width budget.
+5. **Mux** (optional) onto video with ffmpeg, with ducked music and soft or burned‑in subtitles.
+
+## Development
+
+```bash
+git clone <your fork>
+cd headvox
+pip install -e ".[dev]"
+pytest          # the suite runs fully offline via the 'sine' backend
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). HeadVox is original work and is not affiliated
+with Microsoft or the `edge-tts` project; it simply uses `edge-tts` as one
+optional backend.

headvox-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+headvox/__init__.py,sha256=3l5lIathY6eDxXrNeOjviV23v2Ymso9cAo2BplSxe6M,969
+headvox/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+headvox/captions.py,sha256=eec3xfhZYNQyxeC_DOgl_5sPf3zW3Tp44dl1UZEI7go,4959
+headvox/cli.py,sha256=CoaQaybkrNJKUNizKr6M5QI1MQiHbUMXcNrb1UBGwYo,5749
+headvox/script.py,sha256=-sbdzSNfR6Y4xNQTv77VmLeUbSx4IXV5Jl-waf57mJs,7951
+headvox/synth.py,sha256=Rb_qp1HH_ZVfnEV2xbH-Gw3vOvqHfWrta7_rNgLYWME,8720
+headvox/video.py,sha256=tMr5o2AyjtXPolZcanw51ZZ7Jlkr656XpnEcNnSJ_aU,3377
+headvox/backends/__init__.py,sha256=SBCOw96D-A2LF29Hz6l5eaDQtzoj8LHsMkj39d-yJfk,1927
+headvox/backends/edge.py,sha256=DE8tQBmdyIb_bJuwgRfp9WZsHWfi4oXfWhCIuczaTlY,2385
+headvox/backends/sine.py,sha256=QwnPk10fRZkIhEnfcn9tLh0JDinEFIWwTzfssd-_Q8U,2098
+headvox-0.1.0.dist-info/licenses/LICENSE,sha256=EHUdO9_J8eAO-BfY6sL-fv8iTAVy6nYBEETrkiPMAzM,1077
+headvox-0.1.0.dist-info/METADATA,sha256=hYzosNdyoLs5eaOVMk0l98EAoBIjEoB1p3A9x_bMZlo,6828
+headvox-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+headvox-0.1.0.dist-info/entry_points.txt,sha256=O41NzOvsII-JtoWTYf-HK-BGD1ZUhHfKtbCTvh7SZfM,45
+headvox-0.1.0.dist-info/top_level.txt,sha256=DzKGUvDHbft-TiPJtoYdqagkSaY9od379BiWMvB48Us,8
+headvox-0.1.0.dist-info/RECORD,,

headvox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

headvox-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+headvox = headvox.cli:main

headvox-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeadVox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

headvox-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+headvox