VideoSubtitle 影片字幕播放器

A SwiftUI video player for iPhone, iPad, and Mac that plays local videos with SRT subtitles overlaid in sync with playback.

用 SwiftUI 打造的影片播放器，支援 iPhone、iPad 與 Mac，可搭配 SRT 字幕檔同步顯示字幕。

English | 中文說明

English

Download: grab the notarized macOS app from the latest release — unzip and drag it to Applications. For iPhone/iPad, build from source with Xcode.

Features

• Video playback — pick any local video (MP4, MOV, …) with the file picker and play it with AVPlayer.
• SRT subtitles — load an SRT file and the subtitles appear over the video, synced to the playback time (periodic time observer at 0.1 s + binary search over cues). Seeking keeps subtitles in sync.
• Auto-detection of matching subtitles — when you open a video, the app looks for an .srt file with the same base name in the same folder and loads it automatically:
  • iOS / iPadOS: works out of the box for files stored in the app's folder (Files ▸ On My iPhone ▸ VideoSubtitle — file sharing is enabled).
  • macOS (sandboxed): grant access to your video folder once via Authorize Folder… (in the status bar or the settings menu). The app remembers the folder with a security-scoped bookmark, so every video you open from it afterwards auto-loads its matching subtitle — even after relaunching.
• Robust SRT parsing — CRLF/LF line endings, UTF-8 BOM, , or . millisecond separators, multi-line cues, missing index lines; strips <i>/<font> HTML tags and {\an8} ASS style tags.
• Automatic text-encoding detection — tries UTF-8 → UTF-16 (BOM) → Big5 → GB18030 → Shift-JIS → Latin-1, so legacy Chinese/Japanese subtitle files just work.
• Subtitle timing offset — nudge subtitles ±0.5 s at a time when they are out of sync, and reset with one tap.
• Show/hide subtitles from the settings menu.

Requirements

• Xcode with the iOS 27 / current macOS SDK
• Runs on iPhone, iPad, and natively on Mac (the Mac target is sandboxed; entitlements are included)

Project structure

File	Responsibility
VideoSubtitle/SubtitleCue.swift	Subtitle cue model (start/end time + text)
VideoSubtitle/SRTParser.swift	SRT parsing and text-encoding detection
VideoSubtitle/PlayerModel.swift	@Observable player model: video/subtitle loading, time-synced cue lookup, folder authorization with security-scoped bookmarks, related-item file coordination
VideoSubtitle/ContentView.swift	UI: player (AVKit VideoPlayer on iOS, AVPlayerView on macOS), subtitle overlay, file importers, settings menu

Implementation notes

• currentCue is a stored property and SubtitleCue conforms to Equatable, so the 10 Hz time observer only invalidates the UI when the visible subtitle actually changes.
• On macOS the SwiftUI VideoPlayer is replaced with an NSViewRepresentable-wrapped AVKit AVPlayerView (the SwiftUI wrapper has layout issues on macOS).
• The .srt type is declared in Info.plist (UTImportedTypeDeclarations) so SRT files are selectable in the file picker, plus CFBundleDocumentTypes entries with NSIsRelatedItemType for the sandbox's related-items mechanism.

中文說明

**下載：**到最新版本下載已通過 Apple 公證的 macOS App，解壓縮後拖進「應用程式」即可使用；iPhone／iPad 請用 Xcode 從原始碼建置。

功能

• 影片播放 — 用檔案選擇器挑選本機影片（MP4、MOV⋯），以 AVPlayer 播放。
• SRT 字幕 — 載入 SRT 檔後字幕會疊在影片上，跟著播放時間同步顯示（每 0.1 秒的時間觀察器＋二分搜尋），拖動進度條字幕也會跟著跳轉。
• 自動偵測同名字幕 — 開啟影片時，自動尋找同資料夾、同主檔名的 .srt 並載入：
  • iOS / iPadOS：放在 App 資料夾（檔案 ▸ 我的 iPhone ▸ VideoSubtitle）內的影片直接支援（已啟用檔案共享）。
  • macOS（沙盒版）：透過狀態列或設定選單的「授權影片資料夾…」授權一次，App 會用 security-scoped bookmark 永久記住 — 之後從該資料夾開啟的每部影片都會自動載入同名字幕，重新啟動也有效。
• 強健的 SRT 解析 — 支援 CRLF/LF、UTF-8 BOM、, 或 . 毫秒分隔、多行字幕、缺編號行；自動移除 <i>/<font> 等 HTML 標籤與 {\an8} ASS 樣式標籤。
• 自動偵測文字編碼 — 依序嘗試 UTF-8 → UTF-16（BOM）→ Big5 → GB18030 → Shift-JIS → Latin-1，舊的中日文字幕檔也能正常顯示。
• 字幕時間位移 — 字幕不同步時可每次 ±0.5 秒微調，一鍵重設。
• 可隨時從設定選單顯示／隱藏字幕。

環境需求

• 含 iOS 27／最新 macOS SDK 的 Xcode
• 支援 iPhone、iPad 與原生 Mac（Mac 版已沙盒化，entitlements 已附上）

程式結構

檔案	職責
VideoSubtitle/SubtitleCue.swift	字幕資料模型（起訖時間＋文字）
VideoSubtitle/SRTParser.swift	SRT 解析與文字編碼偵測
VideoSubtitle/PlayerModel.swift	@Observable 播放器模型：影片／字幕載入、時間同步查找、資料夾授權（security-scoped bookmark）、related-item 檔案協調
VideoSubtitle/ContentView.swift	UI：播放器（iOS 用 AVKit VideoPlayer、macOS 用 AVPlayerView）、字幕疊層、檔案選擇器、設定選單

實作筆記

• currentCue 是獨立的儲存屬性且 SubtitleCue 遵循 Equatable，因此每秒 10 次的時間觀察器只有在畫面上的字幕真的變化時才會觸發 UI 更新。
• macOS 改用 NSViewRepresentable 包裝 AVKit 的 AVPlayerView（SwiftUI 的 VideoPlayer 在 macOS 有版面問題）。
• .srt 類型在 Info.plist 以 UTImportedTypeDeclarations 宣告（讓 SRT 檔在檔案選擇器中可選），並加上帶 NSIsRelatedItemType 的 CFBundleDocumentTypes 供沙盒的 related-items 機制使用。