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.

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

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

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.

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.

brew install alass

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

uv tool install assy

pip install assy[torch]

uv tool install assy[torch]

assy

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.

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

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

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

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

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.

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.

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:

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

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 recognize them as already processed.

In the batch list, previously processed videos 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.

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 files and their corresponding subtitle files. When you click Load library, all video 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.

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

Supported naming patterns include:

• S01E01, s01e01 – Standard season/episode format
• 1x01, 01x01 – Alternative format with 'x' separator
• Various other common episode numbering schemes

This feature is particularly useful when you have a folder of video 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.

In Batch Mode, you can pair multiple subtitle files with a single video 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 file and subtitle files in English, Spanish, and French, you can sync all three subtitle files against the video simultaneously.

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

AutoSubSync supports the following subtitle formats:

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

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

• Individual video 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 and subtitle files)
• A mix of files and folders

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

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.

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

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

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/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.

Thanks to creators of ffsubsync, autosubsync, alass, 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.

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

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.