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 <track>'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) <noreply@anthropic.com>
This commit is contained in:
Roland 2026-07-16 17:43:40 -06:00 • committed by lrnselfreliance
parent 8ad912505d
commit 16c457ebcb
2 changed files with 100 additions and 0 deletions

View file

@ -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 <track kind="captions" label="German" src={src} srcLang="de" {...props}/>
} else if (src.endsWith('.es.vtt')) {

View file

@ -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');
});
});