From 6063a3d2dab070229ce3ff3dbb4f235eeb64ad5b Mon Sep 17 00:00:00 2001
From: Ahtesham Quraish <ahtesham-quraish@users.noreply.github.com>
Date: Wed, 6 May 2026 17:33:21 +0500
Subject: [PATCH 1/2] fix: add video captions on the video detail page (#3284)

* fix: add captions of video



---------


Co-authored-by: Ahtesham Quraish <ahtesham.quraish@192.168.1.22>
---
 .../VideoDetailPage.tsx                       |  18 ++-
 .../VideoJsPlayer.tsx                         |  63 ++++++++-
 .../VideoSeriesDetailPage.test.tsx            | 132 +++++++++++++++++-
 .../VideoSeriesDetailPage.tsx                 |  21 ++-
 .../videoStructuredData.ts                    |  38 +++++
 5 files changed, 263 insertions(+), 9 deletions(-)
 create mode 100644 frontends/main/src/app-pages/VideoPlaylistCollectionPage/videoStructuredData.ts

diff --git a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoDetailPage.tsx b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoDetailPage.tsx
index f425683fb9..063a1cf9a9 100644
--- a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoDetailPage.tsx
+++ b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoDetailPage.tsx
@@ -28,6 +28,7 @@ import { FeatureFlags } from "@/common/feature_flags"
 import { useFeatureFlagsLoaded } from "@/common/useFeatureFlagsLoaded"
 import { notFound } from "next/navigation"
 import SharePopover from "@/components/SharePopover/SharePopover"
+import { buildVideoStructuredData } from "./videoStructuredData"
 
 const NEXT_PUBLIC_ORIGIN = process.env.NEXT_PUBLIC_ORIGIN
 
@@ -388,7 +389,6 @@ const VideoDetailPage: React.FC<VideoDetailPageProps> = ({
 
   const playlist = playlistData as VideoPlaylistResource | undefined
   const video = resource as VideoResource | undefined
-
   const sources = useMemo(
     () =>
       video
@@ -406,6 +406,7 @@ const VideoDetailPage: React.FC<VideoDetailPageProps> = ({
     : null
 
   const topics = video?.topics ?? []
+  const captionUrls = video?.video?.caption_urls ?? []
 
   const playlistLabel = playlist?.title || "Video Collection"
 
@@ -442,12 +443,26 @@ const VideoDetailPage: React.FC<VideoDetailPageProps> = ({
     }
   }, [isLoading, videoId])
 
+  // VideoObject JSON-LD for Google search indexing.
+  // See: https://developers.google.com/search/docs/appearance/structured-data/video
+  const structuredData = !isLoading ? buildVideoStructuredData(video) : null
+
   if (!showVideoPlaylistPage) {
     return flagsLoaded ? notFound() : null
   }
 
   return (
     <PageWrapper>
+      {structuredData && (
+        <script
+          type="application/ld+json"
+          // JSON.stringify does not escape </ by default; replace prevents
+          // a malicious title/description from breaking out of the script tag.
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(structuredData).replace(/<\//g, "<\\/"),
+          }}
+        />
+      )}
       <SkipLinksNav aria-label="Skip links">
         <SkipLink href="#video-detail-main">Skip to main content</SkipLink>
         <SkipLink href="#video-player-region">Skip to video player</SkipLink>
@@ -530,6 +545,7 @@ const VideoDetailPage: React.FC<VideoDetailPageProps> = ({
               <VideoJsPlayer
                 key={videoId}
                 sources={sources}
+                tracks={captionUrls}
                 poster={
                   sources[0]?.type === "video/youtube"
                     ? undefined
diff --git a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoJsPlayer.tsx b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoJsPlayer.tsx
index d2f0941bf8..40570c1729 100644
--- a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoJsPlayer.tsx
+++ b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoJsPlayer.tsx
@@ -6,6 +6,7 @@ import Player from "video.js/dist/types/player"
 import "video.js/dist/video-js.css"
 // Register YouTube tech so video.js can play youtube:// sources
 import "videojs-youtube"
+import type { CaptionUrl } from "api/v1"
 
 export type VideoJsSource = {
   src: string
@@ -14,6 +15,7 @@ export type VideoJsSource = {
 
 export type VideoJsPlayerProps = {
   sources: VideoJsSource[]
+  tracks?: CaptionUrl[]
   poster?: string | null
   autoplay?: boolean
   controls?: boolean
@@ -29,6 +31,7 @@ export type VideoJsPlayerProps = {
  */
 const VideoJsPlayer: React.FC<VideoJsPlayerProps> = ({
   sources,
+  tracks = [],
   poster,
   autoplay = true,
   controls = true,
@@ -39,6 +42,35 @@ const VideoJsPlayer: React.FC<VideoJsPlayerProps> = ({
 }) => {
   const videoRef = useRef<HTMLDivElement>(null)
   const playerRef = useRef<Player | null>(null)
+  // Prevent the update effect from running on the very first mount —
+  // the init effect already handles the initial sources/tracks setup.
+  const isMountedRef = useRef(false)
+
+  const addTracks = (player: Player, trackList: CaptionUrl[]) => {
+    // Remove any existing remote text tracks first.
+    // Snapshot into a plain array before mutating (TextTrackList is live).
+    // video.js's TextTrackList TS type lacks a numeric index signature, so
+    // cast via unknown to a Record — safer than `any` and no eslint-disable needed.
+    type TrackArg = Parameters<typeof player.removeRemoteTextTrack>[0]
+    const existing = player.remoteTextTracks()
+    const snapshot = Array.from(
+      { length: existing.length },
+      (_, i) => (existing as unknown as Record<number, TrackArg>)[i],
+    )
+    snapshot.forEach((t) => player.removeRemoteTextTrack(t))
+    trackList.forEach((track, index) => {
+      player.addRemoteTextTrack(
+        {
+          kind: "captions",
+          src: track.url,
+          srclang: track.language,
+          label: track.language_name || track.language,
+          default: index === 0,
+        },
+        false,
+      )
+    })
+  }
 
   useEffect(() => {
     // Only initialise once
@@ -67,9 +99,18 @@ const VideoJsPlayer: React.FC<VideoJsPlayerProps> = ({
         poster: poster ?? undefined,
         sources,
         techOrder: ["youtube", "html5"],
+        // Always set crossOrigin so the browser can fetch VTT files from
+        // a different origin (e.g. CloudFront CDN) without CORS errors.
+        crossOrigin: "anonymous",
       },
       function (this: Player) {
+        // Add tracks inside the ready callback — this is the earliest safe
+        // point; adding them before ready can silently fail on some browsers.
+        addTracks(this, tracks)
         onReady?.(this)
+        // Set the flag here so the update effect only runs after the player
+        // is truly ready and the initial setup is complete.
+        isMountedRef.current = true
       },
     )
 
@@ -83,16 +124,30 @@ const VideoJsPlayer: React.FC<VideoJsPlayerProps> = ({
     onReady,
     poster,
     sources,
+    tracks,
   ])
 
-  // Update sources / poster when props change without re-creating the player
+  // Update sources / poster when they change without re-creating the player.
+  // Kept separate from the tracks effect so a captions-only change does not
+  // call player.src() and unexpectedly reload / interrupt playback.
   useEffect(() => {
     const player = playerRef.current
-    if (!player) return
-    player.src(sources)
-    player.poster(poster ?? "")
+    if (!player || !isMountedRef.current) return
+    player.ready(() => {
+      player.src(sources)
+      player.poster(poster ?? "")
+    })
   }, [sources, poster])
 
+  // Update tracks independently so caption changes never trigger a media reload.
+  useEffect(() => {
+    const player = playerRef.current
+    if (!player || !isMountedRef.current) return
+    player.ready(() => {
+      addTracks(player, tracks)
+    })
+  }, [tracks])
+
   // Dispose on unmount
   useEffect(() => {
     return () => {
diff --git a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.test.tsx b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.test.tsx
index 031c630b67..e223ccc2c3 100644
--- a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.test.tsx
+++ b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.test.tsx
@@ -20,8 +20,15 @@ jest.mock("next-nprogress-bar", () => ({
 // Stub VideoJsPlayer to avoid loading video.js in the test environment
 jest.mock("./VideoJsPlayer", () => ({
   __esModule: true,
-  default: (props: { ariaLabel?: string }) => (
-    <div data-testid="video-js-player" aria-label={props.ariaLabel} />
+  default: (props: {
+    ariaLabel?: string
+    tracks?: { language: string; language_name: string; url: string }[]
+  }) => (
+    <div
+      data-testid="video-js-player"
+      aria-label={props.ariaLabel}
+      data-tracks={JSON.stringify(props.tracks ?? [])}
+    />
   ),
 }))
 
@@ -423,6 +430,28 @@ describe("VideoSeriesDetailPage", () => {
         "No playable source available for this video.",
       )
     })
+
+    test("passes caption_urls as tracks prop to VideoJsPlayer", async () => {
+      const captionUrls = [
+        { language: "en", language_name: "English", url: "/captions/en.vtt" },
+      ]
+      const video = makeVideo({
+        video: {
+          id: 1,
+          caption_urls: captionUrls,
+          streaming_url: "https://www.youtube.com/watch?v=abc123",
+          duration: "",
+          cover_image_url: null,
+        },
+      })
+      renderPage({ video })
+
+      const player = await screen.findByTestId("video-js-player")
+      const tracks = JSON.parse(player.getAttribute("data-tracks") ?? "[]")
+      expect(tracks).toHaveLength(1)
+      expect(tracks[0].language).toBe("en")
+      expect(tracks[0].url).toBe("/captions/en.vtt")
+    })
   })
 
   describe("loading state", () => {
@@ -475,4 +504,103 @@ describe("VideoSeriesDetailPage", () => {
       ).toHaveAttribute("href", "#video-player-region")
     })
   })
+
+  describe("JSON-LD structured data", () => {
+    test("renders an application/ld+json script tag with VideoObject data", async () => {
+      const video = makeVideo({
+        title: "Deep Learning Lecture",
+        description: "An intro to deep learning.",
+        last_modified: "2024-01-15T00:00:00Z",
+        video: {
+          id: 1,
+          caption_urls: [],
+          streaming_url: "https://www.youtube.com/watch?v=abc123",
+          duration: "PT1H30M",
+          cover_image_url: null,
+        },
+      })
+      renderPage({ video })
+
+      await screen.findByRole("heading", { name: video.title })
+
+      const script = document.querySelector(
+        "script[type='application/ld+json']",
+      )
+      expect(script).toBeInTheDocument()
+      const data = JSON.parse(script!.textContent ?? "{}")
+      expect(data["@type"]).toBe("VideoObject")
+      expect(data.name).toBe("Deep Learning Lecture")
+      expect(data.description).toBe("An intro to deep learning.")
+      expect(data.duration).toBe("PT1H30M")
+    })
+
+    test("omits duration from JSON-LD when it is not ISO-8601", async () => {
+      const video = makeVideo({
+        last_modified: "2024-01-15T00:00:00Z",
+        video: {
+          id: 1,
+          caption_urls: [],
+          streaming_url: "https://www.youtube.com/watch?v=abc123",
+          duration: "120", // plain seconds — not ISO-8601
+          cover_image_url: null,
+        },
+      })
+      renderPage({ video })
+
+      await screen.findByRole("heading", { name: video.title })
+
+      const script = document.querySelector(
+        "script[type='application/ld+json']",
+      )
+      const data = JSON.parse(script!.textContent ?? "{}")
+      expect(data.duration).toBeUndefined()
+    })
+
+    test("includes accessibilityFeature captions in JSON-LD when caption_urls is non-empty", async () => {
+      const captionUrls = [
+        { language: "en", language_name: "English", url: "/captions/en.vtt" },
+      ]
+      const video = makeVideo({
+        last_modified: "2024-01-15T00:00:00Z",
+        video: {
+          id: 1,
+          caption_urls: captionUrls,
+          streaming_url: "https://www.youtube.com/watch?v=abc123",
+          duration: "PT10M",
+          cover_image_url: null,
+        },
+      })
+      renderPage({ video })
+
+      await screen.findByRole("heading", { name: video.title })
+
+      const script = document.querySelector(
+        "script[type='application/ld+json']",
+      )
+      const data = JSON.parse(script!.textContent ?? "{}")
+      expect(data.accessibilityFeature).toContain("captions")
+    })
+
+    test("omits accessibilityFeature from JSON-LD when caption_urls is empty", async () => {
+      const video = makeVideo({
+        last_modified: "2024-01-15T00:00:00Z",
+        video: {
+          id: 1,
+          caption_urls: [],
+          streaming_url: "https://www.youtube.com/watch?v=abc123",
+          duration: "PT10M",
+          cover_image_url: null,
+        },
+      })
+      renderPage({ video })
+
+      await screen.findByRole("heading", { name: video.title })
+
+      const script = document.querySelector(
+        "script[type='application/ld+json']",
+      )
+      const data = JSON.parse(script!.textContent ?? "{}")
+      expect(data.accessibilityFeature).toBeUndefined()
+    })
+  })
 })
diff --git a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.tsx b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.tsx
index 306d09224d..d1bea0c1a1 100644
--- a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.tsx
+++ b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/VideoSeriesDetailPage.tsx
@@ -18,6 +18,7 @@ import { useSeriesNavigation } from "./useSeriesNavigation"
 import SeriesNavBar from "./SeriesNavBar"
 import UpNextSection from "./UpNextSection"
 import * as Styled from "./VideoSeriesDetailPage.styled"
+import { buildVideoStructuredData } from "./videoStructuredData"
 
 const VideoJsPlayer = dynamic<VideoJsPlayerProps>(
   () => import("./VideoJsPlayer"),
@@ -49,7 +50,6 @@ const VideoSeriesDetailPage: React.FC<VideoSeriesDetailPageProps> = ({
 
   const playlist = playlistData as VideoPlaylistResource | undefined
   const video = resource as VideoResource | undefined
-
   const {
     prevVideo,
     nextVideo,
@@ -71,11 +71,11 @@ const VideoSeriesDetailPage: React.FC<VideoSeriesDetailPageProps> = ({
         : [],
     [video],
   )
-
   const duration = video?.video?.duration
     ? formatDurationClockTime(video.video.duration)
     : null
 
+  const captionUrls = video?.video?.caption_urls ?? []
   const playlistLabel = playlist?.title || "Video Collection"
 
   const isLoading = videoLoading || (!!playlistId && playlistLoading)
@@ -94,12 +94,28 @@ const VideoSeriesDetailPage: React.FC<VideoSeriesDetailPageProps> = ({
     }
   }, [isLoading, videoId])
 
+  // VideoObject JSON-LD for Google search indexing.
+  // Rendered as a plain <script> tag so Googlebot can read it without executing
+  // any additional JS. The replace guard prevents </script> injection.
+  // See: https://developers.google.com/search/docs/appearance/structured-data/video
+  const structuredData = !isLoading ? buildVideoStructuredData(video) : null
+
   if (!showVideoPlaylistPage) {
     return flagsLoaded ? notFound() : null
   }
 
   return (
     <Styled.PageWrapper>
+      {structuredData && (
+        <script
+          type="application/ld+json"
+          // JSON.stringify does not escape </ by default; replace prevents
+          // a malicious title/description from breaking out of the script tag.
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(structuredData).replace(/<\//g, "<\\/"),
+          }}
+        />
+      )}
       <Styled.SkipLinksNav aria-label="Skip links">
         <Styled.SkipLink href="#video-detail-main">
           Skip to main content
@@ -192,6 +208,7 @@ const VideoSeriesDetailPage: React.FC<VideoSeriesDetailPageProps> = ({
               <VideoJsPlayer
                 key={videoId}
                 sources={sources}
+                tracks={captionUrls}
                 poster={
                   sources[0]?.type === "video/youtube"
                     ? undefined
diff --git a/frontends/main/src/app-pages/VideoPlaylistCollectionPage/videoStructuredData.ts b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/videoStructuredData.ts
new file mode 100644
index 0000000000..a500f5ba53
--- /dev/null
+++ b/frontends/main/src/app-pages/VideoPlaylistCollectionPage/videoStructuredData.ts
@@ -0,0 +1,38 @@
+import type { VideoResource } from "api/v1"
+
+// ISO-8601 duration pattern (e.g. "PT2M0S"). Schema.org requires this format
+// for the VideoObject `duration` property.
+const ISO_8601_DURATION_RE =
+  /^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/
+
+/**
+ * Builds a schema.org VideoObject structured-data payload for Google rich
+ * results. Returns `null` when required fields are missing (Google requires at
+ * minimum name, description, thumbnailUrl, and uploadDate).
+ *
+ * See: https://developers.google.com/search/docs/appearance/structured-data/video
+ */
+export function buildVideoStructuredData(
+  video: VideoResource | undefined,
+): Record<string, unknown> | null {
+  if (!video || !video.last_modified) return null
+
+  const captionUrls = video.video?.caption_urls ?? []
+
+  const durationIso =
+    video.video?.duration && ISO_8601_DURATION_RE.test(video.video.duration)
+      ? video.video.duration
+      : undefined
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "VideoObject",
+    name: video.title,
+    ...(video.description ? { description: video.description } : {}),
+    thumbnailUrl: video.video?.cover_image_url || video.image?.url || undefined,
+    uploadDate: video.last_modified,
+    contentUrl: video.url ?? undefined,
+    ...(durationIso ? { duration: durationIso } : {}),
+    ...(captionUrls.length > 0 ? { accessibilityFeature: ["captions"] } : {}),
+  }
+}

From 55001e1cd67112d8430fc4512702fb9f2f0bb298 Mon Sep 17 00:00:00 2001
From: Doof <mitx-devops@mit.edu>
Date: Wed, 6 May 2026 12:34:25 +0000
Subject: [PATCH 2/2] Release 0.66.7

---
 RELEASE.rst      | 5 +++++
 main/settings.py | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/RELEASE.rst b/RELEASE.rst
index e9bb08b0e8..dff5e5b850 100644
--- a/RELEASE.rst
+++ b/RELEASE.rst
@@ -1,6 +1,11 @@
 Release Notes
 =============
 
+Version 0.66.7
+--------------
+
+- fix: add video captions on the video detail page (#3284)
+
 Version 0.66.6 (Released May 06, 2026)
 --------------
 
diff --git a/main/settings.py b/main/settings.py
index 23aa82c121..a2f007ae2a 100644
--- a/main/settings.py
+++ b/main/settings.py
@@ -35,7 +35,7 @@
 from main.settings_pluggy import *  # noqa: F403
 from openapi.settings_spectacular import open_spectacular_settings
 
-VERSION = "0.66.6"
+VERSION = "0.66.7"
 
 log = logging.getLogger()