miragea-dub 0.1.0__tar.gz

miragea_dub-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/
+*.dub/

miragea_dub-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-11-11
+- First release: prepare / translate / render / dub CLI, MCP server (6 tools), Agent Skill.
+- Miragea transcription regrouped into whole sentences; built-in GPU-free diarization; per-speaker voice cloning from the video.
+- Timing fit with speed limit and shorten report; ducked, file, Demucs or removed background; dubbed MP4, M4A, SRT, VTT.
+- Reference hosting with automatic fallback (litterbox, uguu, tmpfiles).

miragea_dub-0.1.0/LICENSE

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

miragea_dub-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: miragea-dub
+Version: 0.1.0
+Summary: Open-source multi-speaker video dubbing: transcribe, find who speaks when, translate, and re-voice every speaker with their own cloned voice, with timing fit, ducked background, dubbed MP4, multi-language audio track and SRT/VTT. CLI + MCP server + Agent Skill, voiced by Miragea.
+Project-URL: Homepage, https://codeberg.org/miragea-voice/miragea-dub
+Project-URL: Documentation, https://codeberg.org/miragea-voice/miragea-dub#readme
+Project-URL: Issues, https://codeberg.org/miragea-voice/miragea-dub/issues
+Project-URL: Miragea API, https://miragea.ai
+Author: miragea-dub contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skill,ai-dubbing,ai-voice-over,dubbing,elevenlabs-dubbing-alternative,heygen-alternative,localization,mcp,mcp-server,miragea,multi-speaker,speaker-diarization,srt,subtitles,text-to-speech,video-dubbing,video-translation,voice-cloning,youtube-multi-language-audio
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Video
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.9
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2
+Provides-Extra: demucs
+Requires-Dist: demucs>=4; extra == 'demucs'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: pyannote
+Requires-Dist: pyannote-audio>=3.1; extra == 'pyannote'
+Provides-Extra: whisper
+Requires-Dist: faster-whisper>=1.0; extra == 'whisper'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/cover.png" alt="miragea-dub banner: two speakers' lanes in English above the same two lanes dubbed into Spanish, each speaker keeping their own voice" width="100%">
+</p>
+
+# miragea-dub: multi-speaker AI video dubbing, open source
+
+**miragea-dub is an open-source command-line tool, MCP server and Agent Skill that dubs a video into another language while keeping a separate cloned voice for every speaker.** It transcribes the video, works out who speaks when, lets you (or your AI agent) translate each line, clones every speaker's voice from the video itself with the [Miragea](https://miragea.ai) voice API, fits each translated line into the original timing, ducks the original audio underneath, and exports a dubbed MP4, a stand-alone audio track for YouTube multi-language audio, and SRT/VTT subtitles. MIT licensed, Python 3.10+, works offline in `demo` mode.
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) [![tests](https://img.shields.io/badge/tests-28%20passing-brightgreen)](tests)
+
+## Demo: a real two-speaker dub
+
+An English clip with two speakers (Ana and Ben) dubbed into Spanish. Both voices were cloned from the clip itself, nothing was pre-recorded:
+
+- [Watch the dubbed MP4 (Spanish, burned-in subtitles, original English kept as 2nd audio track)](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/examples/demo-dubbed-es.mp4)
+- [Original English audio](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/examples/real/original-audio.mp3)
+- [Spanish subtitles](examples/output/two-voices.es.srt) and [timing report](examples/output/two-voices.es.report.json)
+
+![Animated preview of the Spanish dub with burned-in subtitles and a waveform](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/demo.gif)
+
+Round-trip check: transcribing the Spanish track again returns the translated script almost word for word, and the diarizer assigned all 6 lines to the right speaker.
+
+## Quick start
+
+```bash
+pipx install miragea-dub          # or: uvx miragea-dub ...   (needs ffmpeg on PATH)
+miragea-dub demo                  # offline end-to-end run with test tones, no key needed
+export MIRAGEA_API_KEY=...        # create a key at https://miragea.ai/workspace/api
+miragea-dub doctor                # checks ffmpeg, key, connectivity
+
+# 1) transcribe + find speakers -> dub.json
+miragea-dub prepare interview.mp4 --to es --speakers 2
+# 2) translate: let your AI agent fill "translation" in dub.json, or use any OpenAI-compatible LLM
+miragea-dub translate interview.dub/dub.json --translator openai
+# 3) voice, fit, mix, export
+miragea-dub render interview.dub/dub.json --model expressive
+# or all in one:  miragea-dub dub interview.mp4 --to es --translator openai
+```
+
+Outputs next to the video: `interview.es.mp4` (dub track + original track + subtitles), `interview.es.m4a`, `.srt`, `.vtt` and `interview.es.report.json`.
+
+## How it works
+
+![Flow diagram: transcribe, diarize, translate, clone and voice, fit and mix, then publishable files](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/flow.png)
+
+1. **Transcribe**: Miragea speech-to-text (no GPU), local `faster-whisper`, or your own SRT/VTT/JSON. Miragea returns subtitle cues cut at a fixed width, so cues are regrouped into whole sentences using the punctuated full text.
+2. **Diarize**: a built-in, GPU-free speaker clustering on voice features (or `pyannote`, or an RTTM file). Speaker tags already in your transcript (`[Ana] ...`, `S2: ...`) are kept.
+3. **Translate**: every line gets a length budget so the translation can be spoken inside the original time slot. Backends: `agent` (your AI agent edits `dub.json`), `openai` (any OpenAI-compatible endpoint), `file`, `copy`.
+4. **Clone and voice**: an 8-20 second reference clip is cut per speaker from the video, hosted on a temporary public link, and each line is synthesized with that voice through the Miragea API. Requests are idempotent and cached, so a re-run never pays twice.
+5. **Fit and mix**: lines are sped up (up to 1.35x by default) to fit, the original audio is ducked under speech (or removed, or replaced by your music stem, or separated with Demucs), then everything is muxed.
+
+### Real timing report
+
+![Timeline of the real run: for each speaker, outlined bars show the original slot and solid bars the dubbed Spanish line after fitting](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/timeline.png)
+
+![Terminal capture of the real miragea-dub run: 6 lines, 2 speakers, 4 sped up, 0 trimmed](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/terminal-dub.png)
+
+Lines that could not fit even at the speed limit are listed in `lines_to_shorten`; shorten them in `dub.json` and run `render` again (only changed lines are re-voiced).
+
+## Use it from an AI agent
+
+**MCP server** (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf):
+
+```json
+{ "mcpServers": { "miragea-dub": { "command": "uvx", "args": ["--from", "miragea-dub", "miragea-dub-mcp"],
+  "env": { "MIRAGEA_API_KEY": "your-key" } } } }
+```
+
+Tools: `prepare_dub`, `save_translations`, `show_project`, `estimate_dub`, `render_dub`, `list_voices`. The agent is the translator, so no second LLM key is needed.
+
+**Agent Skill**: install `video-dubbing` from [miragea-skills](https://codeberg.org/miragea-voice/miragea-skills), or tell your agent: `Install https://miragea.ai/skills/miragea-audio/install.md`.
+
+## How it compares
+
+| | miragea-dub | [VideoLingo](https://github.com/Huanshere/VideoLingo) | [pyvideotrans](https://github.com/jianchang512/pyvideotrans) | Hosted dubbing apps |
+|---|---|---|---|---|
+| License | MIT | Apache-2.0 | GPL-3.0 | closed SaaS |
+| Interface | CLI + MCP + Agent Skill | Streamlit app | desktop GUI + CLI | web app |
+| Separate cloned voice per speaker | yes (from the video itself) | depends on TTS backend | depends on backend | yes |
+| Runs without a GPU | yes (cloud ASR + voices) | local models recommended | optional | n/a |
+| Your AI agent can drive it | yes (MCP, skill) | no | no | usually no |
+| Editable project file between steps | `dub.json` | partly | partly | web editor |
+| Speaker count / timing report | yes | no | no | varies |
+
+Star counts at time of writing: VideoLingo 19.1k, pyvideotrans 19.7k. Those projects are bigger and have GUIs; miragea-dub is the small, scriptable, agent-friendly option.
+
+## FAQ
+
+**How do I dub a video into another language with AI?** Install miragea-dub, run `miragea-dub dub video.mp4 --to es --translator openai`, and you get a dubbed MP4 plus subtitles.
+
+**Can I dub a video with two or more speakers and keep each voice?** Yes. Speakers are separated by diarization (or by tags in your own transcript) and each one is cloned from their own lines.
+
+**Does it work for a YouTube video with multiple audio tracks?** The `.m4a` output is the stand-alone dubbed track you can upload as an additional language audio track; the `.mp4` already carries dub and original tracks.
+
+**Is there a free open-source alternative to ElevenLabs or HeyGen dubbing?** The pipeline, diarization, timing fit and mixing are free and MIT; the voices come from the Miragea API, which needs a key.
+
+**Can an AI agent (Claude, Cursor, Codex) dub videos?** Yes, through the MCP server or the `video-dubbing` skill. The agent writes the translations itself.
+
+**How do I keep the dubbed speech from running longer than the original?** Every line gets a word or character budget before translation, long lines are sped up to the limit, and what still does not fit is reported for shortening.
+
+**Does it keep background music?** By default the original audio is ducked under speech. Use `--background file` with a music stem, `demucs` to separate stems, or `remove`.
+
+**Which languages?** Anything your translator and the Miragea voices handle; the repo's own example is English to Spanish.
+
+## Troubleshooting
+
+- `litterbox upload failed (HTTP 403)`: the default `--ref-host auto` already falls back to other free hosts; or use `--ref-host "cmd:your-upload-command {path}"`, or `prefix:` with `--ref-dir` for your own server.
+- Wrong speaker count: pass `--speakers N`, or supply `--transcript` with `[Name]` tags.
+- A line sounds rushed: shorten its `translation` in `dub.json` and run `render` again.
+- `401`: create a key at https://miragea.ai/workspace/api and `export MIRAGEA_API_KEY`.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+python -m pytest        # 28 tests, offline: Miragea API is mocked with httpx.MockTransport
+python docs/make_images.py
+```
+
+Base URL defaults to `https://miragea.ai/v1` (override with `MIRAGEA_BASE_URL`). See [CHANGELOG](CHANGELOG.md) and [llms.txt](llms.txt). MIT, see [LICENSE](LICENSE).

miragea_dub-0.1.0/README.md

@@ -0,0 +1,120 @@
+<p align="center">
+  <img src="https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/cover.png" alt="miragea-dub banner: two speakers' lanes in English above the same two lanes dubbed into Spanish, each speaker keeping their own voice" width="100%">
+</p>
+
+# miragea-dub: multi-speaker AI video dubbing, open source
+
+**miragea-dub is an open-source command-line tool, MCP server and Agent Skill that dubs a video into another language while keeping a separate cloned voice for every speaker.** It transcribes the video, works out who speaks when, lets you (or your AI agent) translate each line, clones every speaker's voice from the video itself with the [Miragea](https://miragea.ai) voice API, fits each translated line into the original timing, ducks the original audio underneath, and exports a dubbed MP4, a stand-alone audio track for YouTube multi-language audio, and SRT/VTT subtitles. MIT licensed, Python 3.10+, works offline in `demo` mode.
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml) [![tests](https://img.shields.io/badge/tests-28%20passing-brightgreen)](tests)
+
+## Demo: a real two-speaker dub
+
+An English clip with two speakers (Ana and Ben) dubbed into Spanish. Both voices were cloned from the clip itself, nothing was pre-recorded:
+
+- [Watch the dubbed MP4 (Spanish, burned-in subtitles, original English kept as 2nd audio track)](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/examples/demo-dubbed-es.mp4)
+- [Original English audio](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/examples/real/original-audio.mp3)
+- [Spanish subtitles](examples/output/two-voices.es.srt) and [timing report](examples/output/two-voices.es.report.json)
+
+![Animated preview of the Spanish dub with burned-in subtitles and a waveform](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/demo.gif)
+
+Round-trip check: transcribing the Spanish track again returns the translated script almost word for word, and the diarizer assigned all 6 lines to the right speaker.
+
+## Quick start
+
+```bash
+pipx install miragea-dub          # or: uvx miragea-dub ...   (needs ffmpeg on PATH)
+miragea-dub demo                  # offline end-to-end run with test tones, no key needed
+export MIRAGEA_API_KEY=...        # create a key at https://miragea.ai/workspace/api
+miragea-dub doctor                # checks ffmpeg, key, connectivity
+
+# 1) transcribe + find speakers -> dub.json
+miragea-dub prepare interview.mp4 --to es --speakers 2
+# 2) translate: let your AI agent fill "translation" in dub.json, or use any OpenAI-compatible LLM
+miragea-dub translate interview.dub/dub.json --translator openai
+# 3) voice, fit, mix, export
+miragea-dub render interview.dub/dub.json --model expressive
+# or all in one:  miragea-dub dub interview.mp4 --to es --translator openai
+```
+
+Outputs next to the video: `interview.es.mp4` (dub track + original track + subtitles), `interview.es.m4a`, `.srt`, `.vtt` and `interview.es.report.json`.
+
+## How it works
+
+![Flow diagram: transcribe, diarize, translate, clone and voice, fit and mix, then publishable files](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/flow.png)
+
+1. **Transcribe**: Miragea speech-to-text (no GPU), local `faster-whisper`, or your own SRT/VTT/JSON. Miragea returns subtitle cues cut at a fixed width, so cues are regrouped into whole sentences using the punctuated full text.
+2. **Diarize**: a built-in, GPU-free speaker clustering on voice features (or `pyannote`, or an RTTM file). Speaker tags already in your transcript (`[Ana] ...`, `S2: ...`) are kept.
+3. **Translate**: every line gets a length budget so the translation can be spoken inside the original time slot. Backends: `agent` (your AI agent edits `dub.json`), `openai` (any OpenAI-compatible endpoint), `file`, `copy`.
+4. **Clone and voice**: an 8-20 second reference clip is cut per speaker from the video, hosted on a temporary public link, and each line is synthesized with that voice through the Miragea API. Requests are idempotent and cached, so a re-run never pays twice.
+5. **Fit and mix**: lines are sped up (up to 1.35x by default) to fit, the original audio is ducked under speech (or removed, or replaced by your music stem, or separated with Demucs), then everything is muxed.
+
+### Real timing report
+
+![Timeline of the real run: for each speaker, outlined bars show the original slot and solid bars the dubbed Spanish line after fitting](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/timeline.png)
+
+![Terminal capture of the real miragea-dub run: 6 lines, 2 speakers, 4 sped up, 0 trimmed](https://codeberg.org/miragea-voice/miragea-dub/raw/branch/main/docs/images/terminal-dub.png)
+
+Lines that could not fit even at the speed limit are listed in `lines_to_shorten`; shorten them in `dub.json` and run `render` again (only changed lines are re-voiced).
+
+## Use it from an AI agent
+
+**MCP server** (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf):
+
+```json
+{ "mcpServers": { "miragea-dub": { "command": "uvx", "args": ["--from", "miragea-dub", "miragea-dub-mcp"],
+  "env": { "MIRAGEA_API_KEY": "your-key" } } } }
+```
+
+Tools: `prepare_dub`, `save_translations`, `show_project`, `estimate_dub`, `render_dub`, `list_voices`. The agent is the translator, so no second LLM key is needed.
+
+**Agent Skill**: install `video-dubbing` from [miragea-skills](https://codeberg.org/miragea-voice/miragea-skills), or tell your agent: `Install https://miragea.ai/skills/miragea-audio/install.md`.
+
+## How it compares
+
+| | miragea-dub | [VideoLingo](https://github.com/Huanshere/VideoLingo) | [pyvideotrans](https://github.com/jianchang512/pyvideotrans) | Hosted dubbing apps |
+|---|---|---|---|---|
+| License | MIT | Apache-2.0 | GPL-3.0 | closed SaaS |
+| Interface | CLI + MCP + Agent Skill | Streamlit app | desktop GUI + CLI | web app |
+| Separate cloned voice per speaker | yes (from the video itself) | depends on TTS backend | depends on backend | yes |
+| Runs without a GPU | yes (cloud ASR + voices) | local models recommended | optional | n/a |
+| Your AI agent can drive it | yes (MCP, skill) | no | no | usually no |
+| Editable project file between steps | `dub.json` | partly | partly | web editor |
+| Speaker count / timing report | yes | no | no | varies |
+
+Star counts at time of writing: VideoLingo 19.1k, pyvideotrans 19.7k. Those projects are bigger and have GUIs; miragea-dub is the small, scriptable, agent-friendly option.
+
+## FAQ
+
+**How do I dub a video into another language with AI?** Install miragea-dub, run `miragea-dub dub video.mp4 --to es --translator openai`, and you get a dubbed MP4 plus subtitles.
+
+**Can I dub a video with two or more speakers and keep each voice?** Yes. Speakers are separated by diarization (or by tags in your own transcript) and each one is cloned from their own lines.
+
+**Does it work for a YouTube video with multiple audio tracks?** The `.m4a` output is the stand-alone dubbed track you can upload as an additional language audio track; the `.mp4` already carries dub and original tracks.
+
+**Is there a free open-source alternative to ElevenLabs or HeyGen dubbing?** The pipeline, diarization, timing fit and mixing are free and MIT; the voices come from the Miragea API, which needs a key.
+
+**Can an AI agent (Claude, Cursor, Codex) dub videos?** Yes, through the MCP server or the `video-dubbing` skill. The agent writes the translations itself.
+
+**How do I keep the dubbed speech from running longer than the original?** Every line gets a word or character budget before translation, long lines are sped up to the limit, and what still does not fit is reported for shortening.
+
+**Does it keep background music?** By default the original audio is ducked under speech. Use `--background file` with a music stem, `demucs` to separate stems, or `remove`.
+
+**Which languages?** Anything your translator and the Miragea voices handle; the repo's own example is English to Spanish.
+
+## Troubleshooting
+
+- `litterbox upload failed (HTTP 403)`: the default `--ref-host auto` already falls back to other free hosts; or use `--ref-host "cmd:your-upload-command {path}"`, or `prefix:` with `--ref-dir` for your own server.
+- Wrong speaker count: pass `--speakers N`, or supply `--transcript` with `[Name]` tags.
+- A line sounds rushed: shorten its `translation` in `dub.json` and run `render` again.
+- `401`: create a key at https://miragea.ai/workspace/api and `export MIRAGEA_API_KEY`.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+python -m pytest        # 28 tests, offline: Miragea API is mocked with httpx.MockTransport
+python docs/make_images.py
+```
+
+Base URL defaults to `https://miragea.ai/v1` (override with `MIRAGEA_BASE_URL`). See [CHANGELOG](CHANGELOG.md) and [llms.txt](llms.txt). MIT, see [LICENSE](LICENSE).

miragea_dub-0.1.0/docs/make_images.py

@@ -0,0 +1,185 @@
+"""Render README images from the REAL example run in examples/output (python3 docs/make_images.py)."""
+
+import json
+import subprocess
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / "docs" / "images"
+OUT.mkdir(parents=True, exist_ok=True)
+F = "/usr/share/fonts/truetype/dejavu/"
+SANS, BOLD, MONO, MONOB = F + "DejaVuSans.ttf", F + "DejaVuSans-Bold.ttf", F + "DejaVuSansMono.ttf", F + "DejaVuSansMono-Bold.ttf"
+BG, PANEL = (15, 17, 26), (27, 31, 46)
+ACCENT, ACCENT2 = (252, 163, 17), (34, 211, 238)
+TEXT, MUTED, GREEN, PINK = (236, 238, 245), (150, 158, 180), (74, 222, 128), (244, 114, 182)
+SPK = {"S1": PINK, "S2": ACCENT2}
+
+
+def font(p, s):
+    return ImageFont.truetype(p, s)
+
+
+def gradient(w, h, top, bottom):
+    img = Image.new("RGB", (w, h), top)
+    d = ImageDraw.Draw(img)
+    for y in range(h):
+        t = y / max(1, h - 1)
+        d.line([(0, y), (w, y)], fill=tuple(int(a + (b - a) * t) for a, b in zip(top, bottom)))
+    return img
+
+
+def cover():
+    w, h = 1280, 540
+    img = gradient(w, h, (20, 33, 61), (9, 12, 22))
+    d = ImageDraw.Draw(img)
+    d.text((64, 56), "OPEN-SOURCE  \u00b7  CLI + MCP SERVER + AGENT SKILL", font=font(BOLD, 20), fill=ACCENT)
+    d.text((64, 96), "miragea-dub", font=font(BOLD, 68), fill=TEXT)
+    d.text((64, 184), "Dub a video into another language,", font=font(SANS, 30), fill=TEXT)
+    d.text((64, 224), "keeping a separate cloned voice per speaker", font=font(SANS, 30), fill=TEXT)
+    lanes = [("EN", "Ana", PINK, [(0.0, .1), (.25, .12), (.55, .22)]), ("EN", "Ben", ACCENT2, [(.12, .13), (.45, .1)])]
+    d.text((64, 300), "ORIGINAL", font=font(BOLD, 15), fill=MUTED)
+    for i, (_, name, col, spans) in enumerate(lanes):
+        y = 324 + i * 44
+        d.text((64, y + 8), name, font=font(BOLD, 18), fill=col)
+        d.rounded_rectangle([130, y, 640, y + 34], radius=8, fill=PANEL)
+        for a, b in spans:
+            d.rounded_rectangle([140 + a * 480, y + 6, 140 + (a + b) * 480 + 40, y + 28], radius=6, fill=col)
+    d.text((700, 300), "DUBBED (ES)", font=font(BOLD, 15), fill=MUTED)
+    for i, (_, name, col, spans) in enumerate(lanes):
+        y = 324 + i * 44
+        d.rounded_rectangle([700, y, 1216, y + 34], radius=8, fill=PANEL)
+        for a, b in spans:
+            d.rounded_rectangle([710 + a * 480, y + 6, 710 + (a + b) * 480 + 40, y + 28], radius=6, fill=col)
+    d.text((64, 450), "pipx install miragea-dub", font=font(MONOB, 24), fill=GREEN)
+    d.text((1216, 456), "voices: Miragea API", font=font(SANS, 18), fill=MUTED, anchor="ra")
+    img.save(OUT / "cover.png", optimize=True)
+
+
+def box(d, xy, title, lines, color):
+    d.rounded_rectangle(xy, radius=16, fill=PANEL, outline=color, width=3)
+    x0, y0, x1, _ = xy
+    d.text(((x0 + x1) / 2, y0 + 18), title, font=font(BOLD, 21), fill=TEXT, anchor="ma")
+    for i, ln in enumerate(lines):
+        d.text(((x0 + x1) / 2, y0 + 58 + i * 27), ln, font=font(SANS, 16), fill=MUTED, anchor="ma")
+
+
+def arrow(d, x0, y, x1, color):
+    d.line([(x0, y), (x1 - 4, y)], fill=color, width=4)
+    d.polygon([(x1, y), (x1 - 14, y - 9), (x1 - 14, y + 9)], fill=color)
+
+
+def flow():
+    w, h = 1500, 560
+    img = gradient(w, h, (16, 18, 28), (11, 12, 19))
+    d = ImageDraw.Draw(img)
+    d.text((w / 2, 30), "How miragea-dub dubs a video", font=font(BOLD, 30), fill=TEXT, anchor="ma")
+    steps = [("1. Transcribe", ["Miragea ASR, whisper", "or your SRT/VTT", "-> whole sentences"], ACCENT),
+             ("2. Diarize", ["who speaks when", "built-in, no GPU", "(or pyannote / RTTM)"], ACCENT2),
+             ("3. Translate", ["your AI agent, any", "OpenAI-style LLM,", "or a file; length budgets"], ACCENT),
+             ("4. Clone + voice", ["8-20 s reference per", "speaker, Miragea API,", "parallel, cached"], PINK),
+             ("5. Fit + mix", ["speed to fit each slot,", "duck the original,", "mux tracks + subs"], ACCENT2)]
+    bw, gap, y0 = 250, 45, 110
+    for i, (t, lines, col) in enumerate(steps):
+        x = 40 + i * (bw + gap)
+        box(d, [x, y0, x + bw, y0 + 180], t, lines, col)
+        if i < len(steps) - 1:
+            arrow(d, x + bw + 4, y0 + 90, x + bw + gap - 2, MUTED)
+    d.line([(w / 2, y0 + 180), (w / 2, 360)], fill=GREEN, width=4)
+    d.polygon([(w / 2, 362), (w / 2 - 9, 348), (w / 2 + 9, 348)], fill=GREEN)
+    d.rounded_rectangle([250, 366, 1250, 500], radius=16, fill=(20, 40, 34), outline=GREEN, width=3)
+    d.text((w / 2, 380), "Files you can publish", font=font(BOLD, 22), fill=TEXT, anchor="ma")
+    d.text((w / 2, 420), "video.es.mp4 (dub + original audio + subtitles)   video.es.m4a   .srt   .vtt",
+           font=font(MONO, 16), fill=GREEN, anchor="ma")
+    d.text((w / 2, 450), "video.es.report.json: which lines were sped up or need shortening", font=font(MONO, 16),
+           fill=GREEN, anchor="ma")
+    d.text((40, 524), "Each step writes dub.json, so you can edit a line and re-render; finished lines are never paid twice.",
+           font=font(SANS, 16), fill=MUTED)
+    img.save(OUT / "flow.png", optimize=True)
+
+
+def terminal(name, title, lines, width=1360):
+    m = font(MONO, 19)
+    lh = 30
+    h = 70 + lh * len(lines) + 26
+    img = Image.new("RGB", (width, h), (12, 14, 22))
+    d = ImageDraw.Draw(img)
+    d.rounded_rectangle([0, 0, width - 1, h - 1], radius=14, fill=(22, 25, 36), outline=(52, 58, 80), width=2)
+    d.rectangle([2, 40, width - 3, h - 3], fill=(13, 15, 23))
+    for i, c in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
+        d.ellipse([20 + i * 26, 13, 34 + i * 26, 27], fill=c)
+    d.text((width / 2, 11), title, font=font(SANS, 16), fill=MUTED, anchor="ma")
+    y = 58
+    for ln in lines:
+        x = 24
+        for seg, col in ln:
+            d.text((x, y), seg, font=m, fill=col)
+            x += d.textlength(seg, font=m)
+        y += lh
+    img.save(OUT / name, optimize=True)
+
+
+def P(s, c=TEXT):
+    return (s, c)
+
+
+def terminals():
+    rep = json.loads((ROOT / "examples/output/two-voices.es.report.json").read_text())
+    terminal("terminal-dub.png", "miragea-dub dub (real run, English -> Spanish, 2 speakers)", [
+        [P("$ ", GREEN), P("miragea-dub dub two-voices.mp4 --to es --speakers 2 --translator file \\")],
+        [P("    --translations two-voices.es.translations.json --model expressive")],
+        [P("\u203a Transcript: 6 lines, language en", MUTED)],
+        [P("\u203a Speakers: 2", MUTED)],
+        [P("\u203a Reference clip for S1: 10.0s from 2 line(s)   \u203a Hosted reference for S1", MUTED)],
+        [P("\u203a Reference clip for S2: 9.2s from 2 line(s)    \u203a Hosted reference for S2", MUTED)],
+        [P("\u203a Voicing 6 lines for 2 speaker(s) with miragea", MUTED)],
+        [P("\u203a Done: 6 lines, 4 sped up, 0 trimmed", MUTED)],
+        [P("status: ", ACCENT2), P("done", GREEN), P("   speakers: ", ACCENT2), P(str(rep["speakers"]))],
+        [P("max_speed_used: ", ACCENT2), P(str(rep["max_speed_used"])), P("   lines_to_shorten: ", ACCENT2), P("[]", GREEN)],
+        [P("video: ", ACCENT2), P("two-voices.es.mp4"), P("   srt/vtt: ", ACCENT2), P("two-voices.es.srt / .vtt")],
+    ])
+
+
+def timeline():
+    rep = json.loads((ROOT / "examples/output/two-voices.es.report.json").read_text())
+    total = max(f["placed_end"] for f in rep["fit"]) + 0.5
+    w, h = 1480, 400
+    img = gradient(w, h, (16, 18, 28), (11, 12, 19))
+    d = ImageDraw.Draw(img)
+    d.text((40, 24), "Real timing report: every Spanish line placed in the original slot", font=font(BOLD, 24), fill=TEXT)
+    x0, span = 140, 1300
+    for i, spk in enumerate(["S1", "S2"]):
+        y = 90 + i * 100
+        d.text((40, y + 22), spk, font=font(BOLD, 22), fill=SPK[spk])
+        d.rounded_rectangle([x0, y, x0 + span, y + 70], radius=10, fill=PANEL)
+        for f in rep["fit"]:
+            if f["speaker"] != spk:
+                continue
+            a = x0 + span * f["start"] / total
+            slot = x0 + span * (f["start"] + f["slot"]) / total
+            end = x0 + span * f["placed_end"] / total
+            d.rounded_rectangle([a, y + 8, slot, y + 30], radius=5, outline=MUTED, width=2)
+            d.rounded_rectangle([a, y + 38, end, y + 62], radius=5, fill=SPK[spk])
+            d.text((a + 6, y + 40), f"#{f['id']} x{f['speed']:.2f}", font=font(SANS, 13), fill=BG)
+    d.text((40, 310), "Outlined bar: the slot the original line occupied.  Solid bar: the dubbed line after fitting (x = speed-up).",
+           font=font(SANS, 16), fill=MUTED)
+    d.text((40, 340), f"{len(rep['fit'])} lines, max speed-up {rep['max_speed_used']}, {rep['trimmed']} trimmed. "
+           "Source: examples/output/two-voices.es.report.json", font=font(SANS, 16), fill=MUTED)
+    img.save(OUT / "timeline.png", optimize=True)
+
+
+def gif():
+    subprocess.run(["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "0", "-t", "12", "-i",
+                    str(ROOT / "examples/demo-dubbed-es.mp4"), "-vf",
+                    "fps=8,scale=640:-1:flags=lanczos,split[a][b];[a]palettegen=max_colors=96[p];[b][p]paletteuse=dither=bayer",
+                    str(OUT / "demo.gif")], check=True)
+
+
+if __name__ == "__main__":
+    cover()
+    flow()
+    terminals()
+    timeline()
+    gif()
+    print(sorted(p.name for p in OUT.iterdir()))

miragea_dub-0.1.0/llms.txt

@@ -0,0 +1,15 @@
+# miragea-dub
+
+> Open-source CLI, MCP server and Agent Skill that dubs videos into another language with a separate cloned voice per speaker (Miragea voice API). Outputs dubbed MP4, multi-language audio track, SRT/VTT.
+
+## Docs
+- [README](https://codeberg.org/miragea-voice/miragea-dub/src/branch/main/README.md): quick start, how it works, comparison, FAQ
+- [Skill](https://codeberg.org/miragea-voice/miragea-skills/src/branch/main/skills/video-dubbing/SKILL.md): agent instructions
+- [Changelog](https://codeberg.org/miragea-voice/miragea-dub/src/branch/main/CHANGELOG.md)
+
+## Facts
+- Install: pipx install miragea-dub (PyPI), needs ffmpeg
+- Key: MIRAGEA_API_KEY from https://miragea.ai/workspace/api ; API base https://miragea.ai/v1
+- Commands: prepare, translate, render, dub, estimate, voices, doctor, demo, mcp
+- MCP tools: prepare_dub, save_translations, show_project, estimate_dub, render_dub, list_voices
+- License: MIT

miragea_dub-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "miragea-dub"
+version = "0.1.0"
+description = "Open-source multi-speaker video dubbing: transcribe, find who speaks when, translate, and re-voice every speaker with their own cloned voice, with timing fit, ducked background, dubbed MP4, multi-language audio track and SRT/VTT. CLI + MCP server + Agent Skill, voiced by Miragea."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "miragea-dub contributors" }]
+keywords = ["video-dubbing", "ai-dubbing", "dubbing", "video-translation", "voice-cloning", "multi-speaker", "speaker-diarization", "ai-voice-over", "youtube-multi-language-audio", "heygen-alternative", "elevenlabs-dubbing-alternative", "subtitles", "srt", "mcp", "mcp-server", "agent-skill", "text-to-speech", "localization", "miragea"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Multimedia :: Video",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "numpy>=1.26", "mcp>=1.9", "anyio>=4", "pydantic>=2"]
+
+[project.optional-dependencies]
+whisper = ["faster-whisper>=1.0"]
+pyannote = ["pyannote.audio>=3.1"]
+demucs = ["demucs>=4"]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://codeberg.org/miragea-voice/miragea-dub"
+Documentation = "https://codeberg.org/miragea-voice/miragea-dub#readme"
+Issues = "https://codeberg.org/miragea-voice/miragea-dub/issues"
+"Miragea API" = "https://miragea.ai"
+
+[project.scripts]
+miragea-dub = "miragea_dub.cli:main"
+miragea-dub-mcp = "miragea_dub.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/miragea_dub"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["examples", "docs/images", "docs/media", ".venv", "examples/output"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 150
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["B905"]

miragea_dub-0.1.0/src/miragea_dub/__init__.py

@@ -0,0 +1,3 @@
+"""miragea-dub: open-source multi-speaker video dubbing with per-speaker cloned voices."""
+
+__version__ = "0.1.0"

miragea_dub-0.1.0/src/miragea_dub/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())