Smart Subtitles: SRT, ASS, and Automatic Matching

Subtitles seem simple on the surface. Display text at the right time. But getting them right involves file detection, format parsing, encoding handling, styling, and precise timing synchronization.

Automatic Subtitle Matching

When you open a video, HorangPlayer automatically scans the same directory for matching subtitle files. The matching algorithm uses Levenshtein distance (edit distance) to find the best match — even when filenames don't match exactly.

For example, if you open:

Movie.2024.1080p.BluRay.mkv

HorangPlayer will automatically find and load:

Movie.2024.1080p.BluRay.srt
Movie.2024.BluRay.eng.srt
Movie.2024.srt

The algorithm tolerates differences in quality tags, language codes, and minor naming variations. It picks the closest match automatically.

Subtitle Formats

SRT (SubRip)

The most common format. Plain text with timestamps:

1
00:01:30,000 --> 00:01:33,500
Hello, world!

HorangPlayer parses SRT with full support for multi-line entries, HTML-style formatting tags, and various timestamp formats.

ASS / SSA (Advanced SubStation Alpha)

The most powerful subtitle format. ASS files contain styling information — fonts, colors, sizes, positioning, fade effects, and even animations.

With mpv's built-in libass renderer, HorangPlayer displays ASS subtitles exactly as the author intended. This is critical for anime fansubs and professionally styled subtitles where positioning and typography matter.

VTT (WebVTT)

The web standard for subtitles, commonly found with streaming content. Full parsing support with cue settings.

PGS (Presentation Graphic Stream)

Bitmap-based subtitles from Blu-ray discs. mpv handles these natively when embedded in MKV containers.

Encoding Detection

Subtitle files come in many encodings — UTF-8, Latin-1, EUC-KR, Shift_JIS, GB2312. HorangPlayer attempts UTF-8 first, then falls back to the system encoding. mpv's subtitle pipeline handles encoding detection automatically for embedded subtitles.

Audio Delay Compensation

Sometimes subtitles are in sync but the audio isn't. HorangPlayer supports audio delay adjustment — shift the audio track forward or backward in 100ms increments, up to ±5 seconds. This is applied through mpv's audio-delay property, which adjusts the A/V sync without re-encoding.

mpv's Subtitle Advantage

With the mpv backend, subtitle rendering is integrated directly into the video output. This means:

• No separate overlay — Subtitles are composited at the render level
• Proper ASS styling — Full libass support with all style tags
• Embedded subtitles — MKV files with built-in subtitle tracks just work
• Multiple tracks — Switch between subtitle tracks on the fly

The AVFoundation backend uses a separate SwiftUI subtitle overlay for SRT/VTT files, which works well for simple formats but can't match mpv's ASS rendering capabilities.