Metadata-Version: 2.4
Name: mazinger
Version: 2.3.3
Summary: End-to-end video dubbing pipeline: transcribe, translate, and voice-clone.
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yt-dlp>=2026.3.17
Requires-Dist: openai>=1.0
Requires-Dist: json-repair>=0.28
Requires-Dist: Pillow>=10.0
Requires-Dist: soundfile>=0.12
Requires-Dist: numpy>=1.24
Requires-Dist: tqdm>=4.60
Requires-Dist: python-slugify>=8.0
Provides-Extra: transcribe-faster
Requires-Dist: faster-whisper>=1.0; extra == "transcribe-faster"
Requires-Dist: nvidia-cublas-cu12>=12.0; platform_system == "Linux" and extra == "transcribe-faster"
Provides-Extra: transcribe-whisperx
Requires-Dist: whisperx>=3.8.4; extra == "transcribe-whisperx"
Requires-Dist: pyannote.audio>=4.0; extra == "transcribe-whisperx"
Requires-Dist: torch>=2.0; extra == "transcribe-whisperx"
Requires-Dist: scipy>=1.14; extra == "transcribe-whisperx"
Requires-Dist: scikit-learn>=1.5; extra == "transcribe-whisperx"
Provides-Extra: transcribe-deepgram
Requires-Dist: deepgram-sdk>=6.0; extra == "transcribe-deepgram"
Provides-Extra: transcribe-coherex
Requires-Dist: coherex[langid]>=0.2.0; extra == "transcribe-coherex"
Requires-Dist: torch>=2.8; extra == "transcribe-coherex"
Requires-Dist: torchaudio>=2.8; extra == "transcribe-coherex"
Provides-Extra: transcribe
Requires-Dist: mazinger[transcribe-faster]; extra == "transcribe"
Provides-Extra: tts
Requires-Dist: torch>=2.0; extra == "tts"
Requires-Dist: torchaudio>=2.0; extra == "tts"
Requires-Dist: transformers>=5.4; extra == "tts"
Requires-Dist: accelerate>=1.12; extra == "tts"
Requires-Dist: einops>=0.8; extra == "tts"
Requires-Dist: librosa>=0.10; extra == "tts"
Requires-Dist: soundfile>=0.12; extra == "tts"
Requires-Dist: huggingface-hub>=0.30; extra == "tts"
Requires-Dist: numpy>=1.26; extra == "tts"
Provides-Extra: tts-chatterbox
Requires-Dist: chatterbox-tts; extra == "tts-chatterbox"
Requires-Dist: resemble-perth>=1.0.1; extra == "tts-chatterbox"
Requires-Dist: torch>=2.0; extra == "tts-chatterbox"
Requires-Dist: torchaudio>=2.0; extra == "tts-chatterbox"
Requires-Dist: soundfile>=0.12; extra == "tts-chatterbox"
Requires-Dist: numpy>=1.26; extra == "tts-chatterbox"
Requires-Dist: pandas>=2.2; extra == "tts-chatterbox"
Provides-Extra: flash-attn
Requires-Dist: flash-attn>=2.0; extra == "flash-attn"
Provides-Extra: audio-enhance
Requires-Dist: demucs>=4.0.1; extra == "audio-enhance"
Provides-Extra: tts-omnivoice
Requires-Dist: omnivoice; extra == "tts-omnivoice"
Requires-Dist: torch>=2.0; extra == "tts-omnivoice"
Requires-Dist: soundfile>=0.12; extra == "tts-omnivoice"
Provides-Extra: all-qwen
Requires-Dist: mazinger[audio-enhance,transcribe-faster,tts]; extra == "all-qwen"
Provides-Extra: all-chatterbox
Requires-Dist: mazinger[audio-enhance,transcribe-faster,tts-chatterbox]; extra == "all-chatterbox"
Provides-Extra: all-omnivoice
Requires-Dist: mazinger[audio-enhance,transcribe-faster,tts-omnivoice]; extra == "all-omnivoice"
Provides-Extra: all-coherex
Requires-Dist: mazinger[all]; extra == "all-coherex"
Provides-Extra: all
Requires-Dist: mazinger[audio-enhance,transcribe-coherex,transcribe-deepgram,transcribe-faster,tts,tts-omnivoice,web]; extra == "all"
Provides-Extra: tts-mlx
Requires-Dist: mlx-audio>=0.4.2; extra == "tts-mlx"
Requires-Dist: mlx>=0.20; extra == "tts-mlx"
Requires-Dist: soundfile>=0.12; extra == "tts-mlx"
Provides-Extra: transcribe-mlx
Requires-Dist: mlx-whisper>=0.4; extra == "transcribe-mlx"
Provides-Extra: all-mlx
Requires-Dist: mazinger[transcribe-faster,transcribe-mlx,tts-mlx]; extra == "all-mlx"
Provides-Extra: web
Requires-Dist: gradio>=5.0; extra == "web"
Requires-Dist: huggingface-hub>=0.30; extra == "web"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/bakrianoo/mazinger/refs/heads/master/docs/assets/main-logo-refined.png" alt="Mazinger Dubber" width="240" height="240" />
</p>

<h1 align="center">Mazinger Dubber</h1>

<p align="center">
  End-to-end video dubbing pipeline. Download a video, transcribe it, translate the subtitles, clone a voice, and produce a fully dubbed audio or video — in one command.
</p>

<p align="center">
  <a href="https://huggingface.co/datasets/bakrianoo/mazinger-dubber-profiles/blob/main/promo-demo/mazinger-promo.mp4">
    <img src="https://raw.githubusercontent.com/bakrianoo/mazinger/refs/heads/master/docs/assets/thumbnail-demo.png" alt="Watch demo video" width="640" /><br/>
    ▶️ Watch Demo Video (with audio)
  </a>
</p>

---

## 🚀 Get Started

**Prerequisites:** Python 3.10+ and `ffmpeg` on your `PATH` (`apt install ffmpeg` / `brew install ffmpeg`).

### 1. Install

> ⚠️ **Use `uv` — plain `pip` will fail.** `mazinger[all]` bundles packages with conflicting dependency pins that only `uv` can resolve.
> Install `uv` once: `pip install uv`

```bash
uv pip install "mazinger[all]"
```

### 2. Launch the Web UI

```bash
mazinger web --with-ollama --with-coherex
```

A local URL opens in your browser. Paste a video link, pick a voice, and click **Start**. To process several videos in one go, put one URL or local path per line (or upload several files); they run one after another with a progress bar. The flags install a free local LLM (Ollama) and pre-download **CohereX**, the transcription backend Studio defaults to — no API keys required.

> **Want to script it?** Click **🧾 Show CLI command** next to **Start** to get the `mazinger dub` command that runs the same job with the same settings.

> **No Hugging Face account?** CohereX's weights are gated, so swap in `--with-faster-whisper` and pick **Faster Whisper** in the UI — it needs no sign-in and covers any language.

> The flags only move the wait to launch time: if you run plain `mazinger web`, Studio installs Ollama and pulls the model by itself the first time you start a mission with the **Ollama (Local — Free)** provider. Set `OLLAMA_HOST` to use an Ollama server running elsewhere.

> 💡 **No GPU?** Run it on a free Colab T4 in two clicks:
> [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/bakrianoo/mazinger/blob/master/notebooks/mazinger_colab.ipynb)

> Prefer the command line or Python? Skip ahead to [Common Tasks](#-common-tasks) or the [Python API](#-python-api).

---

## ✨ What You Get

`mazinger[all]` is a single, GPU-friendly install that includes everything needed for the full pipeline and the Studio web UI:

| Capability | Engine |
|---|---|
| Local transcription — 14 languages + a dedicated Arabic model | CohereX — Cohere Transcribe + wav2vec2 (**Studio default**) |
| Local transcription — any language, no sign-in | Faster Whisper (CLI default) |
| Cloud transcription (no GPU) | Deepgram Nova 3 — $200 free credit |
| Voice-cloned TTS | Qwen3-TTS, OmniVoice (24 languages) |
| Background-audio separation | Demucs |
| Web UI | Gradio (Mazinger Studio), with a chunk-level Editor for finished dubs |
| Local LLM (optional) | Ollama (auto-installed by `mazinger web`) |

> **CohereX needs a one-time Hugging Face sign-in** — the Cohere models are
> gated. In the Studio, open **🤗 Hugging Face → Sign in with Hugging Face**;
> from the CLI, set `HF_TOKEN`. Not signed in, or working in a language CohereX
> does not cover? Switch the transcription method to **Faster Whisper**, which
> needs neither.

Need Chatterbox, MLX (Apple Silicon), or a lighter install? See the [Installation Guide](docs/installation.md) — `mazinger[all]` now bundles CohereX, which brings the pyannote stack with it (~50 extra packages).

### 3. Fix the dub, chunk by chunk

When a dub finishes, click **✏️ Open in Editor**, or pick any earlier dub in the **✏️ Editor** tab. Each dubbed chunk is listed with its original audio, transcription, translation, and dubbed audio. Correct a word, reword a line that runs long, move a boundary, split or merge chunks, re-dub only what changed, and click **Assemble** to rebuild the output. Nothing re-runs by itself: edits mark what is out of date, and you choose what to redo. See the [Editor guide](docs/editor.md).

---

## 🛠️ Common Tasks

### Dub a video — auto-clone the original speaker

No voice files needed. Mazinger picks the best 20–60 s of the source as the cloning reference.

```bash
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --target-language Spanish
```

### Dub with a ready-made voice theme

16 built-in themes — no files, no profile downloads.

```bash
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --voice-theme narrator-m \
    --target-language Spanish
```

Themes: `narrator-m/f` · `young-m/f` · `deep-m/f` · `warm-m/f` · `news-m/f` · `storyteller-m/f` · `kid-m/f` · `teen-m/f`

### Dub with a HuggingFace voice profile

```bash
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --clone-profile abubakr \
    --target-language Arabic
```

Available out-of-the-box: `abubakr` · `daheeh-v1` · `3b1b` · `italian-v1` · `morgan-freeman` · `trump-v1` — full list in [Voice Profiles](docs/voice-profiles.md#available-profiles).

### Dub with your own voice sample

```bash
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --voice-sample speaker.m4a \
    --voice-script speaker_transcript.txt \
    --target-language Spanish
```

### Output a video with burned-in subtitles

```bash
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --voice-theme narrator-m \
    --target-language Arabic \
    --output-type video \
    --embed-subtitles \
    --subtitle-google-font "Noto Sans Arabic"
```

See [Subtitle Styling](docs/subtitle-styling.md) for fonts, colors, positioning, and RTL options.

### Transcribe with CohereX (Cohere Transcribe)

14 languages with word-level alignment, plus a dedicated Arabic model that is
selected automatically for Arabic sources. Included in `mazinger[all]`, and the
**default in Mazinger Studio** — nothing to install separately.

The Cohere models are gated on HuggingFace, so it needs a one-time sign-in. In
the Studio, open **🤗 Hugging Face → Sign in with Hugging Face** and follow the
link it shows — no token to copy. From the CLI, set `HF_TOKEN` instead.

The CLI still defaults to Faster Whisper; pass `--transcribe-method coherex` to
use CohereX there:

```bash
export HF_TOKEN=hf_your_token

mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --transcribe-method coherex \
    --source-language Arabic \
    --voice-theme narrator-m \
    --target-language English
```

> ⚠️ Cohere Transcribe cannot detect the source language on its own. Given one,
> it transcribes confidently in whatever language you name; given none, it
> probes each supported language first, which is slower and less reliable.
> Always pass `--source-language` (or pick one in the Studio).

### Use Deepgram instead of a local GPU

```bash
export DEEPGRAM_API_KEY=your_key_here
mazinger dub "https://youtube.com/watch?v=VIDEO_ID" \
    --transcribe-method deepgram \
    --voice-theme narrator-m \
    --target-language English
```

### Run a single stage

```bash
mazinger download   "https://youtube.com/watch?v=VIDEO_ID"
mazinger transcribe ./output/projects/my-video/source/audio.mp3 -o subs.srt
mazinger translate  --srt subs.srt --target-language French -o translated.srt
mazinger subtitle   video.mp4 --srt translated.srt -o output.mp4
```

Every stage caches its output. Re-running resumes where it stopped. Full command list in the [CLI Reference](docs/cli-reference.md).

---

## 🐍 Python API

```python
from mazinger import MazingerDubber

dubber = MazingerDubber(openai_api_key="sk-...", base_dir="./output")

proj = dubber.dub(
    source="https://youtube.com/watch?v=VIDEO_ID",
    voice_theme="narrator-m",
    target_language="Spanish",
    output_type="video",
)

print(proj.final_video)   # ./output/projects/<slug>/tts/dubbed.mp4
```

Full reference: [Python API](docs/python-api.md).

---

## 🔧 How It Works

Mazinger chains ten resumable stages: **Download → Transcribe → Thumbnails → Describe → Review → Translate → Re-segment → Speak → Assemble → Subtitle**. Every stage runs standalone or as part of the full pipeline; completed stages and individual TTS segments are cached and skipped on re-runs.

By default the dub is **in sync with the original speech**, not just with the subtitles: a speech map of the source (voice-activity detection on the Demucs vocals stem) gives every line the exact span of speech it replaces. Each dubbed line is fitted to that length, starts where the original started, and pauses where the speaker paused. The output is exactly as long as the source, the original music and effects stay at their own level, and short sounds nobody transcribed (laughs, breaths) are kept. Pass `--tempo-mode auto` for the earlier subtitle-slot timing.

See the [Pipeline Overview](docs/pipeline.md) for a diagram and the data flow between stages.

---

## 📚 Documentation

| Topic | What's inside |
|---|---|
| [Installation](docs/installation.md) | All install options, advanced extras, Apple Silicon, Colab, uv overrides |
| [Quick Start](docs/quick-start.md) | More copy-paste workflows |
| [Pipeline Overview](docs/pipeline.md) | The ten stages, data flow, resume behavior |
| [CLI Reference](docs/cli-reference.md) | Every command, flag, and default |
| [Python API](docs/python-api.md) | Classes, functions, parameters |
| [Voice Profiles](docs/voice-profiles.md) | Using, creating, uploading profiles |
| [Subtitle Styling](docs/subtitle-styling.md) | Fonts, colors, positioning, RTL, Google Fonts |
| [Configuration](docs/configuration.md) | Env vars, caching, tempo, LLM usage tracking |
| [Editor](docs/editor.md) | Fix a finished dub chunk by chunk: edit, split, merge, re-dub, re-assemble |
| [Project Structure](docs/project-structure.md) | Output directory layout |
| [YouTube Cookies](docs/youtube-cookies.md) | Cookies for age-restricted / region-locked videos |

---

## License

MIT
