feat: enhance chapter marker functionality with translation support and improve chapter loading logic & subtitle feedbacks addressed

Author: aman-imagekit

packages/video-player/javascript/index.ts

@@ -91,7 +91,7 @@ class ImageKitVideoPlayerPlugin extends Plugin {
         }
 
         initPromises.push(
-          initChapterMarkers(this.player, this.currentSource_, this.ikGlobalSettings_, this.ikGlobalSettings_.signerFn)
+          initChapterMarkers(this.player, this.currentSource_, this.ikGlobalSettings_)
         );
 
         initPromises.push(this.initRecommendationsOverlay());

packages/video-player/javascript/interfaces/TextTrack.ts

@@ -25,10 +25,10 @@ export interface TextTrackOptions {
    */
   default?: boolean;
   /**
-   * Maximum number of words per subtitle line (only for transcript files)
-   * @default 4
+   * Maximum number of characters that can appear on a subtitle frame (only for transcript files)
+   * @default 60
    */
-  maxWordsPerLine?: number;
+  maxChars?: number;
   /**
    * Enable word-level highlighting in subtitles (only for transcript files)
    * When enabled, words are highlighted as they are spoken
@@ -306,10 +306,10 @@ export interface AutoGeneratedTextTrackOptions {
    */
   showAutoGenerated?: boolean;
   /**
-   * Maximum number of words per subtitle line
-   * @default 4
+   * Maximum number of characters that can appear on a subtitle frame
+   * @default 60
    */
-  maxWordsPerLine?: number;
+  maxChars?: number;
   /**
    * Enable word-level highlighting in subtitles
    * When enabled, words are highlighted as they are spoken

packages/video-player/javascript/modules/chapters/chapters.ts

@@ -3,6 +3,15 @@ import type { SourceOptions, IKPlayerOptions } from '../../interfaces';
 import { ChapterMarker, parseChaptersFromVTT } from './chapterMarkerProgressBar';
 import { prepareChaptersVttSrc } from '../../utils';
 
+interface ChapterTrackMetadata {
+  langCode: string;
+  chapterList: ChapterMarker[];
+  vttUrl: string;
+}
+
+// Map to store chapter tracks by language
+const chapterTracksCache = new Map<string, ChapterTrackMetadata>();
+
 /**
  * Clean up existing chapter text tracks from the player.
  */
@@ -37,6 +46,147 @@ function cleanupChapterLabelDisplay(player: Player): void {
   }
 }
 
+/**
+ * Clean up all chapter-related components from the player.
+ * Removes chapter text tracks, label display, and progress bar control.
+ */
+function cleanupChapters(player: Player): void {
+  cleanupChapterTextTracks(player);
+  cleanupChapterLabelDisplay(player);
+  const existing = player.getChild('ChapterMarkersProgressBarControl');
+  if (existing) {
+    existing.dispose();
+  }
+}
+
+
+/**
+ * Load chapters for a specific language
+ */
+async function loadChaptersForLanguage(
+  player: Player,
+  vttUrl: string,
+  langCode: string = 'en'
+): Promise<ChapterMarker[]> {
+  // Check cache first
+  if (chapterTracksCache.has(langCode)) {
+    return chapterTracksCache.get(langCode)!.chapterList;
+  }
+
+  try {
+    const res = await fetch(vttUrl);
+    if (!res.ok) {
+      player.log.warn(`Chapter VTT fetch failed for ${langCode} with status: (${res.status})`);
+      return [];
+    }
+    const data = await res.text();
+    const chapterList = parseChaptersFromVTT(data);
+
+    // Cache the chapters
+    chapterTracksCache.set(langCode, { langCode, chapterList, vttUrl });
+
+    return chapterList;
+  } catch (e) {
+    player.log.error(`Failed to fetch chapters for ${langCode}: ${e}`);
+    return [];
+  }
+}
+
+/**
+ * Switch chapters to match the active subtitle language
+ */
+async function switchChaptersLanguage(
+  player: Player,
+  langCode: string
+): Promise<void> {
+  const metadata = chapterTracksCache.get(langCode);
+  
+  if (!metadata) {
+    player.log.warn(`No chapter track found for language: ${langCode}`);
+    return;
+  }
+
+  // Clean up existing chapters
+  cleanupChapters(player);
+
+  // Apply new chapters
+  applyChaptersToPlayer(player, metadata.chapterList);
+}
+
+/**
+ * Apply chapter list to player (extracted for reuse)
+ */
+function applyChaptersToPlayer(player: Player, chapterList: ChapterMarker[]): void {
+  if (chapterList.length === 0) return;
+
+  try {
+    const trackEl = player.addRemoteTextTrack(
+      {
+        kind: 'chapters',
+        default: true,
+      },
+      false
+    ) as unknown as HTMLTrackElement;
+
+    chapterList.forEach((chapter) => {
+      const cue = new VTTCue(chapter.startTime, chapter.endTime, chapter.label);
+      trackEl.track.addCue(cue);
+    });
+
+    setupChapterLabelDisplay(player, trackEl.track);
+
+    // Update the chapters button
+    const controlBar = player.getChild('ControlBar');
+    if (controlBar) {
+      const chaptersButton = controlBar.getChild('ChaptersButton');
+      if (chaptersButton && typeof (chaptersButton as any).update === 'function') {
+        (chaptersButton as any).update();
+      }
+    }
+  } catch (e) {
+    player.log.warn(`Failed to create chapter text track: ${e}`);
+  }
+
+  const existing = player.getChild('ChapterMarkersProgressBarControl');
+  if (existing) {
+    existing.dispose();
+  }
+  player.addChild('ChapterMarkersProgressBarControl', { chapters: chapterList });
+}
+
+/**
+ * Setup listener for subtitle track changes to switch chapters accordingly
+ */
+function setupSubtitleChapterSync(player: Player): void {
+  const textTracks = player.textTracks();
+  
+  textTracks.addEventListener('change', () => {
+    let foundActiveTrack = false;
+    
+    // Check for active subtitle track
+    for (let i = 0; i < textTracks.length; i++) {
+      const track = textTracks[i];
+      
+      // Find the active subtitle track
+      if ((track.kind === 'subtitles' || track.kind === 'captions') && track.mode === 'showing') {
+        const langCode = track.language || 'en';
+        
+        // Switch chapters to match this language
+        if (chapterTracksCache.has(langCode)) {
+          switchChaptersLanguage(player, langCode);
+          foundActiveTrack = true;
+        }
+        break;
+      }
+    }
+    
+    // If no subtitle track is active (user turned off captions), revert to base chapters
+    if (!foundActiveTrack && chapterTracksCache.has('base')) {
+      switchChaptersLanguage(player, 'base');
+    }
+  });
+}
+
 /**
  * Setup chapter label display in the control bar.
  * Displays the current chapter name and updates on cuechange events.
@@ -76,23 +226,20 @@ function setupChapterLabelDisplay(player: Player, chaptersTrack: TextTrack): voi
 /**
  * Initialize chapter markers for the video player.
  * Supports three methods:
- * 1. Auto-generate: chapters: true
+ * 1. Auto-generate: chapters: true (with optional translations)
  * 2. VTT URL: chapters: { url: string }
  * 3. Manual object: chapters: { [timeInSec]: title }
  */
 export async function initChapterMarkers(
   player: Player,
   source: SourceOptions | SourceOptions[] | null,
-  ikGlobalSettings: IKPlayerOptions,
-  signerFn?: (src: string) => Promise<string>
+  ikGlobalSettings: IKPlayerOptions
 ): Promise<void> {
 
-  cleanupChapterTextTracks(player);
-  cleanupChapterLabelDisplay(player);
-  const existing = player.getChild('ChapterMarkersProgressBarControl');
-  if (existing) {
-    existing.dispose();
-  }
+  cleanupChapters(player);
+
+  // Clear cache for new source
+  chapterTracksCache.clear();
 
   if (!source) return;
 
@@ -102,12 +249,13 @@ export async function initChapterMarkers(
   let chapterList: ChapterMarker[] = [];
 
   if (typeof src.chapters === 'object' && 'url' in src.chapters) {
+    // Manual VTT URL - load directly
     try {
       let vttUrl = src.chapters.url;
 
-      if (signerFn) {
+      if (ikGlobalSettings.signerFn) {
         try {
-          vttUrl = await signerFn(vttUrl);
+          vttUrl = await ikGlobalSettings.signerFn(vttUrl);
         } catch (err) {
           player.log.error(`Failed to sign chapter VTT URL: ${err instanceof Error ? err.message : String(err)}`);
           return;
@@ -122,18 +270,19 @@ export async function initChapterMarkers(
       const data = await res.text();
       chapterList = parseChaptersFromVTT(data);
     } catch (e) {
-      player.log.error(`Failed to fetch chapters VTT: ${e}`);
+      player.log.error(`Failed to fetch chapters VTT: ${e instanceof Error ? e.message : String(e)}`);
       return;
     }
   } else if (typeof src.chapters === 'object') {
+    // Manual chapter object - convert to ChapterMarker[]
     const entries = Object.entries(src.chapters)
       .map(([time, label]) => ({ startTime: Number(time), label: String(label) }))
       .sort((a, b) => a.startTime - b.startTime);
 
     const duration = player.duration() || 0;
 
     chapterList = entries.map((entry, index) => {
-        const endTime =
+      const endTime =
         index < entries.length - 1
           ? entries[index + 1].startTime
           : duration || entry.startTime + 10;
@@ -144,55 +293,33 @@ export async function initChapterMarkers(
       };
     });
   } else if (src.chapters === true) {
+    // Auto-generate chapters with translations support
     try {
-      const chaptersVttSrc = await prepareChaptersVttSrc(src, ikGlobalSettings);
-      const res = await fetch(chaptersVttSrc);
-      if (!res.ok) {
-        player.log.warn(`Default VTT fetch failed with status: (${res.status}); skipping chapters.`);
-        return;
+      const { baseUrl, translatedUrls } = await prepareChaptersVttSrc(src, ikGlobalSettings);
+      
+      // Load base language chapters
+      chapterList = await loadChaptersForLanguage(player, baseUrl, 'base');
+
+      // Pre-load translated chapters in background
+      if (translatedUrls.size > 0) {
+        for (const [langCode, url] of translatedUrls.entries()) {
+          // Load in background without blocking
+          loadChaptersForLanguage(player, url, langCode).catch(err => {
+            player.log.warn(`Failed to pre-load chapters for ${langCode}:`, err);
+          });
+        }
+
+        // Setup subtitle-chapter synchronization
+        setupSubtitleChapterSync(player);
       }
-      const data = await res.text();
-      chapterList = parseChaptersFromVTT(data);
     } catch (e) {
       player.log.error(`Failed to fetch default chapters VTT: ${e}`);
       return;
     }
   }
 
-  if (chapterList.length) {
-
-    try {
-      const trackEl = player.addRemoteTextTrack(
-        {
-          kind: 'chapters',
-          default: true,
-        },
-        false
-      ) as unknown as HTMLTrackElement;
-
-      chapterList.forEach((chapter) => {
-        const cue = new VTTCue(chapter.startTime, chapter.endTime, chapter.label);
-        trackEl.track.addCue(cue);
-      });
-
-      setupChapterLabelDisplay(player, trackEl.track);
-
-      const controlBar = player.getChild('ControlBar');
-      if (controlBar) {
-        const chaptersButton = controlBar.getChild('ChaptersButton');
-        if (chaptersButton && typeof (chaptersButton as any).update === 'function') {
-          (chaptersButton as any).update();
-        }
-      }
-    } catch (e) {
-      player.log.warn(`Failed to create chapter text track: ${e}`);
-    }
-
-    const existing = player.getChild('ChapterMarkersProgressBarControl');
-    if (existing) {
-      console.log('Disposing existing chapter markers progress bar control');
-      existing.dispose();
-    }
-    player.addChild('ChapterMarkersProgressBarControl', { chapters: chapterList });
+  // Apply the base/default chapters
+  if (chapterList.length > 0) {
+    applyChaptersToPlayer(player, chapterList);
   }
 }