Fix subtitle playback: vtt format, track elements, fast disk scan

- Convert subs to .vtt (was .srt which browsers don't support in <track>)
- Add GET /subtitle-files endpoint: instant disk scan for .vtt sidecar files,
  no yt-dlp call needed
- Inject <track> elements into the video player for each .vtt on disk;
  browser CC button appears automatically
- Before download: CC chip triggers YouTube availability check (slow, on demand)
- After download with subs: shows "CC ✓" — subtitles live in the player controls

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/routers/videos.py

@@ -662,10 +662,31 @@ def get_available_subs(
     youtube_video_id: str,
     current_user: User = Depends(get_current_user),
 ):
-    """Return subtitle languages available on YouTube for a video."""
+    """Return subtitle languages available on YouTube for a video (yt-dlp call, slow)."""
     return ytdlp.fetch_available_subs(youtube_video_id)
 
 
+@router.get("/by-yt/{youtube_video_id}/subtitle-files")
+def list_subtitle_files(
+    youtube_video_id: str,
+    current_user: User = Depends(get_current_user),
+):
+    """List .vtt subtitle files already on disk for a downloaded video (instant)."""
+    import re as _re
+    from pathlib import Path
+    from ..config import settings as _cfg
+    pat = _re.compile(rf'^{_re.escape(youtube_video_id)}\.(.+)\.vtt$')
+    subs = []
+    try:
+        for f in Path(_cfg.download_path).iterdir():
+            m = pat.match(f.name)
+            if m:
+                subs.append({"lang": m.group(1), "url": f"/files/{f.name}"})
+    except Exception:
+        pass
+    return sorted(subs, key=lambda s: s["lang"])
+
+
 @router.get("/by-yt/{youtube_video_id}/comments")
 def get_comments(
     youtube_video_id: str,

backend/services/ytdlp.py

@@ -662,7 +662,7 @@ def start_download(
 
     fmt = QUALITY_FORMATS.get(quality, QUALITY_FORMATS["best"])
     subtitle_args = (
-        ["--write-subs", "--write-auto-subs", "--sub-langs", subtitle_langs, "--convert-subs", "srt"]
+        ["--write-subs", "--write-auto-subs", "--sub-langs", subtitle_langs, "--convert-subs", "vtt"]
         if subtitle_langs else []
     )
 

frontend/src/api/index.js

@@ -91,6 +91,7 @@ export const createDownload = (youtube_video_id, quality, subtitle_langs) =>
   api.post("/downloads", { youtube_video_id, ...(quality ? { quality } : {}), ...(subtitle_langs ? { subtitle_langs } : {}) });
 export const getDownloads = () => api.get("/downloads");
 export const getAvailableSubs = (ytId) => api.get(`/videos/by-yt/${ytId}/subs`);
+export const getSubtitleFiles = (ytId) => api.get(`/videos/by-yt/${ytId}/subtitle-files`);
 export const getDownload = (id) => api.get(`/downloads/${id}`);
 export const deleteDownload = (id) => api.delete(`/downloads/${id}`);
 export const deleteAllDownloads = () => api.delete("/downloads/all");

frontend/src/pages/Watch.jsx

@@ -7,7 +7,7 @@ import {
   getSettings, updateSettings, getRelatedVideos, getDownloads, rateVideo,
   getBookmarks, createBookmark, updateBookmark, deleteBookmark, importChapters, clearChapters,
   getCollections, addToCollection, getQueue,
-  getVideoComments, refreshVideoComments, getAvailableSubs,
+  getVideoComments, refreshVideoComments, getAvailableSubs, getSubtitleFiles,
 } from "../api";
 import VideoCard from "../components/VideoCard";
 
@@ -668,6 +668,12 @@ export default function Watch() {
     enabled: subsRequested && !!youtubeVideoId,
     staleTime: 30 * 60_000,
   });
+  const { data: subtitleFiles = [] } = useQuery({
+    queryKey: ["subtitle-files", youtubeVideoId],
+    queryFn: () => getSubtitleFiles(youtubeVideoId).then(r => r.data),
+    enabled: fileReady,
+    staleTime: Infinity,
+  });
 
   const { data: dlStatus } = useQuery({
     queryKey: ["download-status", downloadId],
@@ -890,7 +896,18 @@ export default function Watch() {
                   if (video?.watch_progress_seconds > 10) v.currentTime = video.watch_progress_seconds;
                   v.play().catch(() => {});
                 }}
-              />
+              >
+                {subtitleFiles.map((s, i) => (
+                  <track
+                    key={s.lang}
+                    kind="subtitles"
+                    src={s.url}
+                    srcLang={s.lang}
+                    label={s.lang}
+                    default={i === 0}
+                  />
+                ))}
+              </video>
             ) : (
               <Placeholder
                 video={video}
@@ -968,12 +985,20 @@ export default function Watch() {
                 </select>
               )}
 
-              {!dlComplete && (() => {
+              {(() => {
+                // After download: subtitle files on disk are served via <track> in the player
+                if (fileReady && subtitleFiles.length > 0) return (
+                  <span className="flex items-center gap-1 px-3 py-1.5 rounded-full bg-zinc-800 text-zinc-400 text-xs" title="Subtitles loaded — use the CC button in the player">
+                    CC ✓
+                  </span>
+                );
+                // Before download: let user pick a lang to download with
+                if (dlComplete) return null;
                 if (!subsRequested) return (
                   <button
                     onClick={() => setSubsRequested(true)}
                     className="flex items-center gap-1 px-3 py-1.5 rounded-full text-xs font-medium bg-zinc-800 text-zinc-400 hover:bg-zinc-700 transition-colors"
-                    title="Check available subtitles"
+                    title="Check available subtitles on YouTube"
                   >
                     CC
                   </button>
@@ -994,7 +1019,7 @@ export default function Watch() {
                     value={selectedSubLang}
                     onChange={(e) => setSelectedSubLang(e.target.value)}
                     className="bg-zinc-800 text-zinc-300 text-xs rounded-full px-3 py-2 border border-zinc-700 focus:outline-none focus:border-accent"
-                    title="Subtitle language"
+                    title="Subtitle language to download"
                   >
                     <option value="">No subtitles</option>
                     {[...manual].map(l => <option key={l} value={l}>{l}</option>)}