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 handling, encoding, styling, and precise timing synchronization.

Automatic Subtitle Matching

HorangPlayer uses mpv's sub-auto=fuzzy option for automatic subtitle file matching. When you open a video, mpv scans the same directory for subtitle files with similar names.

For example, if you open:

Movie.2024.1080p.BluRay.mkv

mpv will automatically find and load:

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

The fuzzy matching tolerates differences in quality tags, language codes, and minor naming variations.

Subtitle Formats

All subtitle rendering is handled by mpv natively — no custom parsers needed.

SRT (SubRip)

The most common format. Plain text with timestamps. mpv handles 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.

mpv's built-in libass renderer 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.

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. mpv's subtitle pipeline handles encoding detection automatically, for both external and embedded subtitle files.

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.

Why mpv Native Subtitles?

By delegating all subtitle rendering to mpv, we get:

• No separate overlay — Subtitles are composited directly in the render pipeline
• Full ASS styling — libass support with all style tags, fonts, and animations
• Embedded subtitles — MKV files with built-in subtitle tracks just work
• Multiple tracks — Switch between subtitle tracks on the fly
• PGS support — Bitmap subtitles from Blu-ray discs
• Zero maintenance — No custom parsers to maintain or debug

Early versions of HorangPlayer had custom SRT, ASS, and VTT parsers with a SwiftUI subtitle overlay. We removed all of that in favor of mpv's native rendering — it's more capable, more reliable, and handles edge cases we'd never think to test.