AutoSubSync puts four subtitle alignment engines behind one window

Four engines, and the choice belongs to the user

The core idea is that subtitle synchronisation is not one algorithm. AutoSubSync is described as a user friendly tool that automatically synchronises subtitles with videos using powerful tools such as ffsubsync, autosubsync, alass and lapse, and the same four are offered in the interface as a choice. That choice is the design. The tool does not hide that, it exposes the choice, and the user picks a sync tool and clicks Start. The audience is anyone with a video and a subtitle file that has drifted, which in practice means translators, archivists and anyone who has assembled a video from separate sources. The alternative to using it is a manual offset in a player, which is fine for one file and painful for a hundred.

The GUI does the simple case in three steps

The automatic tab is the shortest path through the tool. You drag a video file into the Video or Reference Subtitle field, drag a subtitle file into the Subtitle field, select a sync tool from the four available, and click Start. The manual tab exists for the case where no engine can find the right answer. You go to the Manual tab, load a subtitle file, enter the time shift in milliseconds, select the output location and click Start. That is a fixed offset applied to the whole file, which is the case where a video was re-encoded and the audio drifted slightly but the subtitles are otherwise correct. There is also a batch mode, where you enable Batch Mode, drag files or folders into the batch area, use Auto-Pairing if needed, and click Start. The screenshots in the README show four states of the application, the automatic tab, the manual tab, the batch mode and the processing view, and the project ships an Example application as well as a build.py and a build.spec for the packaged binaries.

assy-cli is the part that belongs in a pipeline

The CLI is the most interesting addition, because it is the reason this project can be used in automation. The documentation describes assy-cli as a fully featured CLI that never starts a Qt event loop and never requires a display, aimed at autonomous pipelines, CI/CD, scheduled jobs and Docker. The invocation is ordinary:

# 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", ...}

The --json flag gives structured output with the ok field, the input and output paths and the tool that was used, which is what a script needs to decide whether to fail or try the next engine. There is also a flag for using an embedded subtitle stream as the sync reference, which removes the need for a separate reference file when the video already carries one:

assy-cli sync video.mkv subs.srt --embedded-subtitles

The project registers two entry points in pyproject.toml, assy as a GUI script pointing at main.main:main and assy-cli as a console script pointing at main.cli:main, so the same install gives you both, and the headless one is a separate module rather than a flag on the desktop application. That separation is what makes it usable in a container without an X server.

Five ways to install, and the PyPI name is not the project name

The distribution is broad, and the first thing to get right is that the package on PyPI is called assy, not autosubsync. On any platform with Python 3.10 to 3.13 the install is:

pip install assy

and the application is then started with:

assy

The alternative for systems whose Python is out of range is uv, which installs a compatible interpreter for you:

uv tool install assy
assy

Beyond Python there are prebuilt binaries. On Windows you download AutoSubSync-windows-amd64.zip, extract it and run AutoSubSync.exe. On Linux there is an AppImage, AutoSubSync-linux-amd64.AppImage, which may need to be made executable with chmod +x. On macOS there are two archives, arm64 for Apple Silicon and amd64 for Intel, and the documentation flags the gatekeeper warning with the route through System Settings, Privacy and Security and Open Anyway, or building from source with build.py. There is also an Arch User Repository package, installed with yay -S autosubsync-bin, maintained by a contributor rather than the author.

The container is a Linux desktop, not a server API

The Docker route, contributed in a pull request, is the way to run the desktop application on a machine with no desktop. The compose file builds from the Dockerfile and publishes two services. The first is the GUI, with the web interface on port 6080 and an optional VNC port on 5900, input and output directories mounted from the working directory, and a desktop directory mounted at the home path. The Dockerfile is built on python:3.11-slim-bookworm and installs an X virtual framebuffer, x11vnc, fluxbox as the window manager, supervisor, the Qt 6 libraries and noVNC, cloned from its repository, with websockify alongside it and a symlink so the vnc.html entry point is served at the index. The second service is a headless CLI image built from a separate Dockerfile.cli, run with a profile so it only starts when invoked explicitly:

cd AutoSubSync
mkdir -p input output desktop
docker-compose up --build -d

The interface is then reached at http://localhost:6080. The distinction matters: the container gives you a real desktop over a browser, not a service API, and the headless image is the one to script against.

The Python dependencies pull in the engines and a model runtime

The dependency list explains what the tool actually does at runtime. The project depends on PyQt6 for the interface, rich for the terminal output of the CLI, static-ffmpeg for the bundled ffmpeg handling, and the four sync engines are declared as Python packages, ffsubsync and autosubsync among them, while alass and lapse are external programs, which is why the macOS instructions require brew install alass for alass to work. onnxruntime is also required, and that is a heavy runtime dependency to pull in for a subtitle offset. Encoding detection is handled with charset-normalizer and chardet, with faust-cchardet added on Python versions below 3.13, and requests is used for network access. The project classifies itself as Development Status 5, Production/Stable, requires Python 3.10 or above, and lists support for Python 3.10 through 3.14 with the operating system marked as independent and the environment as X11 applications using Qt.

GPL 3.0, and a project that ships fast

The licence is GPL-3.0-or-later, stated in pyproject.toml and with a LICENSE file in the repository, and that has consequences worth thinking about before you build anything on top of it. The application itself is fine to run, and a pipeline that calls assy-cli as an external process is a clean arrangement. Distributing a modified version of the application, or a work that links it as a library in the way the GPL covers, means you have to offer the corresponding source to whoever receives it. The project is a desktop tool rather than a library, so the common case is the first one rather than the second, but it is the reason to read the terms rather than assume. On activity, the releases come often, v6.3 on 2025-12-06, v6.4 on 2026-05-19 and v6.5 on 2026-08-17, and the last push was on 2026-08-17. There is a CHANGELOG file, a tests/ directory, a DOCKER.md, a run-docker.sh and a run-docker.bat, and the project describes itself as user friendly, which for a tool with four engines and a manual millisecond offset is a claim the interface has to earn.

Editorial conclusion

AutoSubSync is the right tool for the common case of a subtitle file that is simply offset from the video, because it offers four different alignment strategies and lets you pick the one that suits the footage instead of guessing an offset by hand. It is the wrong tool for a batch pipeline on a server, where the desktop application is dead weight even though assy-cli exists, and it is the wrong tool for a commercial product you intend to ship, because the GPL 3.0 licence obliges you to offer the corresponding source of a distributed derivative. Before adopting it, check that the container image gives you the GUI you actually need over noVNC, and confirm that alass and lapse are installed, since ffsubsync and autosubsync arrive as Python dependencies while those two are external programs.

Frequently asked questions

Official sources

1. denizsafak/AutoSubSync on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases