FastDub 3.8.0
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: MIT
Requires Python: >=3.9
Keywords: dubbing,voicing,fastdub,JustDub,SpeedDub,offline,free,easiest,subtitles,videos,veed,fast

# FastDub

Package for voice over subtitles:

* with the ability to embed in video,
* audio ducking,
* dynamic voice changer for a single track. _Add **--voice-set-anchor** at the beginning of the subtitle line. (Applies
  to
  all
  subsequent ones)_

> pip install -U [FastDub](https://pypi.org/project/FastDub/)

---

# Install for Ubuntu

> sudo apt update -y && sudo apt upgrade -y
>
> sudo apt install python3 python3-pip ffmpeg [espeak](http://espeak.sourceforge.net/data/) libxml2-dev libxslt1-dev
>
> ; libxml for translator functions
>
> sudo python3 -m pip install -U pip setuptools wheel
>
> sudo python3 -m pip install -U [FastDub](https://pypi.org/project/FastDub/)

# Install all dependencies

> pip install FastDub[ALL]  # default

# Youtube support

## Youtube argument group

> pip install FastDub[YT]

### Process all videos from a channel

_To get the channel id if it only has a username, run the JS code in the browser console:_

```javascript
document.querySelector("body>link").href
```

**Then, in the input parameter,
you can pass a link to the channel (with an id, not with a username) or a string of the format "c/CHANNEL_ID"**

_For example:_

> python -m fastdub -i "c/[UCi-5OZ2tYuwMLIcEyOsbdRA](https://www.youtube.com/channel/UCi-5OZ2tYuwMLIcEyOsbdRA)" -yt

## YouTube Search argument group

That the input data was a request to YouTube, they must begin with "?".

_For Example:_

> python -m fastdub -i "?#python" -yt -yts-l 5

## YouTube Upload argument group

> pip install FastDub[YTU]

To download, you need to go to [credentials](https://console.cloud.google.com/apis/credentials) (Create a new project if
needed) > <kbd>+ Create credentials</kbd> > <kbd>OAuth Client ID</kbd> > <kbd>Desktop App</kbd>

After filling in the required fields, <kbd>DOWNLOAD JSON</kbd> format and save to a working folder under the name
_client_secrets.json_

* Specifying the -ytu-ps argument as non-private may result in processing errors, but this was not observed during
  testing.

* Please note that video uploads require a large amount of [quota](https://console.cloud.google.com/iam-admin/quotas) (
  default has 10,000 per day)

# Subtitles translate

### Translate argument group

> pip install FastDub[TR]

# Usage

> python -m fastdub --help

```
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 {...}]
               [-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 {...}]

fastdub is a tool for dubbing videos by subtitle files.

optional arguments:
  -h, --help            show this help message and exit
  -rc {0,1,2}, --remove-cache {0,1,2}
                        Remove all cache (_cached_texts directory) files
                                0 - No remove cache
                                1 - Delete cache before voice acting
                                2 - Delete cache after voice acting (default)
  -ra, --cleanup-audio, -n-ra, --no-cleanup-audio
                        Remove result audio if video exists (default True) (default: True)
  -ev, --export-video, -n-ev, --no-export-video
  -l LANGUAGE, --language LANGUAGE
                        Subtitles language (ru)
  -ll {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}, --loglevel {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}
                        Program log level
  -tc THREADS_COUNT, --threads-count THREADS_COUNT
                        Process count to download (pass to cpu count, < 2 to disable)
                                *N = N * cpu count

Input:
  -i INPUT, --input INPUT
                        Input directory/YouTube Playlist/Video URL.
  -vf VIDEO_FORMAT, --video-format VIDEO_FORMAT
                        Video format (default: .mp4).
  -sf SUBTITLES_FORMAT, --subtitles-format SUBTITLES_FORMAT
                        Subtitles format (default: .srt).

Input Exclude:
  -En EXCLUDE [EXCLUDE ...], --exclude EXCLUDE [EXCLUDE ...]
                        Exclude <name> (glob)
  -Eu EXCLUDE_UNDERSCORE, --exclude-underscore EXCLUDE_UNDERSCORE
                        Exclude files starts with underscore

Audio Ducking:
  -sc, --sidechain, -n-sc, --no-sidechain
                        Enable audio side chain compress (ducking) (default: True)
  -sc-args SIDECHAIN_FFMPEG_PARAMS, --sidechain-ffmpeg-params SIDECHAIN_FFMPEG_PARAMS
                        sidechain FFmpeg parameters (default '')
  -sc-lvl SIDECHAIN_LEVEL_SC, --sidechain-level-sc SIDECHAIN_LEVEL_SC
                        Set sidechain gain. Range is between 0.015625 and 64. (default 0.8)

Voicer:
  -v {...}, --voice {...}
                        SAPI voice for voice acting.
  -a ALIGN, --align ALIGN
                        Audio fit align (divisor)
                                1 = right
                                2 = center (default)
  -v-set-a VOICE_SET_ANCHOR, --voice-set-anchor VOICE_SET_ANCHOR
                        Anchor indicating voice actor change (default "!:")

FFmpeg Output:
  -fll {trace,debug,verbose,info,warning,error,fatal,panic,quiet}, --ffmpeg-loglevel {trace,debug,verbose,info,warning,error,fatal,panic,quiet}  
                        FFmpegWrapper loglevel
  -y, --confirm, -n-y, --no-confirm
                        Don't ask for confirmation (default: True)
  -af AUDIO_FORMAT, --audio-format AUDIO_FORMAT
                        Out audio files format (default wav)
  -wm WATERMARK, --watermark WATERMARK
                        Add watermark to output video

Terminal Output:
  -tb, --traceback, -n-tb, --no-traceback
                        Show debug traceback (default: False)

YouTube:
  -yt, --youtube
  -ak API_KEYS [API_KEYS ...], --api-keys API_KEYS [API_KEYS ...]
                        Youtube API key/s

YouTube Search:
  -yts, --youtube-search
                        The input data is a query for searching on YouTube. (Adds "?" at the start of input)
  -yts-l YOUTUBE_SEARCH_LIMIT, --youtube-search-limit YOUTUBE_SEARCH_LIMIT
                        Sets limit to the number of results. Defaults to 20.
  -yts-rg YOUTUBE_SEARCH_REGION, --youtube-search-region YOUTUBE_SEARCH_REGION
                        Sets the result region. Defaults to "US".

YouTube Upload:
  -ytu, --youtube-upload
                        yt_upload video to YouTube channel after voice acting.
  -ytu-ps {private,public,unlisted}, --privacy-status {private,public,unlisted}
                        Video privacy status (If not private, errors are possible)
  -ytu-t, --youtube-upload-translate
                        Translate title and description on upload. (+ Arguments from translate argument group)

Translate:
  -tr, --translate      Translate input subtitles files
  --rewrite-srt, --no-rewrite-srt
                        Rewrite input subtitles files.
                        If not, add "_" to the beginning of the original subtitle file. (default: False)
  -ts {...}, --translate-service {...}
                        Subtitle translation service. (default google)
```

**If the voice set after "!:" is not selected during voiceover, clear the cache with the -rc argument**

## Example

> python -m fastdub -i DirToDub -v "[Yuriy](https://rhvoice.su/downloads/?voice=yuriy&type=sapi)" --no-sidechain -sf vtt
> -vf mkv

All files in the folder will be voices (*.mkv, *.vtt)

Default is mp4 video and srt subtitles.

Then:
_name and name2 will be announced, and the results will be saved to a folder with the appropriate name._

## YT Example

> python -m fastdub **-yt** -i https://youtu.be/DD5UKQggXTc
> -v "[Yuriy](https://rhvoice.su/downloads/?voice=yuriy&type=sapi)"
> -l ru

### YouTube Search Example

> python -m fastdub -yt **-yts** -i "#annoyingorange" -l ru

## Translate Example

> python -m fastdub -i DirToDub -tr **-ts iciba** _-l [ru](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)_

Default service is Google.

## Other

### The `fastdub.utils` module stores helper functions.

### You can write your issues on [GitHub](https://github.com/NIKDISSV-Forever/fastdub/issues) in English or in Russian.

---

# CHANGELOG

# 3.8.0

## General

- `changelog` has been translated into English.
- Added `logging.error`

## FFmpeg Wrapper

- `ffmpeg_wrapper` module objects renamed according to PEP-8
  (`FFMpeg` to `FFmpeg`)

## Translator

- `translator.get_service_by_name` is now a valid function even if required dependencies are not installed, in which
  case if call it will raise `KeyError`

## YouTube

- dependency `pafy` added to `extra_requires/requires_yt.txt`

# 3.7.0

## General

- **Changed minimum supported Python version from 3.8 to 3.9**

## CLI

- Fixed bug with `logging.getLevelNamesMapping()` in `__main__.py`

# 3.6.0

## General

- Package `logging` used
- Bugfix
- optimization

## Audio Processing

- `sidechain` is now much faster using `ffmpeg`

## FFmpeg Wrapper

- The `ffmpeg-imageio` library is no longer used, instead the `ffmpeg` command is always called

## CLI

- Argument `--sidechain-ffmpeg-params` see [FFmpeg Documentation](https://ffmpeg.org/ffmpeg-all.html#sidechaincompress)
- Separate `--sidechain-level-sc` see `level_sc` higher.
- `-ll` is now program loglevel and ffmpeg loglevel is now `-fll`

# 3.5.2

## Translator

- Now it will not cause an error in the absence of the Internet.

## Subtitles

- Fixed possible .srt format differences (now `.` is allowed instead of `,`)

# 3.5.1

## Subtitles

- Fixed possible problems with different encodings (added `chardet` module)

# 3.5.0

## Voiceover Process

- Added argument `--export-video` (`-ev`): `BooleanOptionalAction` if `False` (`--no-export-video`, `-n-ev`)
  only exports audio

# 3.4.2

- Minor improvements and optimizations.

## Subtitles

- The `TimeLabel` class is no longer a subclass of `Line`

# 3.4.1

- Fixed documentation

# 3.4.0

## General

- Added the ability to apply a watermark to the video (see the `--watermark` argument)

## CLI

- Bugfix
- The `--watermark` argument. The text of the watermark is passed to it.
- Now, when launched from the console, the FastDub mini-banner is shown.

## Voiceover Process

- Bugfix
- Now fitted audio (which starts with '_') is always deleted as it's a temporary file

## FFmpeg Wrapper

- Added class method `FFmpegWrapper.get_video_duration_s`
  which is used in `FFmpegWrapper.get_video_duration_ms`
- The video result includes: dubbed audio, original audio, subtitles, original subtitles (if any)

## Submodules

### Translator

- The latest version of the translators module is now used

# 3.3.0

## General

- Implemented class `GlobalSettings`

## Audio Processing

- The `calc_speed_change_ffmpeg_arg` function for calculating the `-af` ffmpeg argument
  for speed change has been changed.

- Significantly accelerated using a different algorithm.

- Optimized `side_chain` function.

## Voiceover Process

- Audio length trimming and TTS are now combined into one process to increase performance.
- Now a subfolder `_result_working_dir` is created in which separate already fitted subtitle lines are saved, after
  which all parts are glued together with ffmpeg.
  Due to this, memory consumption is significantly reduced.
- `moviepy` is no longer a dependency, ffmpeg output is parsed instead

## FFmpeg Wrapper

- Now all arguments are converted to strings before calling `check_call`

# 3.2.0

## CLI

- Omitted optional `type=str` arguments.
- Changed `BooleanOptionalAction` logic, both `--no-` and `-n-` negation are now available.
- The `--cleanup-audio` argument is now `BooleanOptionalAction` (default `True`), `--cleanup-level` has been removed.
- Argument `--voice-set-anchor` (also `!:` by default).
- `--audio-format` argument for output audio (default `wav`).
- The `--sidechain` argument has been renamed to `--side-chain`.
- Added shorthand to `--traceback` argument - `-tb`.

## Voiceover Process

- Bugfix.
- Optimization of track length fitting (Fitting).

## TTS

- `anchor` argument (see `--voice-set-anchor`).
- Voice change optimization.

## Submodules

### YouTube

- When multi-loading, fully loaded videos are removed from the screen (so as not to take up space in vain).