AutoSubSync: Automatic / Manual Subtitle Synchronization Tool <img title="AutoSubSync Icon" src='https://raw.githubusercontent.com/denizsafak/AutoSubSync/main/images/AutoSubSync.ico' align="right" style="padding-left: 10px; padding-top:5px;">

<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>

AutoSubSync is a user-friendly tool that automatically synchronizes your subtitles with your videos using powerful tools such as ffsubsync, autosubsync and alass. 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.

<img title="AutoSubSync Automatic Tab" src='https://raw.githubusercontent.com/denizsafak/AutoSubSync/main/images/AutoSubSync1.png'> <img title="AutoSubSync Manual Tab" src='https://raw.githubusercontent.com/denizsafak/AutoSubSync/main/images/AutoSubSync2.png'> <img title="AutoSubSync Batch Mode" src='https://raw.githubusercontent.com/denizsafak/AutoSubSync/main/images/AutoSubSync3.png'> <img title="AutoSubSync Processing" src='https://raw.githubusercontent.com/denizsafak/AutoSubSync/main/images/AutoSubSync4.png'>

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

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.

[!NOTE] If you see "cannot be opened because the developer cannot be verified" warning:

• Go to System Settings > Privacy & Security.
• Scroll down and click Open Anyway.
• If it does not work, download the source code and build it on your computer using build.py.

[!IMPORTANT] You need to run this command in your terminal to make alass work in macOS:

brew install alass

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.13:

pip install assy

<details> <summary><strong>With uv (click to expand)</strong></summary>

uv tool install assy

</details>

For Silero VAD support in ffsubsync, install with torch (Python < 3.14):

pip install assy[torch]

<details> <summary><strong>With uv (click to expand)</strong></summary>

uv tool install assy[torch]

</details>

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.13, 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

[!TIP] For detailed instructions, go the Docker guide:

Go to Docker Guide

How to use?

Automatic Synchronization

1. Drag a video file into the Video/Reference Subtitle field
2. Drag a subtitle file into the Subtitle field
3. Select a sync tool (ffsubsync, autosubsync, or alass)
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

Features

Automatic Synchronization

Synchronize subtitles with video files using one of three 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.

Instead of using a video file as the source, you can also use a correctly-timed reference subtitle file. This is useful when you have subtitles in one language that are already synchronized and want to sync subtitles in another language to match.

---

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 multiple video-subtitle pairs in a single operation. Enable batch mode to access the batch list and additional file management options.

Adding files to the batch list:

| Option | Description | |--------|-------------| | Add pair | Manually select a video file and a subtitle file to add as a pair. | | Add pair (continuously) | Keep adding video-subtitle pairs until you cancel. | | Add folder | Select a folder to scan for video and subtitle files, including all subfolders. (Videos and subtitles with matching filenames will be paired automatically.) | | Add multiple files | Select multiple files at once to add to the list. (Videos and subtitles with matching filenames will be paired automatically.) | | Auto-Pairing with Season/Episode | Automatically match videos with subtitles based on episode patterns (see Auto-Pairing with Season/Episode). | | Pair multiple subtitles with single source | Pair multiple subtitle files with one video (see Pair multiple subtitles with single source). |

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

---

Sync Tracking

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

Videos are identified by their content using a hash, not by their filename or location. This means you can rename, move, or reorganize your videos and AutoSubSync will still recogniz