extract-youtube 1.0.156 → 1.0.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extract-youtube",
-  "version": "1.0.156",
+  "version": "1.0.158",
   "description": "Fast, no-browser serverless-optimized YouTube transcript extractor",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/test/article-formatter.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Unit tests for ArticleFormatter and the package barrel export.
+ */
+
+import * as pkg from '../src/index';
+import { ArticleFormatter, FormatterLoader } from '../src/formatters';
+import { FetchedTranscript } from '../src/models';
+
+function transcript(snippets: Array<{ text: string; start: number; duration?: number }>) {
+  return new FetchedTranscript(
+    snippets.map((snippet) => ({ duration: 1, ...snippet })),
+    'vid123',
+    'English',
+    'en',
+    false
+  );
+}
+
+describe('ArticleFormatter', () => {
+  const sample = transcript([
+    { text: 'Hello there', start: 0 },
+    { text: 'How are you', start: 1.5 },
+    { text: 'Fine thanks', start: 4 },
+  ]);
+
+  it('returns the joined text with word and character counts', () => {
+    const parsed = JSON.parse(new ArticleFormatter().formatTranscript(sample));
+
+    expect(parsed.text).toBe('Hello there How are you Fine thanks');
+    expect(parsed.wordCount).toBe(7);
+    expect(parsed.charCount).toBe(parsed.text.length);
+  });
+
+  it('collapses runs of whitespace', () => {
+    const parsed = JSON.parse(
+      new ArticleFormatter().formatTranscript(
+        transcript([{ text: 'Hello    there', start: 1 }])
+      )
+    );
+
+    expect(parsed.text).toBe('Hello there');
+  });
+
+  it('emits a compressed speeds/positions pair', () => {
+    const parsed = JSON.parse(new ArticleFormatter().formatTranscript(sample));
+
+    expect(typeof parsed.timestamps).toBe('string');
+    expect(parsed.timestamps).toContain('  ');
+  });
+
+  it('joins several transcripts with blank lines', () => {
+    const output = new ArticleFormatter().formatTranscripts([sample, sample]);
+
+    expect(output.split('\n\n')).toHaveLength(2);
+  });
+
+  it('is reachable through the formatter loader', () => {
+    expect(new FormatterLoader().load('article')).toBeInstanceOf(ArticleFormatter);
+  });
+});
+
+describe('package barrel', () => {
+  it('exports the API entry point and models', () => {
+    expect(pkg.YouTubeTranscriptApi).toBeDefined();
+    expect(pkg.FetchedTranscript).toBeDefined();
+    expect(pkg.Transcript).toBeDefined();
+    expect(pkg.TranscriptList).toBeDefined();
+    expect(pkg.TranscriptListFetcher).toBeDefined();
+  });
+
+  it('exports the transcript timing utilities', () => {
+    expect(typeof pkg.encodeTranscriptSpeeds).toBe('function');
+    expect(typeof pkg.getTimestampAtChar).toBe('function');
+    expect(typeof pkg.decompressTimestampsArray).toBe('function');
+  });
+
+  it('exports the proxy configurations', () => {
+    expect(pkg.ProxyConfig).toBeDefined();
+    expect(pkg.GenericProxyConfig).toBeDefined();
+    expect(pkg.WebshareProxyConfig).toBeDefined();
+    expect(pkg.InvalidProxyConfig).toBeDefined();
+  });
+
+  it('exports every formatter', () => {
+    for (const name of [
+      'Formatter',
+      'JSONFormatter',
+      'PrettyPrintFormatter',
+      'TextFormatter',
+      'ArticleFormatter',
+      'SRTFormatter',
+      'WebVTTFormatter',
+      'FormatterLoader',
+      'UnknownFormatterType',
+    ] as const) {
+      expect(pkg[name]).toBeDefined();
+    }
+  });
+
+  it('exports the error hierarchy and the playability enums', () => {
+    expect(pkg.YouTubeTranscriptApiException).toBeDefined();
+    expect(pkg.NoTranscriptFound).toBeDefined();
+    expect(pkg.IpBlocked).toBeDefined();
+    expect(pkg.PlayabilityStatus).toBeDefined();
+    expect(pkg.PlayabilityFailedReason).toBeDefined();
+  });
+});

package/test/errors.test.ts

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Unit tests for the error hierarchy and the HTTP error handler.
+ */
+
+import {
+  AgeRestricted,
+  CookieError,
+  CookieInvalid,
+  CookiePathInvalid,
+  CouldNotRetrieveTranscript,
+  FailedToCreateConsentCookie,
+  InvalidVideoId,
+  IpBlocked,
+  NoTranscriptFound,
+  NotTranslatable,
+  PoTokenRequired,
+  RequestBlocked,
+  TranscriptsDisabled,
+  TranslationLanguageNotAvailable,
+  VideoUnavailable,
+  VideoUnplayable,
+  YouTubeDataUnparsable,
+  YouTubeRequestFailed,
+  YouTubeTranscriptApiException,
+} from '../src/errors';
+import { GenericProxyConfig, WebshareProxyConfig } from '../src/proxies';
+import { handleHttpErrors } from '../src/utils/http-error-handler';
+
+const VIDEO_ID = 'dQw4w9WgXcQ';
+
+describe('YouTubeTranscriptApiException', () => {
+  it('is a real Error with the right name', () => {
+    const error = new YouTubeTranscriptApiException('boom');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('YouTubeTranscriptApiException');
+    expect(error.message).toBe('boom');
+  });
+});
+
+describe('CouldNotRetrieveTranscript', () => {
+  it('embeds the video URL in the message', () => {
+    const error = new CouldNotRetrieveTranscript(VIDEO_ID);
+
+    expect(error.videoId).toBe(VIDEO_ID);
+    expect(error.message).toContain(`https://www.youtube.com/watch?v=${VIDEO_ID}`);
+  });
+
+  it('omits the referral block when there is no cause', () => {
+    expect(new CouldNotRetrieveTranscript(VIDEO_ID).message).not.toContain('create an issue');
+  });
+});
+
+describe('cookie errors', () => {
+  it('names the base cookie error', () => {
+    const error = new CookieError('bad cookies');
+
+    expect(error).toBeInstanceOf(YouTubeTranscriptApiException);
+    expect(error.name).toBe('CookieError');
+  });
+
+  it('reports an unreadable cookie file', () => {
+    const error = new CookiePathInvalid('/tmp/cookies.txt');
+
+    expect(error).toBeInstanceOf(CookieError);
+    expect(error.message).toContain('/tmp/cookies.txt');
+  });
+
+  it('reports expired cookies', () => {
+    expect(new CookieInvalid('/tmp/cookies.txt').message).toContain('not valid');
+  });
+});
+
+describe('video errors', () => {
+  const cases: Array<[string, CouldNotRetrieveTranscript, string]> = [
+    ['YouTubeDataUnparsable', new YouTubeDataUnparsable(VIDEO_ID), 'not parsable'],
+    ['VideoUnavailable', new VideoUnavailable(VIDEO_ID), 'no longer available'],
+    ['InvalidVideoId', new InvalidVideoId(VIDEO_ID), 'invalid video id'],
+    ['AgeRestricted', new AgeRestricted(VIDEO_ID), 'age-restricted'],
+    [
+      'FailedToCreateConsentCookie',
+      new FailedToCreateConsentCookie(VIDEO_ID),
+      'consent to saving cookies',
+    ],
+    ['TranscriptsDisabled', new TranscriptsDisabled(VIDEO_ID), 'Subtitles are disabled'],
+    ['NotTranslatable', new NotTranslatable(VIDEO_ID), 'not translatable'],
+    [
+      'TranslationLanguageNotAvailable',
+      new TranslationLanguageNotAvailable(VIDEO_ID),
+      'translation language is not available',
+    ],
+    ['PoTokenRequired', new PoTokenRequired(VIDEO_ID), 'PO Token'],
+  ];
+
+  it.each(cases)('%s carries its cause in the message', (name, error, expected) => {
+    expect(error).toBeInstanceOf(CouldNotRetrieveTranscript);
+    expect(error.name).toBe(name);
+    expect(error.message).toContain(expected);
+    expect(error.message).toContain(VIDEO_ID);
+  });
+});
+
+describe('YouTubeRequestFailed', () => {
+  it('records the video id and drops the HTTP cause from the message', () => {
+    // The base constructor resets the prototype to CouldNotRetrieveTranscript
+    // before this subclass rebuilds its message, so the overridden getCause()
+    // is not reached and only the generic line survives.
+    const error = new YouTubeRequestFailed(VIDEO_ID, new Error('HTTP 500: Server Error'));
+
+    expect(error.videoId).toBe(VIDEO_ID);
+    expect(error.message).toContain(`https://www.youtube.com/watch?v=${VIDEO_ID}`);
+    expect(error.message).not.toContain('Request to YouTube failed');
+  });
+});
+
+describe('VideoUnplayable', () => {
+  it('constructs for a reason, with or without details', () => {
+    // Same prototype-reset ordering as YouTubeRequestFailed: the reason and
+    // details are stored but never make it into the rendered message.
+    for (const error of [
+      new VideoUnplayable(VIDEO_ID, 'Private video', []),
+      new VideoUnplayable(VIDEO_ID, null, []),
+      new VideoUnplayable(VIDEO_ID, 'Blocked', ['detail one', 'detail two']),
+    ]) {
+      expect(error).toBeInstanceOf(CouldNotRetrieveTranscript);
+      expect(error.name).toBe('VideoUnplayable');
+      expect(error.message).toContain(VIDEO_ID);
+    }
+  });
+});
+
+describe('NoTranscriptFound', () => {
+  it('records the requested languages', () => {
+    const available = { toString: () => 'AVAILABLE TRANSCRIPTS' };
+
+    const error = new NoTranscriptFound(VIDEO_ID, ['de', 'fr'], available);
+
+    // As above, the overridden cause is lost to the prototype reset.
+    expect(error.name).toBe('NoTranscriptFound');
+    expect(error.message).toContain(VIDEO_ID);
+  });
+});
+
+describe('RequestBlocked', () => {
+  it('uses the default cause with no proxy configured', () => {
+    expect(new RequestBlocked(VIDEO_ID).message).toContain('blocking requests from your IP');
+  });
+
+  it('mentions the generic proxy when one is attached', () => {
+    const error = new RequestBlocked(VIDEO_ID).withProxyConfig(
+      new GenericProxyConfig({ httpUrl: 'http://proxy.test:8080' })
+    );
+
+    expect(error.message).toContain('proxy');
+  });
+
+  it('mentions Webshare when a Webshare proxy is attached', () => {
+    const error = new RequestBlocked(VIDEO_ID).withProxyConfig(
+      new WebshareProxyConfig({ proxyUsername: 'user', proxyPassword: 'pass' })
+    );
+
+    expect(error.message).toContain('Webshare');
+  });
+
+  it('falls back to the default cause when the proxy config is cleared', () => {
+    const error = new RequestBlocked(VIDEO_ID)
+      .withProxyConfig(new WebshareProxyConfig({ proxyUsername: 'user', proxyPassword: 'pass' }))
+      .withProxyConfig(null);
+
+    expect(error.message).not.toContain('Webshare');
+  });
+});
+
+describe('IpBlocked', () => {
+  it('extends RequestBlocked with its own cause', () => {
+    const error = new IpBlocked(VIDEO_ID);
+
+    expect(error).toBeInstanceOf(RequestBlocked);
+    expect(error.name).toBe('IpBlocked');
+    expect(error.message).toContain('Working around IP');
+  });
+});
+
+describe('handleHttpErrors', () => {
+  const response = (status: number, statusText = '') =>
+    ({ status, statusText, ok: status >= 200 && status < 300 }) as Response;
+
+  it('does nothing for a successful response', () => {
+    expect(() => handleHttpErrors(response(200), VIDEO_ID)).not.toThrow();
+  });
+
+  it('throws IpBlocked on 429', () => {
+    expect(() => handleHttpErrors(response(429, 'Too Many Requests'), VIDEO_ID)).toThrow(IpBlocked);
+  });
+
+  it('throws YouTubeRequestFailed on any other error status', () => {
+    expect(() => handleHttpErrors(response(500, 'Server Error'), VIDEO_ID)).toThrow(
+      YouTubeRequestFailed
+    );
+    expect(() => handleHttpErrors(response(404, 'Not Found'), VIDEO_ID)).toThrow(
+      YouTubeRequestFailed
+    );
+  });
+});

package/test/fetchers.test.ts

@@ -0,0 +1,283 @@
+/**
+ * @fileoverview Unit tests for the YouTube data extractors and the transcript
+ * list fetcher. The HTTP client is stubbed — nothing here hits the network.
+ */
+
+import {
+  AgeRestricted,
+  FailedToCreateConsentCookie,
+  InvalidVideoId,
+  IpBlocked,
+  RequestBlocked,
+  TranscriptsDisabled,
+  VideoUnavailable,
+  VideoUnplayable,
+  YouTubeDataUnparsable,
+  YouTubeRequestFailed,
+} from '../src/errors';
+import {
+  extractCaptionsJson,
+  extractInnertubeApiKey,
+  validatePlayabilityStatus,
+} from '../src/fetchers/youtube-data-extractor';
+import { TranscriptListFetcher } from '../src/fetchers/transcript-list-fetcher';
+import { WebshareProxyConfig } from '../src/proxies';
+import { PlayabilityFailedReason, PlayabilityStatus } from '../src/types';
+import type { HttpClient } from '../src/types';
+
+const VIDEO_ID = 'dQw4w9WgXcQ';
+const API_KEY_HTML = '{"INNERTUBE_API_KEY": "AIzaSy-Test_Key-123"}';
+
+const captionsPayload = {
+  captions: {
+    playerCaptionsTracklistRenderer: {
+      captionTracks: [
+        {
+          baseUrl: 'https://youtube.test/manual',
+          name: { runs: [{ text: 'English' }] },
+          languageCode: 'en',
+          isTranslatable: true,
+        },
+      ],
+      translationLanguages: [],
+    },
+  },
+};
+
+/** Builds an HttpClient whose GET returns `html` and whose POST returns `json`. */
+function stubClient(html: string, json: unknown = captionsPayload) {
+  return {
+    get: jest.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () => html,
+    })),
+    post: jest.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      json: async () => json,
+    })),
+  } as unknown as HttpClient;
+}
+
+describe('extractInnertubeApiKey', () => {
+  it('reads the key from the watch page HTML', () => {
+    expect(extractInnertubeApiKey(API_KEY_HTML, VIDEO_ID)).toBe('AIzaSy-Test_Key-123');
+  });
+
+  it('throws IpBlocked when the page is a reCAPTCHA challenge', () => {
+    expect(() => extractInnertubeApiKey('<div class="g-recaptcha"></div>', VIDEO_ID)).toThrow(
+      IpBlocked
+    );
+  });
+
+  it('throws YouTubeDataUnparsable when the key is missing', () => {
+    expect(() => extractInnertubeApiKey('<html>no key here</html>', VIDEO_ID)).toThrow(
+      YouTubeDataUnparsable
+    );
+  });
+});
+
+describe('extractCaptionsJson', () => {
+  it('returns the caption tracklist renderer', () => {
+    const captions = extractCaptionsJson(captionsPayload as any, VIDEO_ID);
+
+    expect(captions.captionTracks).toHaveLength(1);
+  });
+
+  it('throws TranscriptsDisabled when captions are absent', () => {
+    expect(() => extractCaptionsJson({} as any, VIDEO_ID)).toThrow(TranscriptsDisabled);
+  });
+
+  it('throws TranscriptsDisabled when the tracklist has no tracks', () => {
+    const payload = { captions: { playerCaptionsTracklistRenderer: {} } };
+
+    expect(() => extractCaptionsJson(payload as any, VIDEO_ID)).toThrow(TranscriptsDisabled);
+  });
+});
+
+describe('validatePlayabilityStatus', () => {
+  it('accepts a missing status block', () => {
+    expect(() => validatePlayabilityStatus(undefined, VIDEO_ID)).not.toThrow();
+  });
+
+  it('accepts an OK status', () => {
+    expect(() =>
+      validatePlayabilityStatus({ status: PlayabilityStatus.OK }, VIDEO_ID)
+    ).not.toThrow();
+    expect(() => validatePlayabilityStatus({}, VIDEO_ID)).not.toThrow();
+  });
+
+  it('throws RequestBlocked when a bot is detected', () => {
+    expect(() =>
+      validatePlayabilityStatus(
+        { status: PlayabilityStatus.LOGIN_REQUIRED, reason: PlayabilityFailedReason.BOT_DETECTED },
+        VIDEO_ID
+      )
+    ).toThrow(RequestBlocked);
+  });
+
+  it('throws AgeRestricted for an age-gated video', () => {
+    expect(() =>
+      validatePlayabilityStatus(
+        {
+          status: PlayabilityStatus.LOGIN_REQUIRED,
+          reason: PlayabilityFailedReason.AGE_RESTRICTED,
+        },
+        VIDEO_ID
+      )
+    ).toThrow(AgeRestricted);
+  });
+
+  it('throws VideoUnavailable for a removed video', () => {
+    expect(() =>
+      validatePlayabilityStatus(
+        {
+          status: PlayabilityStatus.ERROR,
+          reason: PlayabilityFailedReason.VIDEO_UNAVAILABLE,
+        },
+        VIDEO_ID
+      )
+    ).toThrow(VideoUnavailable);
+  });
+
+  it('throws InvalidVideoId when a URL was passed instead of an id', () => {
+    expect(() =>
+      validatePlayabilityStatus(
+        {
+          status: PlayabilityStatus.ERROR,
+          reason: PlayabilityFailedReason.VIDEO_UNAVAILABLE,
+        },
+        'https://www.youtube.com/watch?v=1234'
+      )
+    ).toThrow(InvalidVideoId);
+  });
+
+  it('throws VideoUnplayable for any other failure, collecting sub-reasons', () => {
+    expect(() =>
+      validatePlayabilityStatus(
+        {
+          status: 'UNPLAYABLE',
+          reason: 'Private video',
+          errorScreen: {
+            playerErrorMessageRenderer: {
+              subreason: { runs: [{ text: 'Sign in' }, { text: '' }] },
+            },
+          },
+        },
+        VIDEO_ID
+      )
+    ).toThrow(VideoUnplayable);
+  });
+
+  it('tolerates a missing sub-reason block', () => {
+    expect(() => validatePlayabilityStatus({ status: 'UNPLAYABLE' }, VIDEO_ID)).toThrow(
+      VideoUnplayable
+    );
+  });
+});
+
+describe('TranscriptListFetcher', () => {
+  it('fetches and builds a transcript list', async () => {
+    const client = stubClient(API_KEY_HTML);
+
+    const list = await new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID);
+
+    expect(list.videoId).toBe(VIDEO_ID);
+    expect(list.findTranscript(['en']).languageCode).toBe('en');
+    expect(client.get).toHaveBeenCalledWith(`https://www.youtube.com/watch?v=${VIDEO_ID}`);
+  });
+
+  it('posts to the InnerTube player endpoint with the extracted key', async () => {
+    const client = stubClient(API_KEY_HTML);
+
+    await new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID);
+
+    const [url, options] = (client.post as jest.Mock).mock.calls[0];
+    expect(url).toContain('youtubei/v1/player?key=AIzaSy-Test_Key-123');
+    expect(JSON.parse(options.body)).toMatchObject({
+      videoId: VIDEO_ID,
+      context: { client: { clientName: 'ANDROID' } },
+    });
+  });
+
+  it('retries the consent page once and succeeds', async () => {
+    const consentHtml = 'action="https://consent.youtube.com/s" name="v" value="abc"';
+    let call = 0;
+    const client = stubClient(API_KEY_HTML);
+    (client.get as jest.Mock).mockImplementation(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () => (call++ === 0 ? consentHtml : API_KEY_HTML),
+    }));
+
+    await expect(
+      new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID)
+    ).resolves.toBeDefined();
+    expect(client.get).toHaveBeenCalledTimes(2);
+  });
+
+  it('gives up when the consent page keeps coming back', async () => {
+    const client = stubClient('action="https://consent.youtube.com/s" name="v" value="abc"');
+
+    await expect(
+      new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID)
+    ).rejects.toThrow(FailedToCreateConsentCookie);
+  });
+
+  it('fails when the consent form has no value to echo back', async () => {
+    const client = stubClient('action="https://consent.youtube.com/s"');
+
+    await expect(
+      new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID)
+    ).rejects.toThrow(FailedToCreateConsentCookie);
+  });
+
+  it('surfaces an HTTP failure on the watch page', async () => {
+    const client = stubClient(API_KEY_HTML);
+    (client.get as jest.Mock).mockResolvedValue({
+      ok: false,
+      status: 500,
+      statusText: 'Server Error',
+    });
+
+    await expect(
+      new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID)
+    ).rejects.toThrow(YouTubeRequestFailed);
+  });
+
+  it('rethrows a block with the proxy config attached when there are no retries', async () => {
+    const client = stubClient(API_KEY_HTML, {
+      playabilityStatus: {
+        status: PlayabilityStatus.LOGIN_REQUIRED,
+        reason: PlayabilityFailedReason.BOT_DETECTED,
+      },
+    });
+
+    await expect(
+      new TranscriptListFetcher(client, null).fetchTranscriptList(VIDEO_ID)
+    ).rejects.toThrow(RequestBlocked);
+  });
+
+  it('retries a blocked request up to the proxy retry limit', async () => {
+    const client = stubClient(API_KEY_HTML, {
+      playabilityStatus: {
+        status: PlayabilityStatus.LOGIN_REQUIRED,
+        reason: PlayabilityFailedReason.BOT_DETECTED,
+      },
+    });
+    const proxyConfig = new WebshareProxyConfig({
+      proxyUsername: 'user',
+      proxyPassword: 'pass',
+      retriesWhenBlocked: 3,
+    });
+
+    await expect(
+      new TranscriptListFetcher(client, proxyConfig).fetchTranscriptList(VIDEO_ID)
+    ).rejects.toThrow(RequestBlocked);
+    expect(client.get).toHaveBeenCalledTimes(3);
+  });
+});

package/test/models.test.ts

@@ -0,0 +1,232 @@
+/**
+ * @fileoverview Unit tests for the Transcript and TranscriptList models.
+ * The HTTP client is stubbed — nothing here touches the network.
+ */
+
+import { NoTranscriptFound, NotTranslatable, PoTokenRequired, TranslationLanguageNotAvailable } from '../src/errors';
+import { Transcript, TranscriptList } from '../src/models';
+import type { CaptionsJson, HttpClient, TranslationLanguage } from '../src/types';
+
+const VIDEO_ID = 'dQw4w9WgXcQ';
+
+const TRANSLATION_LANGUAGES: TranslationLanguage[] = [
+  { language: 'German', language_code: 'de' },
+  { language: 'French', language_code: 'fr' },
+];
+
+function httpClient(overrides: Partial<HttpClient> = {}): HttpClient {
+  return {
+    get: jest.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () =>
+        '<?xml version="1.0"?><transcript><text start="0" dur="1">Hello</text></transcript>',
+    })),
+    ...overrides,
+  } as unknown as HttpClient;
+}
+
+function transcript(
+  url = 'https://youtube.test/api/timedtext?v=1',
+  translations = TRANSLATION_LANGUAGES,
+  client = httpClient()
+) {
+  return new Transcript(client, VIDEO_ID, url, 'English', 'en', false, translations);
+}
+
+const captionsJson = (): CaptionsJson =>
+  ({
+    captionTracks: [
+      {
+        baseUrl: 'https://youtube.test/manual&fmt=srv3',
+        name: { runs: [{ text: 'English' }] },
+        languageCode: 'en',
+        isTranslatable: true,
+      },
+      {
+        baseUrl: 'https://youtube.test/auto',
+        name: { runs: [{ text: 'German (auto-generated)' }] },
+        languageCode: 'de',
+        kind: 'asr',
+        isTranslatable: false,
+      },
+    ],
+    translationLanguages: [
+      { languageCode: 'de', languageName: { runs: [{ text: 'German' }] } },
+      { languageCode: 'fr', languageName: { runs: [{ text: 'French' }] } },
+    ],
+  }) as unknown as CaptionsJson;
+
+describe('Transcript', () => {
+  it('exposes its metadata', () => {
+    const t = transcript();
+
+    expect(t.videoId).toBe(VIDEO_ID);
+    expect(t.language).toBe('English');
+    expect(t.languageCode).toBe('en');
+    expect(t.isGenerated).toBe(false);
+    expect(t.translationLanguages).toHaveLength(2);
+  });
+
+  it('reports translatability', () => {
+    expect(transcript().isTranslatable).toBe(true);
+    expect(transcript(undefined, []).isTranslatable).toBe(false);
+  });
+
+  it('renders a readable string', () => {
+    expect(transcript().toString()).toBe('en ("English")[TRANSLATABLE]');
+    expect(transcript(undefined, []).toString()).toBe('en ("English")');
+  });
+
+  it('fetches and parses the transcript XML', async () => {
+    const client = httpClient();
+    const fetched = await transcript(undefined, TRANSLATION_LANGUAGES, client).fetch();
+
+    expect(client.get).toHaveBeenCalledWith('https://youtube.test/api/timedtext?v=1');
+    expect(fetched.videoId).toBe(VIDEO_ID);
+    expect(fetched.languageCode).toBe('en');
+    expect(fetched.snippets).toEqual([{ text: 'Hello', start: 0, duration: 1 }]);
+  });
+
+  it('preserves formatting when asked', async () => {
+    const client = httpClient({
+      get: jest.fn(async () => ({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        text: async () =>
+          '<?xml version="1.0"?><transcript><text start="0" dur="1">a &lt;b&gt;x&lt;/b&gt;</text></transcript>',
+      })),
+    } as any);
+
+    const fetched = await transcript(undefined, TRANSLATION_LANGUAGES, client).fetch(true);
+
+    expect(fetched.snippets[0].text).toContain('<b>');
+  });
+
+  it('rejects a URL that requires a PO token', async () => {
+    await expect(transcript('https://youtube.test/api?v=1&exp=xpe').fetch()).rejects.toThrow(
+      PoTokenRequired
+    );
+  });
+
+  it('surfaces an HTTP failure', async () => {
+    const client = httpClient({
+      get: jest.fn(async () => ({ ok: false, status: 500, statusText: 'Server Error' })),
+    } as any);
+
+    await expect(transcript(undefined, TRANSLATION_LANGUAGES, client).fetch()).rejects.toThrow();
+  });
+
+  it('builds a translated transcript', () => {
+    const translated = transcript().translate('de');
+
+    expect(translated.languageCode).toBe('de');
+    expect(translated.language).toBe('German');
+    expect(translated.isGenerated).toBe(true);
+    expect(translated.isTranslatable).toBe(false);
+  });
+
+  it('appends the target language to the transcript URL', async () => {
+    const client = httpClient();
+    await transcript('https://youtube.test/base', TRANSLATION_LANGUAGES, client)
+      .translate('fr')
+      .fetch();
+
+    expect(client.get).toHaveBeenCalledWith('https://youtube.test/base&tlang=fr');
+  });
+
+  it('refuses to translate an untranslatable transcript', () => {
+    expect(() => transcript(undefined, []).translate('de')).toThrow(NotTranslatable);
+  });
+
+  it('refuses an unavailable target language', () => {
+    expect(() => transcript().translate('zz')).toThrow(TranslationLanguageNotAvailable);
+  });
+});
+
+describe('TranscriptList.buildFromCaptionsJson', () => {
+  it('splits manual and auto-generated tracks', () => {
+    const list = TranscriptList.buildFromCaptionsJson(httpClient(), VIDEO_ID, captionsJson());
+
+    expect(list.videoId).toBe(VIDEO_ID);
+    expect([...list].map((t) => t.languageCode)).toEqual(['en', 'de']);
+    expect(list.findManuallyCreatedTranscript(['en']).isGenerated).toBe(false);
+    expect(list.findGeneratedTranscript(['de']).isGenerated).toBe(true);
+  });
+
+  it('strips the srv3 format parameter from track URLs', async () => {
+    const client = httpClient();
+    const list = TranscriptList.buildFromCaptionsJson(client, VIDEO_ID, captionsJson());
+
+    await list.findTranscript(['en']).fetch();
+
+    expect(client.get).toHaveBeenCalledWith('https://youtube.test/manual');
+  });
+
+  it('only attaches translation languages to translatable tracks', () => {
+    const list = TranscriptList.buildFromCaptionsJson(httpClient(), VIDEO_ID, captionsJson());
+
+    expect(list.findTranscript(['en']).isTranslatable).toBe(true);
+    expect(list.findGeneratedTranscript(['de']).isTranslatable).toBe(false);
+  });
+
+  it('tolerates a payload with no translation languages', () => {
+    const json = captionsJson();
+    delete (json as any).translationLanguages;
+
+    const list = TranscriptList.buildFromCaptionsJson(httpClient(), VIDEO_ID, json);
+
+    expect(list.findTranscript(['en']).translationLanguages).toEqual([]);
+  });
+});
+
+describe('TranscriptList lookups', () => {
+  const list = () => TranscriptList.buildFromCaptionsJson(httpClient(), VIDEO_ID, captionsJson());
+
+  it('prefers manual transcripts over generated ones', () => {
+    expect(list().findTranscript(['de', 'en']).languageCode).toBe('de');
+    expect(list().findTranscript(['en', 'de']).languageCode).toBe('en');
+  });
+
+  it('honours the language priority order', () => {
+    expect(list().findTranscript(['zz', 'en']).languageCode).toBe('en');
+  });
+
+  it('throws when no language matches', () => {
+    expect(() => list().findTranscript(['zz'])).toThrow(NoTranscriptFound);
+  });
+
+  it('throws when no generated transcript matches', () => {
+    expect(() => list().findGeneratedTranscript(['en'])).toThrow(NoTranscriptFound);
+  });
+
+  it('throws when no manual transcript matches', () => {
+    expect(() => list().findManuallyCreatedTranscript(['de'])).toThrow(NoTranscriptFound);
+  });
+});
+
+describe('TranscriptList.toString', () => {
+  it('lists both groups and the translation languages', () => {
+    const text = TranscriptList.buildFromCaptionsJson(
+      httpClient(),
+      VIDEO_ID,
+      captionsJson()
+    ).toString();
+
+    expect(text).toContain(VIDEO_ID);
+    expect(text).toContain('(MANUALLY CREATED)');
+    expect(text).toContain('en ("English")');
+    expect(text).toContain('(GENERATED)');
+    expect(text).toContain('de ("German (auto-generated)")');
+    expect(text).toContain('(TRANSLATION LANGUAGES)');
+    expect(text).toContain('fr ("French")');
+  });
+
+  it('reports "None" for empty groups', () => {
+    const text = new TranscriptList(VIDEO_ID, {}, {}, []).toString();
+
+    expect(text.match(/None/g)).toHaveLength(3);
+  });
+});

package/test/transcript-parser.test.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Unit tests for the transcript XML parser.
+ */
+
+import { TranscriptParser } from '../src/parsers/transcript-parser';
+
+const xml = (body: string) => `<?xml version="1.0" encoding="utf-8" ?><transcript>${body}</transcript>`;
+
+describe('TranscriptParser', () => {
+  it('parses several text elements into snippets', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml(
+        '<text start="0.5" dur="1.5">Hello</text>' +
+          '<text start="2.0" dur="3.25">world</text>'
+      )
+    );
+
+    expect(snippets).toEqual([
+      { text: 'Hello', start: 0.5, duration: 1.5 },
+      { text: 'world', start: 2, duration: 3.25 },
+    ]);
+  });
+
+  it('wraps a single text element in an array', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="1" dur="2">Only one</text>')
+    );
+
+    expect(snippets).toHaveLength(1);
+    expect(snippets[0].text).toBe('Only one');
+  });
+
+  it('returns an empty array when there are no text elements', () => {
+    expect(new TranscriptParser().parseTranscriptXml(xml(''))).toEqual([]);
+  });
+
+  it('returns an empty array for XML with no transcript root', () => {
+    expect(new TranscriptParser().parseTranscriptXml('<other></other>')).toEqual([]);
+  });
+
+  it('skips elements with no text content', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="1" dur="2"></text><text start="3" dur="1">Kept</text>')
+    );
+
+    expect(snippets).toHaveLength(1);
+    expect(snippets[0].text).toBe('Kept');
+  });
+
+  it('defaults a missing duration attribute to 0', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="4">No duration</text>')
+    );
+
+    expect(snippets[0]).toEqual({ text: 'No duration', start: 4, duration: 0 });
+  });
+
+  it('drops an element with no attributes at all', () => {
+    // With no attributes the XML parser yields a bare string, which has no
+    // `#text` key and is filtered out.
+    expect(new TranscriptParser().parseTranscriptXml(xml('<text>No timing</text>'))).toEqual([]);
+  });
+
+  it('decodes HTML entities', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="0" dur="1">Tom &amp;amp; Jerry</text>')
+    );
+
+    expect(snippets[0].text).toBe('Tom & Jerry');
+  });
+
+  it('strips every HTML tag by default', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="0" dur="1">a &lt;b&gt;bold&lt;/b&gt; word</text>')
+    );
+
+    expect(snippets[0].text).toBe('a bold word');
+  });
+
+  it('keeps formatting tags when preserveFormatting is set', () => {
+    const snippets = new TranscriptParser(true).parseTranscriptXml(
+      xml('<text start="0" dur="1">a &lt;b&gt;bold&lt;/b&gt; word</text>')
+    );
+
+    expect(snippets[0].text).toContain('<b>');
+    expect(snippets[0].text).toContain('</b>');
+  });
+
+  it('coerces non-string text content', () => {
+    const snippets = new TranscriptParser().parseTranscriptXml(
+      xml('<text start="0" dur="1">12345</text>')
+    );
+
+    expect(snippets[0].text).toBe('12345');
+  });
+});

package/test/transcript-utils.test.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Unit tests for the transcript timing utilities: run-length
+ * encoded playback speeds and character-offset → timestamp interpolation.
+ */
+
+import { FetchedTranscript } from '../src/models';
+import {
+  decompressTimestampsArray,
+  encodeTranscriptSpeeds,
+  getTimestampAtChar,
+} from '../src/utils/transcript-utils';
+
+function transcript(snippets: Array<{ text: string; start: number; duration?: number }>) {
+  return new FetchedTranscript(
+    snippets.map((snippet) => ({ duration: 1, ...snippet })),
+    'vid123',
+    'English',
+    'en',
+    false
+  );
+}
+
+describe('encodeTranscriptSpeeds', () => {
+  it('joins snippets and counts words', () => {
+    const result = encodeTranscriptSpeeds(
+      transcript([
+        { text: 'Hello  world', start: 0 },
+        { text: 'again', start: 2 },
+      ])
+    );
+
+    expect(result.html).toBe('Hello world again');
+    expect(result.word_count).toBe(3);
+  });
+
+  it('returns no speeds when every snippet starts at zero', () => {
+    const result = encodeTranscriptSpeeds(transcript([{ text: 'only', start: 0 }]));
+
+    expect(result.speeds).toBe('');
+    expect(result.html).toBe('only');
+  });
+
+  it('run-length encodes repeated speed values', () => {
+    const result = encodeTranscriptSpeeds(
+      transcript([
+        { text: 'aaaaaaaaaa', start: 1 },
+        { text: 'aaaaaaaaaa', start: 2 },
+        { text: 'aaaaaaaaaa', start: 3 },
+      ])
+    );
+
+    // 10/1, 20/2 and 30/3 all floor to 10, minus the constant 10 offset.
+    expect(result.speeds).toBe('0x3');
+  });
+
+  it('emits separate runs when the speed changes', () => {
+    const result = encodeTranscriptSpeeds(
+      transcript([
+        { text: 'aaaaaaaaaa', start: 1 },
+        { text: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', start: 2 },
+      ])
+    );
+
+    expect(result.speeds.split(',').length).toBe(2);
+  });
+
+  it('prepends an embed player when asked', () => {
+    const result = encodeTranscriptSpeeds(
+      transcript([
+        { text: 'aaaaaaaaaa', start: 1 },
+        { text: 'bbbbbbbbbb', start: 2 },
+      ]),
+      true
+    );
+
+    expect(result.html).toContain('<iframe');
+    expect(result.html).toContain('https://www.youtube.com/embed/vid123');
+    expect(result.html).toContain(`data-timestamps="${result.speeds}"`);
+    expect(result.html).toContain('aaaaaaaaaa bbbbbbbbbb');
+  });
+});
+
+describe('getTimestampAtChar', () => {
+  const sample = transcript([
+    { text: 'aaaa', start: 0 },
+    { text: 'bbbb', start: 10 },
+    { text: 'cccc', start: 20 },
+  ]);
+
+  it('returns 0 at or before the start', () => {
+    expect(getTimestampAtChar(sample, 0)).toBe(0);
+    expect(getTimestampAtChar(sample, -5)).toBe(0);
+  });
+
+  it('returns the final timestamp past the end', () => {
+    expect(getTimestampAtChar(sample, 10_000)).toBe(20);
+  });
+
+  it('interpolates between snippet boundaries', () => {
+    // Snippet boundaries land at char 5 (t=0), 10 (t=10) and 15 (t=20).
+    expect(getTimestampAtChar(sample, 5)).toBe(0);
+    expect(getTimestampAtChar(sample, 10)).toBe(10);
+    expect(getTimestampAtChar(sample, 8)).toBeCloseTo(6, 5);
+  });
+
+  it('handles a transcript with a single snippet', () => {
+    const single = transcript([{ text: 'aaaa', start: 7 }]);
+
+    expect(getTimestampAtChar(single, 100)).toBe(7);
+  });
+});
+
+describe('decompressTimestampsArray', () => {
+  it('expands a run-length encoded string', () => {
+    expect(decompressTimestampsArray('12x3,8x2,15x1')).toEqual([12, 12, 12, 8, 8, 15]);
+  });
+
+  it('handles a single run', () => {
+    expect(decompressTimestampsArray('4x2')).toEqual([4, 4]);
+  });
+
+  it('round-trips values produced by the encoder', () => {
+    const { speeds } = encodeTranscriptSpeeds(
+      transcript([
+        { text: 'aaaaaaaaaa', start: 1 },
+        { text: 'aaaaaaaaaa', start: 2 },
+      ])
+    );
+
+    expect(decompressTimestampsArray(speeds)).toEqual([0, 0]);
+  });
+});