---

name: subtitle-sync description: "Use and troubleshoot VSE's bundled Sushi subtitle timeline synchronizer for SRT/ASS files, source/destination videos, CLI flags, GUI Sync Timeline, and media-tool prerequisites." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Subtitle Sync

Use this sub-skill when the user already has a subtitle file and wants to align it from a source video to a destination video using VSE's bundled Sushi synchronizer. This is different from extracting hard-coded subtitles from video.

Read first

• workflows: GUI and CLI synchronization paths.
• CLI reference: Sushi flags and defaults.
• API reference: subtitle_sync, parser, and algorithm surfaces.
• troubleshooting: missing files, ffmpeg/media tools, keyframes/timecodes, output collisions, and unsafe temp cleanup.
• Use scripts/sushi_command_builder.py to construct a command without running ffmpeg or mutating files.

Route elsewhere

• Hard-subtitle OCR extraction: extraction-workflows.
• OCR backend setup: ocr-backends.
• SRT text cleanup after extraction: postprocessing-config.