Installation

ffsubsync is a Python package that shells out to ffmpeg for audio extraction. Installation is therefore two steps: install ffmpeg, then install the Python package.

Install ffmpeg

ffmpeg (and its companion ffprobe) must be available before ffsubsync can read a video or audio reference. On macOS with Homebrew:

$ brew install ffmpeg

On Debian/Ubuntu:

$ sudo apt install ffmpeg

Windows users should make sure ffmpeg is on the PATH and can be invoked from the command line. If ffmpeg lives somewhere unusual, you can always point ffsubsync at it explicitly with --ffmpeg-path (see Advanced options).

Note

ffmpeg is only required when the reference is a video or audio file. If you sync against an already-correct subtitle file (see Reference types), no audio is extracted and ffmpeg is not needed.

Install ffsubsync

ffsubsync is compatible with Python 3.6 and newer. Grab it from PyPI:

$ pip install ffsubsync

Installing the package registers three equivalent console commands — ffs, subsync, and ffsubsync — all of which do the same thing. The rest of these docs use ffs for brevity.

To live on the bleeding edge, install the latest revision straight from GitHub:

$ pip install git+https://github.com/smacke/ffsubsync@latest

The optional torch extra

The neural silero and fused voice-activity detectors (see Voice-activity detectors (--vad)) require PyTorch, which is not installed by default because it is large. Pull it in with the torch extra:

$ pip install "ffsubsync[torch]"

or install torch yourself alongside a plain ffsubsync install. The default WebRTC detector needs none of this.

Encoding detectors

The character-encoding detectors ffsubsync uses to read subtitle files are ordinary dependencies and install automatically. There is one cross-version wrinkle — the fastest detector is only available on Python < 3.13 — which is covered in detail in Character encoding.

Docker

Prebuilt images are published to the GitHub Container Registry if you would rather not install anything locally:

$ docker pull ghcr.io/smacke/ffsubsync:latest
$ docker run --rm -v "$PWD":/video ghcr.io/smacke/ffsubsync:latest \
    video.mp4 -i unsynchronized.srt -o synchronized.srt

Mount the directory containing your video and subtitles into /video. You can also build the image yourself from a checkout with docker build -t ffsubsync ., optionally pinning a released version with --build-arg FFSUBSYNC_VERSION=0.4.31.