Welcome to FFsubsync’s documentation!

Indices and tables

Synchronize subtitles with video.

usage: ffsubsync [-h] [-i [SRTIN [SRTIN ...]]] [-o SRTOUT]
                 [--merge-with-reference] [--make-test-case]
                 [--reference-stream REFERENCE_STREAM] [-v]
                 [--overwrite-input] [--encoding ENCODING]
                 [--max-subtitle-seconds MAX_SUBTITLE_SECONDS]
                 [--start-seconds START_SECONDS]
                 [--max-offset-seconds MAX_OFFSET_SECONDS]
                 [--apply-offset-seconds APPLY_OFFSET_SECONDS]
                 [--frame-rate FRAME_RATE] [--skip-infer-framerate-ratio]
                 [--non-speech-label NON_SPEECH_LABEL]
                 [--output-encoding OUTPUT_ENCODING]
                 [--reference-encoding REFERENCE_ENCODING]
                 [--vad {subs_then_webrtc,webrtc,subs_then_auditok,auditok}]
                 [--no-fix-framerate] [--serialize-speech]
                 [--extract-subs-from-stream EXTRACT_SUBS_FROM_STREAM]
                 [--ffmpeg-path FFMPEG_PATH] [--log-dir-path LOG_DIR_PATH]

Positional Arguments

reference Reference (video, subtitles, or a numpy array with VAD speech) to which to synchronize input subtitles.

Named Arguments

-i, --srtin Input subtitles file (default=stdin).
-o, --srtout Output subtitles file (default=stdout).
--merge-with-reference, --merge

Merge reference subtitles with synced output subtitles.

Default: False

--make-test-case, --create-test-case

If specified, serialize reference speech to a numpy array, and create an archive with input/output subtitles and serialized speech.

Default: False

--reference-stream, --refstream, --reference-track, --reftrack
 Which stream/track in the video file to use as reference, formatted according to ffmpeg conventions. For example, 0:s:0 uses the first subtitle track; 0:a:3 would use the third audio track. You can also drop the leading 0:; i.e. use s:0 or a:3, respectively. Example: ffs ref.mkv -i in.srt -o out.srt –reference-stream s:2
-v, --version show program’s version number and exit

If specified, will overwrite the input srt instead of writing the output to a new file.

Default: False


What encoding to use for reading input subtitles (default=infer).

Default: “infer”


Maximum duration for a subtitle to appear on-screen (default=10.000 seconds).

Default: 10


Start time for processing (default=0 seconds).

Default: 0


The max allowed offset seconds for any subtitle segment (default=60 seconds).

Default: 60


Apply a predefined offset in seconds to all subtitle segments (default=0 seconds).

Default: 0


Frame rate for audio extraction (default=48000).

Default: 48000


If set, do not try to infer framerate ratio based on duration ratio.

Default: False


Label to use for frames detected as non-speech (default=0.000000)

Default: 0.0


What encoding to use for writing output subtitles (default=utf-8). Can indicate “same” to use same encoding as that of the input.

Default: “utf-8”

 What encoding to use for reading / writing reference subtitles (if applicable, default=infer).

Possible choices: subs_then_webrtc, webrtc, subs_then_auditok, auditok

Which voice activity detector to use for speech extraction (if using video / audio as a reference, default=subs_then_webrtc).


If specified, subsync will not attempt to correct a framerate mismatch between reference and subtitles.

Default: False


If specified, serialize reference speech to a numpy array.

Default: False

 If specified, do not attempt sync; instead, just extract subtitles from the specified stream using the reference.
--ffmpeg-path, --ffmpegpath
 Where to look for ffmpeg and ffprobe. Uses the system PATH by default.
--log-dir-path Where to save ffsubsync.log file (must be an existing directory).