Add subtitle-only download for already-downloaded videos

- download_subs_only(): yt-dlp --skip-download to fetch just .vtt sidecar
- POST /by-yt/{ytId}/download-subs endpoint
- CC chip now visible on downloaded videos; clicking checks YouTube,
  shows lang picker with "Add subtitles" button separate from re-download

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

backend/routers/videos.py

@@ -666,6 +666,22 @@ def get_available_subs(
     return ytdlp.fetch_available_subs(youtube_video_id)
 
 
+@router.post("/by-yt/{youtube_video_id}/download-subs")
+def download_subs(
+    youtube_video_id: str,
+    body: dict,
+    current_user: User = Depends(get_current_user),
+):
+    """Download subtitle file(s) only for an already-downloaded video."""
+    langs = (body.get("subtitle_langs") or "").strip()
+    if not langs:
+        raise HTTPException(status_code=400, detail="subtitle_langs required")
+    ok = ytdlp.download_subs_only(youtube_video_id, langs)
+    if not ok:
+        raise HTTPException(status_code=500, detail="Subtitle download failed")
+    return {"ok": True}
+
+
 @router.get("/by-yt/{youtube_video_id}/subtitle-files")
 def list_subtitle_files(
     youtube_video_id: str,

backend/services/ytdlp.py

@@ -384,6 +384,22 @@ def fetch_channel_links(channel_id: str) -> list[str]:
     return list(channel_ids)
 
 
+def download_subs_only(video_id: str, subtitle_langs: str) -> bool:
+    """Download subtitle files only (no video) for an already-downloaded video."""
+    url = f"https://www.youtube.com/watch?v={video_id}"
+    output_template = str(Path(settings.download_path) / f"{video_id}.%(ext)s")
+    _, _, code = _run([
+        "yt-dlp", url,
+        "--skip-download", "--no-playlist",
+        "--write-subs", "--write-auto-subs",
+        "--sub-langs", subtitle_langs,
+        "--convert-subs", "vtt",
+        "-o", output_template,
+        *_cookie_args(),
+    ], timeout=60)
+    return code == 0
+
+
 def fetch_available_subs(video_id: str) -> dict:
     """Return subtitle languages available on YouTube for a video.
 

frontend/src/api/index.js

@@ -92,6 +92,7 @@ export const createDownload = (youtube_video_id, quality, 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 downloadSubs = (ytId, subtitle_langs) => api.post(`/videos/by-yt/${ytId}/download-subs`, { subtitle_langs });
 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, getSubtitleFiles,
+  getVideoComments, refreshVideoComments, getAvailableSubs, getSubtitleFiles, downloadSubs,
 } from "../api";
 import VideoCard from "../components/VideoCard";
 
@@ -809,6 +809,15 @@ export default function Watch() {
     onSuccess: (res) => setDisliked(res.data.rating === -1),
   });
 
+  const addSubsMut = useMutation({
+    mutationFn: () => downloadSubs(youtubeVideoId, selectedSubLang),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ["subtitle-files", youtubeVideoId] });
+      setSubsRequested(false);
+      setSelectedSubLang("");
+    },
+  });
+
   const handlePiP = useCallback(async () => {
     if (!videoRef.current) return;
     try {
@@ -986,14 +995,17 @@ export default function Watch() {
               )}
 
               {(() => {
-                // 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">
+                // Subs already on disk → show indicator (player CC button handles the rest)
+                if (subtitleFiles.length > 0 && !subsRequested) return (
+                  <button
+                    onClick={() => setSubsRequested(true)}
+                    className="flex items-center gap-1 px-3 py-1.5 rounded-full bg-zinc-800 text-zinc-400 text-xs hover:bg-zinc-700 transition-colors"
+                    title="Subtitles loaded — click to add more languages"
+                  >
                     CC ✓
-                  </span>
+                  </button>
                 );
-                // Before download: let user pick a lang to download with
-                if (dlComplete) return null;
+                // Not yet asked → show CC chip
                 if (!subsRequested) return (
                   <button
                     onClick={() => setSubsRequested(true)}
@@ -1003,6 +1015,7 @@ export default function Watch() {
                     CC
                   </button>
                 );
+                // Loading YouTube subtitle list
                 if (subsLoading) return (
                   <span className="flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-zinc-800 text-zinc-500 text-xs">
                     <span className="w-3 h-3 border border-zinc-600 border-t-transparent rounded-full animate-spin inline-block" />
@@ -1015,16 +1028,29 @@ export default function Watch() {
                   <span className="px-3 py-1.5 rounded-full bg-zinc-800 text-zinc-600 text-xs">No CC</span>
                 );
                 return (
-                  <select
-                    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 to download"
-                  >
-                    <option value="">No subtitles</option>
-                    {[...manual].map(l => <option key={l} value={l}>{l}</option>)}
-                    {auto.map(l => <option key={l} value={l}>{l} (auto)</option>)}
-                  </select>
+                  <>
+                    <select
+                      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"
+                    >
+                      <option value="">No subtitles</option>
+                      {[...manual].map(l => <option key={l} value={l}>{l}</option>)}
+                      {auto.map(l => <option key={l} value={l}>{l} (auto)</option>)}
+                    </select>
+                    {dlComplete && selectedSubLang && (
+                      <button
+                        onClick={() => addSubsMut.mutate()}
+                        disabled={addSubsMut.isPending}
+                        className="flex items-center gap-1 px-3 py-1.5 rounded-full text-xs font-medium bg-accent text-black hover:bg-yellow-300 transition-colors disabled:opacity-50"
+                      >
+                        {addSubsMut.isPending ? (
+                          <span className="w-3 h-3 border-2 border-black/40 border-t-transparent rounded-full animate-spin inline-block" />
+                        ) : null}
+                        {addSubsMut.isPending ? "Fetching…" : "Add subtitles"}
+                      </button>
+                    )}
+                  </>
                 );
               })()}