AutoSubSync: Automatic / Manual Subtitle Synchronization Tool

AutoSubSync is a user-friendly tool that automatically synchronizes your subtitles with your videos or audio files using powerful tools such as ffsubsync, autosubsync, alass and lapse. It also lets you manually adjust the subtitle timings. Just drag and drop your files, and let AutoSubSync do the rest, making subtitle alignment both simple and efficient.

How to install?

Windows

1. Download the latest AutoSubSync-windows-amd64.zip.
2. Extract the ZIP file.
3. Double-click AutoSubSync.exe to run.

Linux

1. Download the latest AutoSubSync-linux-amd64.AppImage.
2. Double-click AutoSubSync-linux-amd64.AppImage to run.

If you see any permission issues, you may need to make the AppImage executable:

chmod +x AutoSubSync-linux-amd64.AppImage

Debian, Ubuntu, and Linux Mint

Download the latest AutoSubSync-linux-amd64.deb and double-click it to install it with your software installer. The package installs the application under /opt/autosubsync, adds the autosubsync command, and creates a desktop launcher.

Arch Linux

You can also download AutoSubSync from AUR in Arch Linux using the following command:

yay -S autosubsync-bin

Thanks to @Rainoutt for the AUR package.

macOS

1. Download the appropriate ZIP for your Mac:
   • Apple Silicon (M1/M2/M3): AutoSubSync-macos-arm64.zip
   • Intel: AutoSubSync-macos-amd64.zip
2. Extract the ZIP file.
3. Double-click AutoSubSync to run.

PyPI (All Platforms)

You can install AutoSubSync using either pip or uv (a fast Python package manager) on any platform with Python 3.10 - 3.14:

pip install assy

uv tool install assy

Then run:

assy

If your system Python is not compatible (e.g., macOS with older Python):

If your system Python version is below 3.10 or above 3.14, the recommended solution is to use uv to install and run AutoSubSync with a compatible Python version automatically.

First, install uv by following the instructions at astral.sh/uv.

Then, simply run:

uv tool install assy
# Then run with:
assy

This will ensure you have a compatible Python version and the latest AutoSubSync installed, regardless of your system Python.

You can install uv from astral.sh/uv.

Docker Guide

Thanks to @IlmariKu in PR #61, you can run AutoSubSync in a Docker container. This makes it easier to deploy and run AutoSubSync in different environments without worrying about dependencies.

# Navigate to the AutoSubSync directory
cd AutoSubSync

# Create input and output directories
mkdir -p input output desktop

# Build and run the container
docker-compose up --build -d

To access the GUI, open your web browser and go to: http://localhost:6080

How to use?

Automatic Synchronization

1. Drag a video, audio file, or reference subtitle into the Video/Reference Subtitle field
2. Drag a subtitle file into the Subtitle field
3. Select a sync tool (ffsubsync, autosubsync, alass, or lapse)
4. Click Start

Batch Mode

1. Enable Batch Mode
2. Drag files or folders into the batch area
3. Use Auto-Pairing if needed
4. Click Start

Manual Adjustment

1. Go to the Manual tab
2. Load a subtitle file
3. Enter the time shift in milliseconds
4. Select output location
5. Click Start

Command-line interface (assy-cli)

For autonomous pipelines, CI/CD, scheduled jobs, and Docker, AutoSubSync ships a fully-featured CLI that never starts a Qt event loop or requires a display.

# Auto-sync one subtitle (machine-readable output)
assy-cli sync video.mkv subs.srt -o synced.srt --json
# {"ok": true, "input": "subs.srt", "output": "synced.srt", "tool": "ffsubsync", ...}

# Use an audio file as the sync reference
assy-cli sync audio.mp3 subs.srt -o synced.srt

# Prefer a matching embedded subtitle stream as the sync reference
assy-cli sync video.mkv subs.srt --embedded-subtitles

# Shift a subtitle by 1.5 seconds
assy-cli shift subs.srt 1500 -o shifted.srt

# Batch sync a folder of pairs and continue past failures
assy-cli batch --folder ./episodes --continue-on-error --json

# Two-folder pairing with explicit output dir
assy-cli batch --video-dir ./videos --subtitle-dir ./subs -o ./out --json

# Enable embedded-subtitle references for every video in a batch
assy-cli batch --folder ./episodes --embedded-subtitles

# Pick a sync engine per call
assy-cli sync video.mkv subs.srt -t alass

# Add a custom suffix to the output filename
assy-cli sync video.mkv subs.srt --suffix "_custom"

# Inspect or persist user config
assy-cli config path
assy-cli config get sync_tool
assy-cli config set sync_tool alass

The sync and batch commands accept --embedded-subtitles and --no-embedded-subtitles. These flags override the selected tool's saved setting for that invocation. Without either flag, the saved setting and tool default are used.

Exit codes: 0 success · 1 at least one sync failed · 2 usage or config error · 130 SIGINT.

Needs review: LAPSE results marked as unsure or nothing, and autosubsync results with a low-quality warning, are reported with needs_review: true in JSON output and as warnings in human-readable logs.

JSON mode (--json) writes structured results to stdout (one object per sync; for batch, NDJSON plus a final {"summary": ...} line) while human-readable logs go to stderr. Pipe straight into jq:

assy-cli sync video.mkv subs.srt --json | jq -r '.output'

Run from Docker with no display:

docker build -f Dockerfile.cli -t autosubsync-cli .
docker run --rm -v "$PWD:/data" autosubsync-cli sync /data/video.mkv /data/subs.srt -o /data/out.srt

Or via compose: docker compose --profile cli run --rm assy-cli sync /data/video.mkv /data/subs.srt.

Features

Automatic Synchronization

Synchronize subtitles with video or audio files using one of four available synchronization tools. Each tool uses a different approach, so if one doesn't produce satisfactory results, you can try another.

• ffsubsync – Analyzes the audio track of the video and aligns subtitles to match the speech. Works well for most content.
• autosubsync – Uses machine learning to detect speech patterns and synchronize subtitles accordingly.
• alass – Can align subtitles using either audio analysis or a reference subtitle file. Generally faster than other tools, and most of the time produces accurate results.
• lapse – Language-Agnostic Playback Synchronization Engine. A fast C++ engine built on FFmpeg, libfvad/Silero VAD, and FFTW3. Supports video, audio, and subtitle references, linear drift correction, and split mode for cuts. AutoSubSync keeps LAPSE updated automatically and stores downloaded updates in your user data folder.

In addition to video files, you can use an audio file or a correctly-timed reference subtitle file as the source. Audio references are converted to a temporary MP4 automatically; enable Keep converted audio files in Settings to keep the converted file. Supported audio references include MP3, M4A, AAC, FLAC, OGG/OGA, OPUS, WAV, WMA, AIFF/AIF, APE, and MKA. Reference subtitles are useful when you have subtitles in one language that are already synchronized and want to sync subtitles in another language to match.

Results that a tool is unsure about, or low-quality matches from autosubsync, are marked Needs review in orange instead of being reported as successful.

Sync Tool Settings

Each sync tool has its own settings on the Automatic tab. Use Other options for advanced tool-specific settings, and Additional arguments for custom command-line flags. Additional arguments take priority over the app's settings, so you won't pass the same option twice. Use Restore to defaults to reset the selected tool to its defaults while keeping your Additional arguments.

Advanced settings include ffsubsync quality and offset limits, segmented sampling, audio-track selection, strict mode, and maximum duration; ALASS negative timestamps, alignment interval, and subtitle framerate; and LAPSE confidence, snapping, audio-track, and minimum-shift controls.

Manual Synchronization

Shift all subtitle timings by a specified number of milliseconds. Use positive values to delay subtitles (make them appear later) or negative values to advance them (make them appear earlier).

This is useful for fine-tuning results after automatic synchronization, or when you know the exact offset needed. The interface provides increment and decrement buttons for small adjustments, or you can enter a specific value directly.

You can choose to save the adjusted subtitle to your desktop as a new file, or replace the original subtitle file.

Batch Processing

Process many subtitles against their video, audio, or reference subtitle sources in a single operation. Enable batch mode to access the batch list and additional file management options.

Adding files to the batch list:

You can also right-click a subtitle item and choose Add video/reference to this item to pair it with a video, audio file, or reference subtitle.

You can also drag and drop files or folders directly onto the batch list.

Sync Tracking

AutoSubSync maintains a database of reference files (videos or audio files) that have been synchronized previously. When you add references to the batch list, any references that have been previously processed are automatically identified and marked to be skipped. This feature is designed for reference files only; subtitle files are not tracked.

References are identified by their content using a hash, not by their filename or location. This means you can rename, move, or reorganize your references and AutoSubSync will still recognize them as already processed.

In the batch list, previously processed references appear greyed out with a Status: Skipped tooltip.

Right-click on items in the batch list to access the following options:

Sync tracking menu options:

Location: Settings → Sync tracking, or the Sync tracking button in Batch Mode

You can locate your processed items database file (processed_items.db) using Open config file directory in the Settings menu.

Library Manager

Save folders containing your media files for quick access. The Library Manager stores your folder list in a database that persists between sessions.

Add folders that contain video or audio files and their corresponding subtitle files. When you click Load library, all video, audio, and subtitle files from your saved folders are loaded into the batch list. This is useful if you regularly work with the same media collection and want to quickly check for new content to process.

You can add new folders, remove individual folders, or clear the entire list.

Location: Settings → Sync tracking → Manage library folders, or Batch Mode → Sync tracking → Manage library folders

You can locate your library database file (library_folders.db) from Open config file directory in the Settings menu.

Auto-Pairing with Season/Episode

When working with TV series or other episodic content, AutoSubSync can automatically match video or audio files with their corresponding subtitle files based on season and episode information in the filenames.

Supported naming patterns include:

• S01E01, s01e01, S01E156 – Standard season/episode format, including longer episode numbers
• E01, EP01, Episode 1, Episode.1, Ep 01, bölüm 3 – Episode-only formats (assume season 1)
• 1x01, 01x01 – Alternative format with 'x' separator
• Part 2, Pt2 – Part-based numbering (assumes season 1)
• E001 and other longer episode numbers

Years, video resolutions, and codec names are not treated as episode numbers.

This feature is particularly useful when you have a folder of video or audio files and a separate folder of subtitle files that need to be paired up.

Location: Enable Batch Mode, then click input box to open the batch add menu, and select Auto-Pairing with Season/Episode.

Pair Multiple Subtitles with Single Source

In Batch Mode, you can pair multiple subtitle files with a single video, audio file, or reference subtitle. This allows you to synchronize subtitles in several languages against the same source in one batch operation.

For example, if you have a video or audio file and subtitle files in English, Spanish, and French, you can sync all three subtitle files against the same source simultaneously.

Location: Enable Batch Mode, then click input box to open the batch add menu, and select Pair multiple subtitles with single source.

Supported Input Subtitle Formats

AutoSubSync supports the following subtitle formats:

Subtitles can be converted between formats during the synchronization process if needed.

LAPSE also reads VobSub .idx files together with their matching .sub file. AutoSubSync copies the .sub file alongside the synced .idx output.

Drag and Drop

The interface supports drag and drop for all file inputs. You can drag:

• Individual video, audio, or subtitle files onto their respective input fields
• Multiple files onto the batch list
• Entire folders onto the batch list (AutoSubSync will scan for video, audio, and subtitle files)
• A mix of files and folders

This eliminates the need to navigate through file browser dialogs for most operations.

Interface Languages

The application interface is available in 23 languages:

English, Español, Deutsch, Français, Italiano, Polski, Português, Türkçe, Tiếng Việt, Bahasa Indonesia, Bahasa Melayu, ไทย, Українська, Русский, 中文, 繁體中文, 日本語, 한국어, हिन्दी, বাংলা, العربية, فارسی, اردو

Change the language from Settings → Language. The interface will update after restarting the application.

Special thanks to @bayramhayri for translations.

Settings

Access settings via the gear icon in the top right corner.

Contributing

I welcome contributions! If you have ideas for new features, improvements, or bug fixes, please fork the repository and submit a pull request.

For developers and contributors

If you'd like to modify the code and contribute to development, you can download the repository, extract it and run the following commands to install the package:

# Go to the directory where you extracted the repository and run:
pip install -e .[dev]     # Installs the package in editable mode with dev dependencies
assy                    # Opens the GUI
assy-cli                # Alternative CLI command
python build.py           # Builds standalone executables (AppImage/.deb/Windows/macOS)
python build_pypi.py      # Builds PyPI package to dist/pypi folder

Requires Python 3.10 or higher. Feel free to explore the code and make any changes you like.

Credits

Thanks to creators of ffsubsync, autosubsync, alass, lapse, ffmpeg and others. Automatic subtitle synchronization is possible because of these tools. This is just a GUI application that makes the process a bit easier.

How to uninstall?

Before uninstalling, you may want to cleanup your settings and logs. Open AutoSubSync and go to:

• Settings → Open config file directory to locate your configuration files and databases. (You may want to back up these files if you plan to reinstall AutoSubSync later.)
• Settings → Open logs directory to delete log files.

Then, follow the appropriate method below based on how you installed AutoSubSync:

pip uninstall assy

uv tool uninstall assy

yay -R autosubsync-bin

sudo apt remove autosubsync

Tags: automatic subtitle synchronization, autosubsync, automatic sub sync, subtitle synchronization, resync subtitles, re-sync subtitles, subtitle shifter, subtitle adjuster, subtitle tools, subtitle utilities, synchronize subtitles, adjust subtitle timing, subtitle management, Python subtitle tool, subtitle manipulation, subtitle synchronization script, subtitle sync fixing, subtitle sync fix, fix subtitle sync.