feat(player): let editors upload subtitles for a version

Subtitle tracks hang off a version rather than off a video, because re-editing a cut shifts every cue. The file
always lands in our own S3-compatible storage whatever hosts the video, so a Bunny-hosted cut and an R2 one take the
same path: both already play through our own video element, so a track element is all it takes.

Uploads are normalised before they are stored. Whatever arrives, SRT or WebVTT, is parsed into cues and
re-serialised as a canonical WebVTT file, and anything we did not understand is dropped rather than passed through.
That is what makes it safe to serve a user-supplied text file from our own origin. Files saved out of Windows
editors are decoded as windows-1254 or windows-1252 when they are not valid UTF-8, rather than refused.

A YouTube version cannot carry an uploaded track, so the same CC menu drives YouTube's own captions through the
iframe module API. The embed hides YouTube's controls, so until now those captions were unreachable even when the
video had them.

Uploading and deleting take the editor permission rather than the commenter one: a subtitle is part of the
delivered cut, not a comment attachment.

components/video-page/hooks/subtitle-preference.ts

@@ -0,0 +1,32 @@
+/**
+ * The chosen subtitle language, remembered per video the way a player is expected to.
+ *
+ * Shared by both caption paths, so a viewer who turned Turkish on for a Bunny-hosted cut
+ * gets Turkish again on the YouTube version of the same video.
+ */
+
+function preferenceKey(videoId: string): string {
+  return `openframe:subtitle-language:${videoId}`;
+}
+
+export function readStoredSubtitleLanguage(videoId: string): string | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return window.localStorage.getItem(preferenceKey(videoId));
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredSubtitleLanguage(videoId: string, language: string | null): void {
+  if (typeof window === 'undefined') return;
+  try {
+    if (language) {
+      window.localStorage.setItem(preferenceKey(videoId), language);
+    } else {
+      window.localStorage.removeItem(preferenceKey(videoId));
+    }
+  } catch {
+    // A browser with storage disabled still gets subtitles, just not a remembered choice.
+  }
+}

components/video-page/hooks/use-subtitles.ts

@@ -0,0 +1,270 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import {
+  readStoredSubtitleLanguage,
+  writeStoredSubtitleLanguage,
+} from '@/components/video-page/hooks/subtitle-preference';
+import type { Subtitle } from '@/components/video-page/types';
+
+interface UseSubtitlesParams {
+  videoId: string;
+  versionId: string | null;
+  videoRef: RefObject<HTMLVideoElement | null>;
+  /** Only the providers we play through our own element can carry a track. */
+  supportsSubtitles: boolean;
+}
+
+/**
+ * A wiped track is remounted at most this many times per version. A file that really is
+ * empty cannot reach storage (the upload route refuses one), so the cap only exists so a
+ * surprise can never turn into a fetch loop.
+ */
+const MAX_TRACK_REPAIRS = 3;
+
+export function useSubtitles({
+  videoId,
+  versionId,
+  videoRef,
+  supportsSubtitles,
+}: UseSubtitlesParams) {
+  const [subtitles, setSubtitles] = useState<Subtitle[]>([]);
+  const [canManageSubtitles, setCanManageSubtitles] = useState(false);
+  const [activeLanguage, setActiveLanguage] = useState<string | null>(null);
+  const [isUploadingSubtitle, setIsUploadingSubtitle] = useState(false);
+
+  // Bumped to remount the <track> elements when something empties them. See the effect
+  // below for what does that and why remounting is the fix.
+  const [trackEpoch, setTrackEpoch] = useState(0);
+
+  // The stored preference is applied once per version, not on every list refresh: turning
+  // subtitles off and then deleting an unrelated track must not switch them back on.
+  const appliedPreferenceForVersionRef = useRef<string | null>(null);
+  const loadedLanguagesRef = useRef<Set<string>>(new Set());
+  const repairCountRef = useRef(0);
+
+  useEffect(() => {
+    loadedLanguagesRef.current.clear();
+    repairCountRef.current = 0;
+  }, [versionId]);
+
+  const refresh = useCallback(async () => {
+    if (!versionId || !supportsSubtitles) {
+      setSubtitles([]);
+      setCanManageSubtitles(false);
+      return;
+    }
+
+    try {
+      const res = await fetch(
+        `/api/videos/${videoId}/subtitles?versionId=${encodeURIComponent(versionId)}`,
+        { cache: 'no-store' }
+      );
+      if (!res.ok) return;
+      const payload = await res.json();
+      const list: Subtitle[] = Array.isArray(payload?.data?.subtitles)
+        ? payload.data.subtitles
+        : [];
+      setSubtitles(list);
+      setCanManageSubtitles(Boolean(payload?.data?.canManageSubtitles));
+    } catch {
+      // A failed list leaves the player without tracks, which is the same as having none.
+    }
+  }, [supportsSubtitles, versionId, videoId]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  useEffect(() => {
+    if (!versionId) return;
+    if (appliedPreferenceForVersionRef.current === versionId) return;
+    if (subtitles.length === 0) return;
+
+    appliedPreferenceForVersionRef.current = versionId;
+    const stored = readStoredSubtitleLanguage(videoId);
+    if (stored && subtitles.some((subtitle) => subtitle.language === stored)) {
+      setActiveLanguage(stored);
+    }
+  }, [subtitles, versionId, videoId]);
+
+  // A track that is no longer in the list cannot stay selected.
+  useEffect(() => {
+    if (!activeLanguage) return;
+    if (subtitles.some((subtitle) => subtitle.language === activeLanguage)) return;
+    setActiveLanguage(null);
+  }, [activeLanguage, subtitles]);
+
+  /**
+   * React renders the <track> elements; their display mode is set here rather than through
+   * the `default` attribute, which the browser only honours on first load and which would
+   * fight the user's choice on every re-render.
+   *
+   * The second job here is repair. hls.js empties every text track on the media element,
+   * ours included, each time it loads a manifest (`_cleanTracks()` in its timeline
+   * controller). That fires on the initial load and again on every source switch, so a
+   * viewer who flips quality would watch the subtitles vanish for good: the file has
+   * already been fetched, so the browser never parses it a second time. Remounting the
+   * track element under a new key is what makes it fetch again.
+   */
+  useEffect(() => {
+    const videoEl = videoRef.current;
+    if (!videoEl) return;
+
+    const findActiveTrack = (): TextTrack | null => {
+      if (!activeLanguage) return null;
+      const tracks = videoEl.textTracks;
+      for (let index = 0; index < tracks.length; index += 1) {
+        if (tracks[index].language === activeLanguage) return tracks[index];
+      }
+      return null;
+    };
+
+    const applyModes = () => {
+      const tracks = videoEl.textTracks;
+      for (let index = 0; index < tracks.length; index += 1) {
+        const track = tracks[index];
+        const shouldShow = Boolean(activeLanguage) && track.language === activeLanguage;
+        track.mode = shouldShow ? 'showing' : 'disabled';
+        if (!shouldShow) continue;
+
+        // The control bar sits over the bottom of the frame in fullscreen, so cues are
+        // lifted clear of it instead of landing underneath.
+        const cues = track.cues;
+        if (!cues) continue;
+        for (let cueIndex = 0; cueIndex < cues.length; cueIndex += 1) {
+          const cue = cues[cueIndex] as VTTCue;
+          if (typeof cue.line !== 'undefined') {
+            cue.snapToLines = true;
+            cue.line = -3;
+          }
+        }
+      }
+    };
+
+    const markLoaded = (event: Event) => {
+      const element = event.currentTarget as HTMLTrackElement;
+      loadedLanguagesRef.current.add(element.srclang);
+      applyModes();
+    };
+
+    const repairIfEmptied = () => {
+      if (!activeLanguage) return;
+      // Before the file has loaded a track legitimately has no cues, so only a track we
+      // have seen load and that is now empty counts as wiped.
+      if (!loadedLanguagesRef.current.has(activeLanguage)) return;
+      const track = findActiveTrack();
+      if (!track || (track.cues?.length ?? 0) > 0) return;
+      if (repairCountRef.current >= MAX_TRACK_REPAIRS) return;
+
+      repairCountRef.current += 1;
+      loadedLanguagesRef.current.delete(activeLanguage);
+      setTrackEpoch((epoch) => epoch + 1);
+    };
+
+    applyModes();
+
+    // A track's cues are null until the browser has fetched the file, which it only does
+    // once the track is not disabled. The lift above therefore has to run again on load.
+    const trackElements = Array.from(videoEl.querySelectorAll('track'));
+    trackElements.forEach((element) => element.addEventListener('load', markLoaded));
+    videoEl.textTracks.addEventListener('addtrack', applyModes);
+    // `loadeddata` catches a source switch while paused; `timeupdate` catches everything
+    // else within a quarter of a second of playback.
+    videoEl.addEventListener('loadeddata', repairIfEmptied);
+    videoEl.addEventListener('timeupdate', repairIfEmptied);
+
+    return () => {
+      trackElements.forEach((element) => element.removeEventListener('load', markLoaded));
+      videoEl.textTracks.removeEventListener('addtrack', applyModes);
+      videoEl.removeEventListener('loadeddata', repairIfEmptied);
+      videoEl.removeEventListener('timeupdate', repairIfEmptied);
+    };
+  }, [activeLanguage, subtitles, trackEpoch, videoRef, versionId]);
+
+  const selectSubtitleLanguage = useCallback(
+    (language: string | null) => {
+      setActiveLanguage(language);
+      writeStoredSubtitleLanguage(videoId, language);
+      appliedPreferenceForVersionRef.current = versionId;
+    },
+    [versionId, videoId]
+  );
+
+  const uploadSubtitle = useCallback(
+    async (file: File, language: string, label: string): Promise<string | null> => {
+      if (!versionId) return 'No version selected';
+
+      setIsUploadingSubtitle(true);
+      try {
+        const formData = new FormData();
+        formData.append('subtitle', file);
+        formData.append('versionId', versionId);
+        formData.append('language', language);
+        formData.append('label', label);
+
+        const res = await fetch(`/api/videos/${videoId}/subtitles`, {
+          method: 'POST',
+          body: formData,
+        });
+        const payload = await res.json().catch(() => null);
+        if (!res.ok) {
+          return payload?.error?.message || payload?.error || 'Failed to upload subtitle';
+        }
+
+        await refresh();
+        selectSubtitleLanguage(language.toLowerCase());
+        return null;
+      } catch {
+        return 'Failed to upload subtitle';
+      } finally {
+        setIsUploadingSubtitle(false);
+      }
+    },
+    [refresh, selectSubtitleLanguage, versionId, videoId]
+  );
+
+  const deleteSubtitle = useCallback(
+    async (subtitleId: string): Promise<string | null> => {
+      try {
+        const res = await fetch(`/api/videos/${videoId}/subtitles/${subtitleId}`, {
+          method: 'DELETE',
+        });
+        if (!res.ok) {
+          const payload = await res.json().catch(() => null);
+          return payload?.error?.message || payload?.error || 'Failed to delete subtitle';
+        }
+        await refresh();
+        return null;
+      } catch {
+        return 'Failed to delete subtitle';
+      }
+    },
+    [refresh, videoId]
+  );
+
+  return useMemo(
+    () => ({
+      subtitles,
+      canManageSubtitles,
+      activeSubtitleLanguage: activeLanguage,
+      subtitleTrackKey: String(trackEpoch),
+      selectSubtitleLanguage,
+      uploadSubtitle,
+      deleteSubtitle,
+      isUploadingSubtitle,
+      refreshSubtitles: refresh,
+    }),
+    [
+      activeLanguage,
+      canManageSubtitles,
+      deleteSubtitle,
+      isUploadingSubtitle,
+      refresh,
+      selectSubtitleLanguage,
+      subtitles,
+      trackEpoch,
+      uploadSubtitle,
+    ]
+  );
+}

components/video-page/hooks/use-video-player.ts

@@ -81,6 +81,10 @@ export function useVideoPlayer({
 }: UseVideoPlayerParams) {
   const [isApiLoaded, setIsApiLoaded] = useState(false);
   const [isReady, setIsReady] = useState(false);
+  // Bumped every time the YouTube player loads or unloads a module. It is the only
+  // signal that `getOption('captions', ...)` will answer, so the captions hook waits
+  // on it rather than polling.
+  const [youtubeModuleRevision, setYoutubeModuleRevision] = useState(0);
   const [bunnyPlaybackState, setBunnyPlaybackState] = useState<BunnyPlaybackState>('none');
   const [currentTime, setCurrentTime] = useState(0);
   const [videoDuration, setVideoDuration] = useState(0);
@@ -315,6 +319,9 @@ export function useVideoPlayer({
               const dur = event.target.getDuration();
               if (dur > 0) setVideoDuration(dur);
             },
+            onApiChange: () => {
+              setYoutubeModuleRevision((revision) => revision + 1);
+            },
             onStateChange: (event: YT.OnStateChangeEvent) => {
               setIsPlaying(event.data === YT.PlayerState.PLAYING);
 
@@ -1344,6 +1351,7 @@ export function useVideoPlayer({
 
   return {
     isReady,
+    youtubeModuleRevision,
     bunnyPlaybackState,
     currentTime,
     setCurrentTime,

components/video-page/hooks/use-youtube-captions.ts

@@ -0,0 +1,177 @@
+'use client';
+// Same exemption as the players themselves: this hook mirrors an external player's
+// caption state into React, which is the case the rule cannot distinguish.
+/* eslint-disable react-hooks/set-state-in-effect */
+
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from 'react';
+import {
+  readStoredSubtitleLanguage,
+  writeStoredSubtitleLanguage,
+} from '@/components/video-page/hooks/subtitle-preference';
+import type { PlayerAdapter, SubtitleTrackOption } from '@/components/video-page/types';
+
+interface UseYoutubeCaptionsParams {
+  videoId: string;
+  versionId: string | null;
+  playerRef: RefObject<YT.Player | PlayerAdapter | null>;
+  /** The active version is a YouTube one. */
+  enabled: boolean;
+  isReady: boolean;
+  /** Incremented by the player on every onApiChange. */
+  moduleRevision: number;
+}
+
+/** One entry of `getOption('captions', 'tracklist')`. Only these fields are relied on. */
+type YoutubeCaptionTrack = {
+  languageCode?: string;
+  languageName?: string;
+  displayName?: string;
+};
+
+const CAPTIONS_MODULE = 'captions';
+
+function asYoutubePlayer(
+  player: YT.Player | PlayerAdapter | null
+): (YT.Player & { loadModule?: unknown }) | null {
+  if (!player) return null;
+  const candidate = player as YT.Player;
+  return typeof candidate.loadModule === 'function' ? candidate : null;
+}
+
+/**
+ * Drives YouTube's own captions from our control bar.
+ *
+ * A YouTube version plays inside an iframe we do not own, so a <track> element is not an
+ * option and neither is an uploaded file: the only captions that exist for it are the ones
+ * the video already carries. The player is embedded with controls=0, which hides
+ * YouTube's CC button along with the rest of its chrome, so without this the captions
+ * would be unreachable even when they exist.
+ */
+export function useYoutubeCaptions({
+  videoId,
+  versionId,
+  playerRef,
+  enabled,
+  isReady,
+  moduleRevision,
+}: UseYoutubeCaptionsParams) {
+  const [tracks, setTracks] = useState<SubtitleTrackOption[]>([]);
+  const [activeLanguage, setActiveLanguage] = useState<string | null>(null);
+
+  // Read inside effects that must not re-run when the selection changes.
+  const activeLanguageRef = useRef<string | null>(null);
+  useEffect(() => {
+    activeLanguageRef.current = activeLanguage;
+  }, [activeLanguage]);
+  const appliedPreferenceForVersionRef = useRef<string | null>(null);
+  /**
+   * The caption state we last pushed into the player, or `undefined` before the first
+   * push. Loading and unloading a module both fire onApiChange, so an effect that reacted
+   * to every revision by unloading again would answer its own event forever.
+   */
+  const appliedLanguageRef = useRef<string | null | undefined>(undefined);
+
+  useEffect(() => {
+    setTracks([]);
+    setActiveLanguage(null);
+    appliedLanguageRef.current = undefined;
+  }, [versionId]);
+
+  // Loading the module is what makes the track list readable, and it also switches
+  // captions on. The probe below turns them straight back off for a viewer who has not
+  // asked for them: at this point the video is at its first frame with no cue to draw,
+  // so there is nothing to flash.
+  useEffect(() => {
+    if (!enabled || !isReady) return;
+    const player = asYoutubePlayer(playerRef.current);
+    if (!player) return;
+    try {
+      player.loadModule(CAPTIONS_MODULE);
+    } catch {
+      // An older or restricted player without the module API simply has no captions.
+    }
+  }, [enabled, isReady, playerRef, versionId]);
+
+  useEffect(() => {
+    if (!enabled || !isReady || moduleRevision === 0) return;
+    const player = asYoutubePlayer(playerRef.current);
+    if (!player) return;
+
+    let rawTracks: YoutubeCaptionTrack[] = [];
+    try {
+      rawTracks = player.getOption<YoutubeCaptionTrack[]>(CAPTIONS_MODULE, 'tracklist') ?? [];
+    } catch {
+      rawTracks = [];
+    }
+
+    const mapped: SubtitleTrackOption[] = rawTracks
+      .filter((track): track is YoutubeCaptionTrack & { languageCode: string } =>
+        Boolean(track?.languageCode)
+      )
+      .map((track) => ({
+        id: `youtube:${track.languageCode}`,
+        language: track.languageCode.toLowerCase(),
+        label: track.displayName || track.languageName || track.languageCode.toUpperCase(),
+        canDelete: false,
+      }));
+
+    setTracks(mapped);
+
+    const stored =
+      versionId && appliedPreferenceForVersionRef.current !== versionId
+        ? readStoredSubtitleLanguage(videoId)
+        : null;
+    if (versionId) appliedPreferenceForVersionRef.current = versionId;
+
+    const wanted =
+      activeLanguageRef.current ??
+      (stored && mapped.some((track) => track.language === stored) ? stored : null);
+
+    if (appliedLanguageRef.current === wanted) return;
+    appliedLanguageRef.current = wanted;
+
+    try {
+      if (wanted) {
+        player.setOption(CAPTIONS_MODULE, 'track', { languageCode: wanted });
+        setActiveLanguage(wanted);
+      } else {
+        player.unloadModule(CAPTIONS_MODULE);
+      }
+    } catch {
+      // Same as above: a player that will not take the option has no captions to give.
+    }
+  }, [enabled, isReady, moduleRevision, playerRef, versionId, videoId]);
+
+  const selectCaptionLanguage = useCallback(
+    (language: string | null) => {
+      setActiveLanguage(language);
+      writeStoredSubtitleLanguage(videoId, language);
+      appliedPreferenceForVersionRef.current = versionId;
+      appliedLanguageRef.current = language;
+
+      const player = asYoutubePlayer(playerRef.current);
+      if (!player) return;
+      try {
+        if (language) {
+          player.loadModule(CAPTIONS_MODULE);
+          player.setOption(CAPTIONS_MODULE, 'track', { languageCode: language });
+        } else {
+          player.unloadModule(CAPTIONS_MODULE);
+        }
+      } catch {
+        // Nothing to recover: the menu already reflects the choice, and a player that
+        // refuses the module was never going to show captions.
+      }
+    },
+    [playerRef, versionId, videoId]
+  );
+
+  return useMemo(
+    () => ({
+      youtubeCaptionTracks: enabled ? tracks : [],
+      activeYoutubeCaptionLanguage: enabled ? activeLanguage : null,
+      selectYoutubeCaptionLanguage: selectCaptionLanguage,
+    }),
+    [activeLanguage, enabled, selectCaptionLanguage, tracks]
+  );
+}