DEV Community

TranscriptFetch
TranscriptFetch

Posted on

The youtube-transcript npm package gave me Arabic for an English video: 4 traps

The youtube-transcript npm package is the usual way to pull YouTube captions in Node, and it sits under several n8n community nodes too. I ran version 1.3.1 on Node 24 against a handful of real videos on 2026-11-12, from a home connection. It works, but four things surprised me. All four are easy to fix once you know them.

1. With no language set, you get the first track, not English

import { YoutubeTranscript } from 'youtube-transcript';

const segments = await YoutubeTranscript.fetchTranscript('aircAruvnKk');
console.log(segments[0]);
// { text: 'هذه صورة للرقم ثلاثة.', duration: 1180, offset: 4220, lang: 'ar' }
Enter fullscreen mode Exit fullscreen mode

That is a 3Blue1Brown video, spoken in English. The package takes the first caption track YouTube lists, and for this video the first track is Arabic.

Video Spoken Returned with no language
3Blue1Brown, neural networks (aircAruvnKk) English Arabic, 216 segments
Steve Jobs at Stanford (UF8uR6Z6KLc) English Arabic, 161 segments
Rick Astley (dQw4w9WgXcQ) English English
Me at the zoo (jNQXAC9IVRw) English English

The fix is one option:

const segments = await YoutubeTranscript.fetchTranscript('aircAruvnKk', { lang: 'en' });
// 286 segments, lang: 'en'
Enter fullscreen mode Exit fullscreen mode

If you feed transcripts to an LLM without checking lang, this one can go unnoticed for a long time.

2. The language code has to match exactly

There is no fallback from a region code to a base code, or the other way round. On the Rick Astley video:

  • en works.
  • en-US throws No transcripts are available in en-US this video (dQw4w9WgXcQ). Available languages: en, en, de-DE, ja, pt-BR, es-419
  • de throws the same error, although de-DE is right there in the list.

The error prints the codes the video has, so catch YoutubeTranscriptNotAvailableLanguageError and pick from that list. A small helper that tries en, then anything starting with en, saves a lot of failed runs.

3. "Transcript is disabled" does not always mean that

The package throws [YoutubeTranscript] 🚨 Transcript is disabled on this video whenever YouTube's answer has no caption tracks. I got that exact message for:

  • a live stream (jfKfPfyJRdk)
  • a video ID that does not exist (xxxxxxxxxxx)

Neither is a video whose owner turned captions off. So do not show that message to your users as a fact about the video. Check that the ID exists first, and treat the error as "no caption tracks came back".

4. Version 1.2.1 fails on everything

On 1.2.1, 3 of 3 videos failed with TypeError: Cannot read properties of undefined (reading 'slice'). On 1.3.1 the same three returned. If a dependency of yours pins ^1.2.1 and your lockfile is old, you may still be on the broken one. npm ls youtube-transcript tells you.

Two smaller notes

  • offset and duration are in milliseconds on 1.3.1.
  • Segment text keeps the caption file's line breaks, so replace \n before you join segments into a paragraph.

What I could not test

I ran this from a home connection, so YouTube never blocked me. I cannot tell you what the package returns from a blocked cloud address, only that the source has a YoutubeTranscriptTooManyRequestError for the captcha page.

If you use this package inside n8n, the Code node adds its own error (Module 'youtube-transcript' is disallowed). I wrote that part up, with the n8n Cloud limits, on the TranscriptFetch blog. TranscriptFetch is a hosted transcript API, so that page ends with our own option.

If you have hit a failure in this package that is not on the list, I would like to hear it in the comments.

Top comments (0)