headvox 0.1.0__tar.gz

headvox-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,157 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "headvox"
+version = "0.1.0"
+description = "Turn a script into a talking-head voiceover with word-aligned SRT/VTT captions. Chinese, English and Japanese, free neural voices, one command."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "HeadVox contributors" }]
+keywords = [
+  "tts", "text-to-speech", "voiceover", "talking-head", "subtitles", "srt", "vtt",
+  "captions", "edge-tts", "chinese-tts", "ai-voice", "video", "ffmpeg", "youtube", "shorts",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Chinese (Simplified)",
+  "Natural Language :: English",
+  "Natural Language :: Japanese",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Multimedia :: Video",
+]
+dependencies = []
+
+[project.optional-dependencies]
+edge = ["edge-tts>=7.0"]
+dev = ["pytest>=7"]
+
+[project.scripts]
+headvox = "headvox.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

headvox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

headvox-0.1.0/src/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-0.1.0/src/headvox/__main__.py

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

headvox-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)