retake-vo 0.1.0__tar.gz

retake_vo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragea team
+
+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.

retake_vo-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: retake-vo
+Version: 0.1.0
+Summary: Fix a flubbed voiceover line in your own voice: re-voice one sentence and splice it in with matched loudness, EQ and room tone. Open-source Overdub alternative (CLI + MCP), powered by Miragea.
+Author: Miragea team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yyert123/retake
+Project-URL: Source, https://github.com/yyert123/retake
+Project-URL: Issues, https://github.com/yyert123/retake/issues
+Project-URL: Demo, https://huggingface.co/spaces/headvox/retake
+Project-URL: Voice engine, https://miragea.ai
+Keywords: voiceover,overdub,voice cloning,fix voiceover mistake,audio editing,podcast editing,text-based audio editing,descript alternative,mcp,mcp-server,tts,miragea
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Editors
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: hf
+Requires-Dist: huggingface_hub>=0.23; extra == "hf"
+Provides-Extra: all
+Requires-Dist: mcp>=1.2; extra == "all"
+Requires-Dist: huggingface_hub>=0.23; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Retake: fix a voiceover mistake in your own voice (open-source Overdub alternative)
+
+**Said "Wednesday" instead of "Thursday"? Don't re-record.** Retake re-voices only the sentence you
+changed, in the same voice, and splices it back into your recording with matched loudness, tone (EQ) and
+room tone. Works with any editor (Premiere, Resolve, Final Cut, Audacity, CapCut) because it simply gives
+you a fixed WAV plus edit markers. CLI for humans, MCP server for AI agents. Voice engine:
+[Miragea](https://miragea.ai).
+
+```bash
+pip install retake-vo
+export MIRAGEA_API_KEY=your_key            # https://miragea.ai
+retake transcribe take.wav                 # numbered sentences + timestamps (cached, pay once)
+retake fix take.wav --replace "Wednesday" --with "Thursday" --voice YOUR_VOICE_ID
+# -> take.fixed.wav, take.fixed.edits.json, take.fixed.markers.csv
+```
+
+<!-- mcp-name: io.github.yyert123/retake -->
+
+> **Status (v0.1.0, 2026-11-08):** transcription, sentence finding, pause-snapped cut points, EQ/loudness/
+> room-tone matching, splicing, exports, CLI and MCP server are tested (9 offline tests + live Miragea
+> transcription on real recordings). A listen-to-it before/after demo will be added to the
+> [demo page](https://huggingface.co/spaces/headvox/retake) as soon as the voice side is verified end to end.
+
+## What it does automatically
+
+1. **Transcribes** the take with Miragea speech recognition and splits it into sentences (initials like
+   "O. Henry" handled). The transcript is cached next to the file, so later fixes cost nothing extra.
+2. **Finds the sentence** that contains your words; refuses to guess if they appear twice.
+3. **Finds real cut points**: sentence edges are snapped to the quietest stretch of the pause around them,
+   so cuts never land inside a word, even though recognition segments can split words.
+4. **Re-voices** the edited sentence with Miragea in your saved voice, or cloned from a reference clip.
+5. **Matches it to the take**: trims silence, matches the long-term spectrum (EQ, 1/3-octave smoothed,
+   clamped), matches speech loudness, lays your own room tone under it, equal-power crossfades the seams.
+6. **Exports** a 24-bit WAV at the original sample rate and channels, a JSON edit list (old/new text,
+   old/new times, gain), and a CSV of markers you can import into your editor. The original file is never
+   modified.
+
+## Why Retake (honest comparison)
+
+| | **Retake** | Descript Overdub / Regenerate | DaVinci Resolve 21 Speech Generator | Reasonate (REAPER) | Manual ElevenLabs workflow |
+|---|---|---|---|---|---|
+| Price | Free, MIT; pay-as-you-go voice | Subscription | Resolve Studio ($295) | Free + ElevenLabs plan | ElevenLabs plan |
+| Works with your editor | Any (WAV + markers) | Only inside Descript | Only inside Resolve | Only inside REAPER | Any, by hand |
+| Finds the line for you | Yes, by words or line number | Yes | No, you place it | Yes (forced alignment) | No |
+| Cut points at real pauses | Automatic | Automatic | Manual | Automatic | Manual |
+| Loudness match | Automatic | Automatic | Manual | Automatic | Manual |
+| EQ / tone match | Automatic | Partial | Manual | No | Manual (the most-cited pain) |
+| Room tone under patch | Automatic | Partial | No | No | Manual |
+| Length per fix | Up to 2,000 characters | - | ~350 characters | - | - |
+| AI agents (MCP) | Yes, `retake-mcp` | No | No | No | No |
+| Voice engine | Miragea (saved voice or clone) | Descript | Resolve built-in voices / custom WAV | ElevenLabs only | ElevenLabs |
+
+Sources: Resolve limits per [davinciresolveclub.com](https://davinciresolveclub.com/davinci-resolve-text-to-speech/);
+Reasonate per its [README](https://github.com/b451c/Reasonate); the EQ-matching pain per an
+[r/editors thread](https://www.reddit.com/r/editors/comments/15s6lau/).
+
+## Choosing the voice
+
+| Option | When | Example |
+|---|---|---|
+| `--voice ID` | You saved your voice in your Miragea account (best: consistent, no upload) | `--voice v_abc123` |
+| `--ref-url URL --ref-text "..."` | You have a public clip of the same speaker; giving its exact words uses the cheaper 1x rate | `--ref-url https://raw.githubusercontent.com/you/voice/main/me.wav` |
+| `--host hf:user/repo` | Fully automatic: Retake cuts ~9 s of untouched speech from the take and uploads it to **your public** Hugging Face dataset (needs `pip install "retake-vo[hf]"` and `HF_TOKEN`) | `--host hf:me/voice-refs` |
+
+Reference URLs must be public, served directly (no long signed redirects) and under 1,024 characters.
+Miragea has agreed to add a direct upload endpoint; when it ships, Retake will upload the clip from your
+take itself and these options become optional.
+
+## More examples
+
+```bash
+# several fixes in one pass (each sentence re-voiced once)
+retake fix vo.mp3 --replace "twenty twenty-five" --with "twenty twenty-six" --replace "Jon" --with "John" --voice v1
+
+# rewrite a whole sentence by its number from `retake transcribe`
+retake fix vo.wav --line 7 --say "Click Export, then choose MP4." --voice v1 -o vo.v2.wav
+
+# keep each generated patch as its own file (for manual placement in a DAW)
+retake fix vo.wav --replace "fourty" --with "forty" --voice v1 --keep-patches
+```
+
+## Use it from Claude, Cursor or Codex (MCP)
+
+```bash
+pip install "retake-vo[mcp]"
+```
+
+```json
+{ "mcpServers": { "retake": { "command": "retake-mcp", "env": { "MIRAGEA_API_KEY": "your_key" } } } }
+```
+
+Then ask: *"In ~/Videos/launch/vo.wav, change 'Wednesday' to 'Thursday' using my voice v_abc123."*
+Tools: `transcribe_take(path)` and `fix_line(path, old_words, new_words | line, new_sentence, voice_id | ref_url | host)`.
+
+## Python API
+
+```python
+from retake import fix, transcribe
+lines = transcribe("take.wav")["sentences"]
+res = fix("take.wav", [("Wednesday", "Thursday")], voice="v_abc123")
+print(res.output, res.edits[0].new_start)
+```
+
+## FAQ
+
+**Will people hear the patch?** Retake does everything an editor would do by hand: cut in the pause,
+match level, tone and room noise, crossfade. Quality still depends on the clone; a saved Miragea voice
+made from a clean 10-20 s sample of the same mic gives the closest match. Listen before you publish.
+
+**Does it change the rest of my audio?** No. Everything outside the edited sentences is copied sample for
+sample; later audio shifts by the length difference, which the edit list and markers report.
+
+**What does it cost?** Transcription: 3 Miragea points per second of audio, once per file (cached).
+Each fix: Miragea's per-character rate for the new sentence (1x with a saved voice or exact reference text).
+
+**Is my key safe?** It is read from `MIRAGEA_API_KEY` only, never logged or written to disk.
+
+**Can I fix someone else's recording?** Only with the speaker's consent. Retake is built for fixing your own
+narration or a talent's read you are licensed to edit.
+
+**Which formats?** Anything ffmpeg reads (WAV, MP3, M4A, FLAC, MP4, MOV...). Output is WAV by default; use
+`-o fixed.mp3` for MP3.
+
+**Error messages?** Every error says what went wrong and how to fix it (missing key, ffmpeg not installed,
+word not found, word found twice, balance, rate limit). Re-running is always safe.
+
+## Requirements
+
+Python 3.9+, ffmpeg on PATH, a [Miragea](https://miragea.ai) API key.
+
+## Related
+
+- [miragea-skills](https://github.com/yyert123/miragea-skills): Agent Skills for captions and Remotion narration.
+- [HeadVox](https://github.com/yyert123/headvox): script to voiceover with word-aligned captions.
+
+MIT License.

retake_vo-0.1.0/README.md

@@ -0,0 +1,136 @@
+# Retake: fix a voiceover mistake in your own voice (open-source Overdub alternative)
+
+**Said "Wednesday" instead of "Thursday"? Don't re-record.** Retake re-voices only the sentence you
+changed, in the same voice, and splices it back into your recording with matched loudness, tone (EQ) and
+room tone. Works with any editor (Premiere, Resolve, Final Cut, Audacity, CapCut) because it simply gives
+you a fixed WAV plus edit markers. CLI for humans, MCP server for AI agents. Voice engine:
+[Miragea](https://miragea.ai).
+
+```bash
+pip install retake-vo
+export MIRAGEA_API_KEY=your_key            # https://miragea.ai
+retake transcribe take.wav                 # numbered sentences + timestamps (cached, pay once)
+retake fix take.wav --replace "Wednesday" --with "Thursday" --voice YOUR_VOICE_ID
+# -> take.fixed.wav, take.fixed.edits.json, take.fixed.markers.csv
+```
+
+<!-- mcp-name: io.github.yyert123/retake -->
+
+> **Status (v0.1.0, 2026-11-08):** transcription, sentence finding, pause-snapped cut points, EQ/loudness/
+> room-tone matching, splicing, exports, CLI and MCP server are tested (9 offline tests + live Miragea
+> transcription on real recordings). A listen-to-it before/after demo will be added to the
+> [demo page](https://huggingface.co/spaces/headvox/retake) as soon as the voice side is verified end to end.
+
+## What it does automatically
+
+1. **Transcribes** the take with Miragea speech recognition and splits it into sentences (initials like
+   "O. Henry" handled). The transcript is cached next to the file, so later fixes cost nothing extra.
+2. **Finds the sentence** that contains your words; refuses to guess if they appear twice.
+3. **Finds real cut points**: sentence edges are snapped to the quietest stretch of the pause around them,
+   so cuts never land inside a word, even though recognition segments can split words.
+4. **Re-voices** the edited sentence with Miragea in your saved voice, or cloned from a reference clip.
+5. **Matches it to the take**: trims silence, matches the long-term spectrum (EQ, 1/3-octave smoothed,
+   clamped), matches speech loudness, lays your own room tone under it, equal-power crossfades the seams.
+6. **Exports** a 24-bit WAV at the original sample rate and channels, a JSON edit list (old/new text,
+   old/new times, gain), and a CSV of markers you can import into your editor. The original file is never
+   modified.
+
+## Why Retake (honest comparison)
+
+| | **Retake** | Descript Overdub / Regenerate | DaVinci Resolve 21 Speech Generator | Reasonate (REAPER) | Manual ElevenLabs workflow |
+|---|---|---|---|---|---|
+| Price | Free, MIT; pay-as-you-go voice | Subscription | Resolve Studio ($295) | Free + ElevenLabs plan | ElevenLabs plan |
+| Works with your editor | Any (WAV + markers) | Only inside Descript | Only inside Resolve | Only inside REAPER | Any, by hand |
+| Finds the line for you | Yes, by words or line number | Yes | No, you place it | Yes (forced alignment) | No |
+| Cut points at real pauses | Automatic | Automatic | Manual | Automatic | Manual |
+| Loudness match | Automatic | Automatic | Manual | Automatic | Manual |
+| EQ / tone match | Automatic | Partial | Manual | No | Manual (the most-cited pain) |
+| Room tone under patch | Automatic | Partial | No | No | Manual |
+| Length per fix | Up to 2,000 characters | - | ~350 characters | - | - |
+| AI agents (MCP) | Yes, `retake-mcp` | No | No | No | No |
+| Voice engine | Miragea (saved voice or clone) | Descript | Resolve built-in voices / custom WAV | ElevenLabs only | ElevenLabs |
+
+Sources: Resolve limits per [davinciresolveclub.com](https://davinciresolveclub.com/davinci-resolve-text-to-speech/);
+Reasonate per its [README](https://github.com/b451c/Reasonate); the EQ-matching pain per an
+[r/editors thread](https://www.reddit.com/r/editors/comments/15s6lau/).
+
+## Choosing the voice
+
+| Option | When | Example |
+|---|---|---|
+| `--voice ID` | You saved your voice in your Miragea account (best: consistent, no upload) | `--voice v_abc123` |
+| `--ref-url URL --ref-text "..."` | You have a public clip of the same speaker; giving its exact words uses the cheaper 1x rate | `--ref-url https://raw.githubusercontent.com/you/voice/main/me.wav` |
+| `--host hf:user/repo` | Fully automatic: Retake cuts ~9 s of untouched speech from the take and uploads it to **your public** Hugging Face dataset (needs `pip install "retake-vo[hf]"` and `HF_TOKEN`) | `--host hf:me/voice-refs` |
+
+Reference URLs must be public, served directly (no long signed redirects) and under 1,024 characters.
+Miragea has agreed to add a direct upload endpoint; when it ships, Retake will upload the clip from your
+take itself and these options become optional.
+
+## More examples
+
+```bash
+# several fixes in one pass (each sentence re-voiced once)
+retake fix vo.mp3 --replace "twenty twenty-five" --with "twenty twenty-six" --replace "Jon" --with "John" --voice v1
+
+# rewrite a whole sentence by its number from `retake transcribe`
+retake fix vo.wav --line 7 --say "Click Export, then choose MP4." --voice v1 -o vo.v2.wav
+
+# keep each generated patch as its own file (for manual placement in a DAW)
+retake fix vo.wav --replace "fourty" --with "forty" --voice v1 --keep-patches
+```
+
+## Use it from Claude, Cursor or Codex (MCP)
+
+```bash
+pip install "retake-vo[mcp]"
+```
+
+```json
+{ "mcpServers": { "retake": { "command": "retake-mcp", "env": { "MIRAGEA_API_KEY": "your_key" } } } }
+```
+
+Then ask: *"In ~/Videos/launch/vo.wav, change 'Wednesday' to 'Thursday' using my voice v_abc123."*
+Tools: `transcribe_take(path)` and `fix_line(path, old_words, new_words | line, new_sentence, voice_id | ref_url | host)`.
+
+## Python API
+
+```python
+from retake import fix, transcribe
+lines = transcribe("take.wav")["sentences"]
+res = fix("take.wav", [("Wednesday", "Thursday")], voice="v_abc123")
+print(res.output, res.edits[0].new_start)
+```
+
+## FAQ
+
+**Will people hear the patch?** Retake does everything an editor would do by hand: cut in the pause,
+match level, tone and room noise, crossfade. Quality still depends on the clone; a saved Miragea voice
+made from a clean 10-20 s sample of the same mic gives the closest match. Listen before you publish.
+
+**Does it change the rest of my audio?** No. Everything outside the edited sentences is copied sample for
+sample; later audio shifts by the length difference, which the edit list and markers report.
+
+**What does it cost?** Transcription: 3 Miragea points per second of audio, once per file (cached).
+Each fix: Miragea's per-character rate for the new sentence (1x with a saved voice or exact reference text).
+
+**Is my key safe?** It is read from `MIRAGEA_API_KEY` only, never logged or written to disk.
+
+**Can I fix someone else's recording?** Only with the speaker's consent. Retake is built for fixing your own
+narration or a talent's read you are licensed to edit.
+
+**Which formats?** Anything ffmpeg reads (WAV, MP3, M4A, FLAC, MP4, MOV...). Output is WAV by default; use
+`-o fixed.mp3` for MP3.
+
+**Error messages?** Every error says what went wrong and how to fix it (missing key, ffmpeg not installed,
+word not found, word found twice, balance, rate limit). Re-running is always safe.
+
+## Requirements
+
+Python 3.9+, ffmpeg on PATH, a [Miragea](https://miragea.ai) API key.
+
+## Related
+
+- [miragea-skills](https://github.com/yyert123/miragea-skills): Agent Skills for captions and Remotion narration.
+- [HeadVox](https://github.com/yyert123/headvox): script to voiceover with word-aligned captions.
+
+MIT License.

retake_vo-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "retake-vo"
+version = "0.1.0"
+description = "Fix a flubbed voiceover line in your own voice: re-voice one sentence and splice it in with matched loudness, EQ and room tone. Open-source Overdub alternative (CLI + MCP), powered by Miragea."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Miragea team" }]
+keywords = ["voiceover", "overdub", "voice cloning", "fix voiceover mistake", "audio editing", "podcast editing",
+            "text-based audio editing", "descript alternative", "mcp", "mcp-server", "tts", "miragea"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio :: Editors",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+]
+dependencies = ["numpy>=1.22"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.2"]
+hf = ["huggingface_hub>=0.23"]
+all = ["mcp>=1.2", "huggingface_hub>=0.23"]
+dev = ["pytest>=7"]
+
+[project.scripts]
+retake = "retake.cli:main"
+retake-mcp = "retake.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/yyert123/retake"
+Source = "https://github.com/yyert123/retake"
+Issues = "https://github.com/yyert123/retake/issues"
+Demo = "https://huggingface.co/spaces/headvox/retake"
+"Voice engine" = "https://miragea.ai"
+
+[tool.setuptools.packages.find]
+where = ["src"]

retake_vo-0.1.0/setup.cfg

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

retake_vo-0.1.0/src/retake/__init__.py

@@ -0,0 +1,4 @@
+"""Retake: fix a flubbed voiceover line in your own voice (Miragea engine)."""
+__version__ = "0.1.0"
+
+from .core import fix, transcribe  # noqa: E402,F401

retake_vo-0.1.0/src/retake/__main__.py

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

retake_vo-0.1.0/src/retake/align.py

@@ -0,0 +1,131 @@
+"""Turn Miragea's segment-level transcript into sentence-level timings.
+
+Miragea returns the full transcript plus short segments whose boundaries can
+fall mid-word ("cen" | "ts"). We locate every segment inside the full text,
+interpolate a time for every character, then split the text into sentences.
+Sentence boundaries are later snapped to real pauses in the audio (see dsp).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+
+_SENT_RE = re.compile(r"[^.!?…]+(?:[.!?…]+[\"'”’)\]]*|$)", re.S)
+
+
+@dataclass
+class Sentence:
+    index: int
+    text: str
+    start: float
+    end: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _norm(ch: str) -> str:
+    return ch.lower() if ch.isalnum() else ""
+
+
+def char_times(text: str, segments: list[dict]) -> list[float | None]:
+    """Return an estimated time (seconds) for each character of ``text``."""
+    times: list[float | None] = [None] * (len(text) + 1)
+    # Build an index of alphanumeric characters of the full text.
+    alnum_pos = [i for i, c in enumerate(text) if c.isalnum()]
+    alnum_str = "".join(text[i].lower() for i in alnum_pos)
+    cursor = 0
+    for seg in segments:
+        s_txt = "".join(_norm(c) for c in seg.get("text", ""))
+        if not s_txt:
+            continue
+        found = alnum_str.find(s_txt, cursor)
+        if found < 0:  # tolerate small differences: anchor on the first 4 chars
+            found = alnum_str.find(s_txt[:4], cursor)
+            if found < 0:
+                continue
+        a, b = found, min(found + len(s_txt), len(alnum_pos)) - 1
+        n = max(1, b - a)
+        for k in range(a, b + 1):
+            frac = (k - a) / n
+            times[alnum_pos[k]] = float(seg["start"]) + frac * (float(seg["end"]) - float(seg["start"]))
+        cursor = b + 1
+    # Fill gaps by linear interpolation between known points.
+    known = [i for i, t in enumerate(times) if t is not None]
+    if not known:
+        return times
+    for i in range(len(times)):
+        if times[i] is None:
+            left = max((k for k in known if k < i), default=None)
+            right = min((k for k in known if k > i), default=None)
+            if left is None:
+                times[i] = times[right]
+            elif right is None:
+                times[i] = times[left]
+            else:
+                f = (i - left) / (right - left)
+                times[i] = times[left] + f * (times[right] - times[left])
+    return times
+
+
+_ABBREV = re.compile(r"(?:\b[A-Z]|\b(?:Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St|vs|etc|e\.g|i\.e|No|Inc|Ltd|U\.S))\.$")
+
+
+def split_sentences(text: str) -> list[tuple[int, int]]:
+    """Return (start, end) character spans of sentences, whitespace-trimmed.
+
+    Initials and common abbreviations ("O. Henry", "Dr. Smith") do not end a sentence."""
+    spans: list[tuple[int, int]] = []
+    for m in _SENT_RE.finditer(text):
+        a, b = m.start(), m.end()
+        while a < b and text[a].isspace():
+            a += 1
+        while b > a and text[b - 1].isspace():
+            b -= 1
+        if a < b and any(c.isalnum() for c in text[a:b]):
+            if spans and _ABBREV.search(text[spans[-1][0]:spans[-1][1]]):
+                spans[-1] = (spans[-1][0], b)
+            else:
+                spans.append((a, b))
+    return spans
+
+
+def sentences_from_transcript(transcript: dict, duration: float | None = None) -> list[Sentence]:
+    text = transcript.get("text") or " ".join(s.get("text", "") for s in transcript.get("segments", []))
+    segs = transcript.get("segments", [])
+    times = char_times(text, segs)
+    out = []
+    for idx, (a, b) in enumerate(split_sentences(text)):
+        first = next(i for i in range(a, b) if text[i].isalnum())
+        last = max(i for i in range(a, b) if text[i].isalnum())
+        start, end = times[first], times[last]
+        if start is None or end is None:
+            continue
+        out.append(Sentence(idx, text[a:b], round(start, 3), round(end, 3)))
+    if out and segs:  # the last character is spoken a little before its segment ends
+        out[-1].end = round(max(out[-1].end, float(segs[-1]["end"])), 3)
+    if duration:
+        for s in out:
+            s.end = min(s.end, duration)
+    return out
+
+
+def find_sentence(sentences: list[Sentence], needle: str) -> Sentence:
+    """Find the one sentence that contains ``needle`` (case/punctuation-insensitive)."""
+    key = "".join(_norm(c) for c in needle)
+    hits = [s for s in sentences if key and key in "".join(_norm(c) for c in s.text)]
+    if not hits:
+        raise LookupError(f'"{needle}" was not found in the transcript. Run `retake transcribe` to see the exact words.')
+    if len(hits) > 1:
+        lines = "; ".join(f"#{s.index} at {s.start:.1f}s" for s in hits)
+        raise LookupError(f'"{needle}" appears in {len(hits)} sentences ({lines}). Add more words or use --line N.')
+    return hits[0]
+
+
+def apply_replacement(sentence: str, old: str, new: str) -> str:
+    """Replace ``old`` with ``new`` inside ``sentence``, ignoring case and spacing differences."""
+    pattern = r"\s+".join(re.escape(w) for w in old.split())
+    result, n = re.subn(pattern, new, sentence, count=1, flags=re.I)
+    if n == 0:
+        raise LookupError(f'"{old}" was not found verbatim in: {sentence}')
+    return result

retake_vo-0.1.0/src/retake/cli.py

@@ -0,0 +1,75 @@
+"""retake - fix a flubbed voiceover line in your own voice, from the terminal."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import fix, transcribe
+
+
+def _fmt(t: float) -> str:
+    return f"{int(t // 60):02d}:{t % 60:05.2f}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="retake",
+        description="Fix a wrong word in a recorded voiceover by re-voicing only that sentence in the same voice "
+                    "(engine: Miragea, https://miragea.ai). Loudness, EQ and room tone are matched automatically.")
+    p.add_argument("--version", action="version", version=f"retake {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    t = sub.add_parser("transcribe", help="list the take's sentences with line numbers and timestamps")
+    t.add_argument("take", type=Path)
+    t.add_argument("--force", action="store_true", help="ignore the cached transcript and pay to re-transcribe")
+
+    f = sub.add_parser("fix", help="re-voice the sentence(s) you changed and splice them in")
+    f.add_argument("take", type=Path)
+    f.add_argument("--replace", action="append", default=[], metavar="OLD", help="words to change (repeatable)")
+    f.add_argument("--with", dest="with_", action="append", default=[], metavar="NEW", help="replacement words")
+    f.add_argument("--line", action="append", type=int, default=[], metavar="N", help="sentence number to rewrite")
+    f.add_argument("--say", action="append", default=[], metavar="TEXT", help="full new text for --line")
+    f.add_argument("-o", "--output", type=Path, help="output file (default: <take>.fixed.wav)")
+    v = f.add_argument_group("voice (pick one)")
+    v.add_argument("--voice", help="voice id saved in your Miragea account")
+    v.add_argument("--ref-url", help="public URL of a clip of the same speaker")
+    v.add_argument("--ref-text", help="exact words spoken in --ref-url (cheaper: 1x instead of 3x)")
+    v.add_argument("--host", metavar="hf:USER/REPO",
+                   help="auto-cut a reference clip from this take and host it on your PUBLIC Hugging Face dataset")
+    f.add_argument("--model", default="expressive", choices=["expressive", "standard"])
+    f.add_argument("--no-room-tone", action="store_true")
+    f.add_argument("--no-eq", action="store_true")
+    f.add_argument("--keep-patches", action="store_true", help="also save each generated patch as its own file")
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "transcribe":
+            data = transcribe(a.take, force=a.force)
+            for s in data["sentences"]:
+                print(f"[{s['index']:>3}] {_fmt(s['start'])}-{_fmt(s['end'])}  {s['text']}")
+            print(f"\n{len(data['sentences'])} lines, cached in {a.take.name}.retake.json (re-runs are free).",
+                  file=sys.stderr)
+            return 0
+        if len(a.replace) != len(a.with_):
+            p.error("every --replace needs a matching --with")
+        if len(a.line) != len(a.say):
+            p.error("every --line needs a matching --say")
+        res = fix(a.take, list(zip(a.replace, a.with_)), lines=list(zip(a.line, a.say)), output=a.output,
+                  voice=a.voice, ref_url=a.ref_url, ref_text=a.ref_text, host=a.host, model=a.model,
+                  room=not a.no_room_tone, eq=not a.no_eq, keep_patches=a.keep_patches)
+        for e in res.edits:
+            print(f"fixed {_fmt(e.start)}: \"{e.old_text}\"\n   -> \"{e.new_text}\"  (gain {e.gain_db:+.1f} dB, "
+                  f"now at {_fmt(e.new_start)})")
+        print(f"\nwrote {res.output}\n      {res.report}\n      {res.markers} (import as markers in your editor)")
+        return 0
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001 - show a clean message, never a traceback, to end users
+        print(f"retake: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())