From 16c457ebcbc7bd7d977e6618b0463c0e4d772944 Mon Sep 17 00:00:00 2001 From: Roland Date: Thu, 16 Jul 2026 17:43:40 -0600 Subject: [PATCH] videos: center YouTube auto-generated captions YouTube auto-generated captions (downloaded via yt-dlp) stamp every cue with `align:start position:0%`, which pins the caption text to the bottom-left of the player and makes it hard to read. Properly-authored VTT files have no cue settings and already render centered. Detect that auto-caption signature and reset only those cues to the browser's centered default (align:center / position:auto / line:auto). This mutates the in-memory VTTCue objects the browser parsed; the .vtt file on disk is never modified, and deliberately-positioned cues are left untouched. Wired via each 's onLoad. Non-default language tracks are `disabled` at load (no cues yet), so they are normalized lazily on the first cuechange when the user selects them. Co-Authored-By: Claude Opus 4.8 (1M context) --- app/src/components/VideoPlayer.js | 42 +++++++++++++++++++ app/src/components/VideoPlayer.test.js | 58 ++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 app/src/components/VideoPlayer.test.js diff --git a/app/src/components/VideoPlayer.js b/app/src/components/VideoPlayer.js index 644846e2..be602e7b 100644 --- a/app/src/components/VideoPlayer.js +++ b/app/src/components/VideoPlayer.js @@ -33,7 +33,49 @@ const MEDIA_PATH = '/media'; +// YouTube auto-generated captions (downloaded via yt-dlp) stamp every cue with `align:start position:0%`, +// which pins the text to the bottom-left of the player and makes it hard to read. Detect that signature and +// reset those cues to the browser's centered default. This mutates only the in-memory VTTCue objects the +// browser parsed; the .vtt file on disk is never modified. Cues that were deliberately positioned (anything +// other than the auto-caption signature) are left untouched. +export function centerAutoCaptions(track) { + if (!track || !track.cues) { + return 0; + } + let changed = 0; + for (const cue of track.cues) { + if (cue.align === 'start' && cue.position === 0) { + cue.align = 'center'; + cue.position = 'auto'; + cue.line = 'auto'; + changed++; + } + } + return changed; +} + +function handleCaptionTrackLoad(event) { + const track = event.target.track; + if (!track) { + return; + } + if (track.cues && track.cues.length > 0) { + centerAutoCaptions(track); + } else { + // A non-default track has mode 'disabled' at load time, so its cues are not parsed yet. Normalize + // them the first time the browser populates them (when the user selects the track and playback + // advances into a cue). + const onCueChange = () => { + centerAutoCaptions(track); + track.removeEventListener('cuechange', onCueChange); + }; + track.addEventListener('cuechange', onCueChange); + } +} + export function CaptionTrack({src, ...props}) { + // Center YouTube auto-generated captions once the browser parses the cues (see centerAutoCaptions). + props = {onLoad: handleCaptionTrackLoad, ...props}; if (src.endsWith('.de.vtt')) { return } else if (src.endsWith('.es.vtt')) { diff --git a/app/src/components/VideoPlayer.test.js b/app/src/components/VideoPlayer.test.js new file mode 100644 index 00000000..1aa42453 --- /dev/null +++ b/app/src/components/VideoPlayer.test.js @@ -0,0 +1,58 @@ +import {centerAutoCaptions} from './VideoPlayer'; + +// Build a fake TextTrack whose cues mimic what the browser parses from a .vtt file. +const makeTrack = (cues) => ({cues}); + +describe('centerAutoCaptions', () => { + test('re-centers YouTube auto-caption cues (align:start position:0%)', () => { + const track = makeTrack([ + {align: 'start', position: 0, line: 'auto', size: 100, text: 'hello'}, + {align: 'start', position: 0, line: 'auto', size: 100, text: 'world'}, + ]); + + const changed = centerAutoCaptions(track); + + expect(changed).toBe(2); + for (const cue of track.cues) { + expect(cue.align).toBe('center'); + expect(cue.position).toBe('auto'); + expect(cue.line).toBe('auto'); + } + }); + + test('leaves deliberately-positioned cues untouched', () => { + const track = makeTrack([ + // Already centered (no cue settings in the .vtt file). + {align: 'center', position: 'auto', line: 'auto'}, + // Deliberately placed at the top, right-aligned. + {align: 'end', position: 90, line: 0}, + ]); + + const changed = centerAutoCaptions(track); + + expect(changed).toBe(0); + expect(track.cues[0].align).toBe('center'); + expect(track.cues[1].align).toBe('end'); + expect(track.cues[1].position).toBe(90); + expect(track.cues[1].line).toBe(0); + }); + + test('handles a track with no cues yet (mode disabled)', () => { + expect(centerAutoCaptions({cues: null})).toBe(0); + expect(centerAutoCaptions(null)).toBe(0); + expect(centerAutoCaptions(undefined)).toBe(0); + }); + + test('only normalizes the auto-caption cues in a mixed track', () => { + const track = makeTrack([ + {align: 'start', position: 0, line: 'auto'}, + {align: 'end', position: 90, line: 0}, + ]); + + const changed = centerAutoCaptions(track); + + expect(changed).toBe(1); + expect(track.cues[0].align).toBe('center'); + expect(track.cues[1].align).toBe('end'); + }); +});