Metadata-Version: 2.4
Name: fastdub
Version: 3.8.1
Summary: A Python CLI package for voice over subtitles, with the ability to embed in video, audio ducking, and dynamic voice changer for a single track; auto translating; download and upload to YouTube supports
License-Expression: MIT
Keywords: dubbing,voicing,fastdub,JustDub,SpeedDub,offline,free,easiest,subtitles,videos,veed,fast
Author: Nikita Denissov
Author-email: n.denissov@proton.me
Requires-Python: >=3.9
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: Russian
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: tr
Provides-Extra: yt
Provides-Extra: ytu
Requires-Dist: chardet (>=5.2.0)
Requires-Dist: download-youtube-subtitle (>=1.0.4) ; extra == "all"
Requires-Dist: download-youtube-subtitle (>=1.0.4) ; extra == "yt"
Requires-Dist: google-api-python-client (>=2.160.0) ; extra == "all"
Requires-Dist: google-api-python-client (>=2.160.0) ; extra == "ytu"
Requires-Dist: oauth2client (>=4.1.3) ; extra == "all"
Requires-Dist: oauth2client (>=4.1.3) ; extra == "ytu"
Requires-Dist: pafy (>=0.5.5) ; extra == "all"
Requires-Dist: pafy (>=0.5.5) ; extra == "yt"
Requires-Dist: pydub (>=0.25.1)
Requires-Dist: pyttsx3 (>=2.90)
Requires-Dist: rich (>=13.9.4)
Requires-Dist: tqdm (>=4.67.1)
Requires-Dist: translators (>=5.9.3) ; extra == "all"
Requires-Dist: translators (>=5.9.3) ; extra == "tr"
Requires-Dist: youtube-dl (>=2021.12.17) ; extra == "all"
Requires-Dist: youtube-dl (>=2021.12.17) ; extra == "yt"
Requires-Dist: youtube-search-python (>=1.6.6) ; extra == "all"
Requires-Dist: youtube-search-python (>=1.6.6) ; extra == "yt"
Project-URL: Bug Tracker, https://github.com/ndenissov/FastDub/issues
Project-URL: Download Voices, https://rhvoice.su/voices
Project-URL: Homepage, https://github.com/ndenissov/FastDub
Project-URL: Repository, https://github.com/ndenissov/FastDub
Description-Content-Type: text/markdown

# FastDub

[![PyPI version](https://img.shields.io/pypi/v/fastdub.svg)](https://pypi.org/project/fastdub/)
[![Downloads](https://static.pepy.tech/badge/fastdub)](https://pepy.tech/project/fastdub)
[![Python versions](https://img.shields.io/pypi/pyversions/fastdub.svg)](https://pypi.org/project/fastdub/)
[![License](https://img.shields.io/pypi/l/fastdub.svg)](https://github.com/ndenissov/FastDub/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ndenissov/FastDub)](https://github.com/ndenissov/FastDub/stargazers)

FastDub is a Python package and command-line utility for automated subtitle voiceovers, video dubbing, audio ducking, dynamic voice changing, subtitle translation, and YouTube integration.

---

## Features

- **Automated Video Dubbing**: Generate speech from subtitle files (.srt, .vtt) and embed the audio into videos (.mp4, .mkv).
- **Audio Ducking (Sidechain Compression)**: Dynamically lower original background audio level while speech is active.
- **Dynamic Voice Changing**: Switch voices mid-track using subtitle anchors (`!:`).
- **Subtitle Translation**: Auto-translate subtitles to target languages using Google Translate or alternative services.
- **YouTube Integration**: Download video playlists/channels, search YouTube directly from CLI, and upload dubbed videos back to YouTube with translated titles and descriptions.
- **Cross-Platform**: Support for SAPI voices on Windows and eSpeak/RHVoice on Linux.

---

## Installation

### System Dependencies

#### Ubuntu / Debian

```bash
sudo apt update -y && sudo apt upgrade -y
sudo apt install -y python3 python3-pip ffmpeg espeak libxml2-dev libxslt1-dev
```

#### macOS

```bash
brew install ffmpeg espeak
```

### Installing FastDub

#### Via PyPI with pip

```bash
# Core package
pip install FastDub

# Install all optional dependencies (Translation + YouTube support)
pip install "FastDub[ALL]"
```

#### Extra Feature Bundles

| Extra | Description | Command |
| :--- | :--- | :--- |
| `TR` | Subtitle translation support | `pip install "FastDub[TR]"` |
| `YT` | YouTube downloading and search | `pip install "FastDub[YT]"` |
| `YTU` | YouTube video uploading | `pip install "FastDub[YTU]"` |
| `ALL` | All optional features combined | `pip install "FastDub[ALL]"` |

#### Via Poetry

```bash
poetry add fastdub --extras "all"
```

---

## Quick Start

### Basic Local Video Dubbing

To voiceover all videos in a target directory:

```bash
fastdub -i ./input_folder -v "Yuriy" --no-sidechain -sf srt -vf mp4
```

Or using python module invocation:

```bash
python -m fastdub -i ./input_folder -l ru
```

### Subtitle Translation

Translate subtitles to Russian before voice acting:

```bash
fastdub -i ./input_folder -tr -l ru -ts google
```

### YouTube Download & Dubbing

Process a single YouTube video:

```bash
fastdub -yt -i "https://youtu.be/DD5UKQggXTc" -l ru
```

Process videos from a YouTube Search query:

```bash
fastdub -yt -yts -i "#python" -yts-l 5 -l ru
```

Process an entire YouTube channel:

```bash
fastdub -yt -i "c/UCi-5OZ2tYuwMLIcEyOsbdRA" -l ru
```

### YouTube Upload Setup

To upload processed videos to YouTube (`FastDub[YTU]`):

1. Go to [Google Cloud Console Credentials](https://console.cloud.google.com/apis/credentials).
2. Create OAuth 2.0 Client ID for Desktop App.
3. Download the JSON credentials file and place it in your working directory as `client_secrets.json`.
4. Run FastDub with upload flags:

```bash
fastdub -i ./input_folder -ytu -ytu-ps private -ytu-t
```

---

## Advanced Usage

### Dynamic Voice Anchors

Change the active voice actor for specific sections by inserting anchor tokens in your subtitle file.

Example SRT subtitle content:

```srt
1
00:00:01,000 --> 00:00:04,000
!:Yuriy Hello, welcome to this video!

2
00:00:04,500 --> 00:00:08,000
!:Elena Here is the next speaker.
```

If voice anchors are updated and cached files need to be refreshed, clear the cache using `-rc`:

```bash
fastdub -i ./input_folder -rc 1
```

---

## Command Line Arguments Reference

```text
usage: fastdub [-h] [-rc {0,1,2}] [-ra | --cleanup-audio | -n-ra | --no-cleanup-audio]
               [-ev | --export-video | -n-ev | --no-export-video] [-l LANGUAGE]
               [-ll {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]
               [-tc THREADS_COUNT] -i INPUT [-vf VIDEO_FORMAT] [-sf SUBTITLES_FORMAT]
               [-En EXCLUDE [EXCLUDE ...]] [-Eu EXCLUDE_UNDERSCORE]
               [-sc | --sidechain | -n-sc | --no-sidechain]
               [-sc-args SIDECHAIN_FFMPEG_PARAMS] [-sc-lvl SIDECHAIN_LEVEL_SC]
               [-v VOICE] [-a ALIGN] [-v-set-a VOICE_SET_ANCHOR]
               [-fll {trace,debug,verbose,info,warning,error,fatal,panic,quiet}]
               [-y | --confirm | -n-y | --no-confirm] [-af AUDIO_FORMAT] [-wm WATERMARK]
               [-tb | --traceback | -n-tb | --no-traceback] [-yt]
               [-ak API_KEYS [API_KEYS ...]] [-yts] [-yts-l YOUTUBE_SEARCH_LIMIT]
               [-yts-rg YOUTUBE_SEARCH_REGION] [-ytu]
               [-ytu-ps {private,public,unlisted}] [-ytu-t] [-tr] [--rewrite-srt | --no-rewrite-srt]
               [-ts TRANSLATE_SERVICE]
```

---

## Python API Usage

FastDub modules can be imported directly into Python applications:

```python
from fastdub import GlobalSettings, dubber

GlobalSettings.language = "ru"
GlobalSettings.threads_count = 4

# Perform dubbing operation programmatically
dubber.dub(
    input_dir="./media",
    voice="Yuriy",
    export_video=True,
    sidechain=True
)
```

---

## Development & Publishing

FastDub uses [Poetry](https://python-poetry.org/) for build backend management.

### Build Package

```bash
poetry build
```

### Publish Package

```bash
poetry publish
```

---

## Issues & Support

If you encounter any issues or have feature requests, please open an issue on [GitHub Issues](https://github.com/ndenissov/FastDub/issues).

---

## License

Distributed under the MIT License. See [LICENSE](https://github.com/ndenissov/FastDub/blob/main/LICENSE) for details.

