youtube-transcript-api-ts 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# youtube-transcript-api-ts
+
+A simple, dependency-free (except axios) TypeScript library to fetch transcripts/captions for YouTube videos. This is a port of the popular Python [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api).
+
+## Features
+
+- **Fetch Transcripts**: Retrieve the full transcript of a YouTube video.
+- **Support for Auto-Generated Captions**: Works with both manually created and auto-generated (ASR) captions.
+- **Language Selection**: Automatically selects the most appropriate language (defaults to English).
+- **Text Format**: Option to retrieve the transcript as a single block of text or as a list of timestamped objects.
+- **No API Key Required**: Does not require a Google/YouTube Data API key.
+
+## Installation
+
+```bash
+npm install youtube-transcript-api-ts
+# or
+yarn add youtube-transcript-api-ts
+```
+
+## Usage
+
+### Basic Usage (Get JSON Objects)
+
+By default, the library returns an array of objects containing the text, duration, and offset.
+
+```typescript
+import { YoutubeTranscript } from 'youtube-transcript-ts';
+
+async function main() {
+  try {
+    const transcript = await YoutubeTranscript.fetchTranscript('dQw4w9WgXcQ');
+    
+    console.log(transcript);
+    /* Output:
+    [
+      { text: 'Never gonna give you up', duration: 2.1, offset: 0.5, lang: 'en' },
+      { text: 'Never gonna let you down', duration: 1.5, offset: 2.6, lang: 'en' },
+      ...
+    ]
+    */
+  } catch (e) {
+    console.error('Error fetching transcript:', e);
+  }
+}
+
+main();
+```
+
+### Get Transcript as Text
+
+If you just want the full text of the video without timestamps:
+
+```typescript
+const text = await YoutubeTranscript.fetchTranscript('dQw4w9WgXcQ', { format: 'text' });
+console.log(text);
+// Output: "Never gonna give you up Never gonna let you down ..."
+```
+
+### Configuration Options
+
+You can pass a configuration object as the second argument:
+
+```typescript
+YoutubeTranscript.fetchTranscript('video_id', {
+  lang: 'de', // Priority language (default: 'en')
+  country: 'DE', // Optional country code
+  format: 'text' // Optional: 'object' (default) or 'text'
+});
+```
+
+## Error Handling
+
+The library throws specific errors for various failure cases. You can import these error classes to handle them:
+
+```typescript
+import { 
+  YoutubeTranscript, 
+  VideoUnavailable, 
+  TranscriptsDisabled 
+} from 'youtube-transcript-ts';
+
+try {
+  await YoutubeTranscript.fetchTranscript('invalid-id');
+} catch (e) {
+  if (e instanceof VideoUnavailable) {
+    console.error('Video is unavailable');
+  } else if (e instanceof TranscriptsDisabled) {
+    console.error('Transcripts are disabled for this video');
+  } else {
+    console.error('Unknown error:', e);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/Transcript.d.ts

@@ -0,0 +1,17 @@
+import { TranscriptResponse } from './types';
+export declare class Transcript {
+    private videoId;
+    private url;
+    language: string;
+    languageCode: string;
+    isGenerated: boolean;
+    translationLanguages: {
+        language: string;
+        languageCode: string;
+    }[];
+    constructor(videoId: string, url: string, language: string, languageCode: string, isGenerated: boolean, translationLanguages: {
+        language: string;
+        languageCode: string;
+    }[]);
+    fetch(preserveFormatting?: boolean): Promise<TranscriptResponse[]>;
+}

package/dist/Transcript.js

@@ -0,0 +1,81 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transcript = void 0;
+const axios_1 = __importDefault(require("axios"));
+const fast_xml_parser_1 = require("fast-xml-parser");
+const he = __importStar(require("he"));
+class Transcript {
+    constructor(videoId, url, language, languageCode, isGenerated, translationLanguages) {
+        this.videoId = videoId;
+        this.url = url;
+        this.language = language;
+        this.languageCode = languageCode;
+        this.isGenerated = isGenerated;
+        this.translationLanguages = translationLanguages;
+    }
+    async fetch(preserveFormatting = false) {
+        const response = await axios_1.default.get(this.url);
+        const parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '',
+        });
+        const xml = parser.parse(response.data);
+        if (!xml.transcript || !xml.transcript.text) {
+            return [];
+        }
+        // Ensure it's an array even if single item
+        const textElements = Array.isArray(xml.transcript.text) ? xml.transcript.text : [xml.transcript.text];
+        return textElements.map((item) => {
+            let text = item['#text'] || '';
+            if (!preserveFormatting) {
+                // Remove HTML tags
+                text = text.replace(/<[^>]*>/g, '');
+            }
+            // Decode HTML entities
+            text = he.decode(text);
+            return {
+                text,
+                duration: parseFloat(item.dur) || 0.0,
+                offset: parseFloat(item.start) || 0.0,
+                lang: this.languageCode
+            };
+        });
+    }
+}
+exports.Transcript = Transcript;

package/dist/TranscriptList.d.ts

@@ -0,0 +1,16 @@
+import { Transcript } from './Transcript';
+export declare class TranscriptList {
+    private videoId;
+    private manuallyCreatedTranscripts;
+    private generatedTranscripts;
+    constructor(videoId: string, manuallyCreatedTranscripts: {
+        [key: string]: Transcript;
+    }, generatedTranscripts: {
+        [key: string]: Transcript;
+    });
+    findTranscript(languageCodes: string[]): Transcript;
+    findGeneratedTranscript(languageCodes: string[]): Transcript;
+    findManuallyCreatedTranscript(languageCodes: string[]): Transcript;
+    private _findTranscript;
+    [Symbol.iterator](): Generator<Transcript, void, unknown>;
+}

package/dist/TranscriptList.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranscriptList = void 0;
+const errors_1 = require("./errors");
+class TranscriptList {
+    constructor(videoId, manuallyCreatedTranscripts, generatedTranscripts) {
+        this.videoId = videoId;
+        this.manuallyCreatedTranscripts = manuallyCreatedTranscripts;
+        this.generatedTranscripts = generatedTranscripts;
+    }
+    findTranscript(languageCodes) {
+        return this._findTranscript(languageCodes, [this.manuallyCreatedTranscripts, this.generatedTranscripts]);
+    }
+    findGeneratedTranscript(languageCodes) {
+        return this._findTranscript(languageCodes, [this.generatedTranscripts]);
+    }
+    findManuallyCreatedTranscript(languageCodes) {
+        return this._findTranscript(languageCodes, [this.manuallyCreatedTranscripts]);
+    }
+    _findTranscript(languageCodes, transcriptDicts) {
+        for (const lang of languageCodes) {
+            for (const transcriptDict of transcriptDicts) {
+                if (lang in transcriptDict) {
+                    return transcriptDict[lang];
+                }
+            }
+        }
+        // If unable to find exact match
+        throw new errors_1.NoTranscriptFound(this.videoId, languageCodes);
+    }
+    // Iterate over all transcripts
+    *[Symbol.iterator]() {
+        for (const t of Object.values(this.manuallyCreatedTranscripts))
+            yield t;
+        for (const t of Object.values(this.generatedTranscripts))
+            yield t;
+    }
+}
+exports.TranscriptList = TranscriptList;

package/dist/TranscriptListFetcher.d.ts

@@ -0,0 +1,11 @@
+import { AxiosInstance } from 'axios';
+import { TranscriptList } from './TranscriptList';
+export declare class TranscriptListFetcher {
+    private http_client;
+    constructor(http_client: AxiosInstance);
+    fetch(videoId: string): Promise<TranscriptList>;
+    private _fetchVideoHtml;
+    private _fetchCaptionsJson;
+    private _extractInnertubeApiKey;
+    private _buildTranscriptList;
+}

package/dist/TranscriptListFetcher.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranscriptListFetcher = void 0;
+const TranscriptList_1 = require("./TranscriptList");
+const Transcript_1 = require("./Transcript");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+class TranscriptListFetcher {
+    constructor(http_client) {
+        this.http_client = http_client;
+    }
+    async fetch(videoId) {
+        const html = await this._fetchVideoHtml(videoId);
+        const captionsJson = await this._fetchCaptionsJson(videoId, html);
+        return this._buildTranscriptList(videoId, captionsJson);
+    }
+    async _fetchVideoHtml(videoId) {
+        try {
+            const response = await this.http_client.get(constants_1.WATCH_URL.replace('{videoId}', videoId));
+            return response.data;
+        }
+        catch (e) {
+            if (e.response && e.response.status === 429) {
+                throw new errors_1.TooManyRequests(videoId);
+            }
+            throw new errors_1.YouTubeRequestFailed(videoId, e);
+        }
+    }
+    async _fetchCaptionsJson(videoId, html) {
+        var _a;
+        const apiKey = this._extractInnertubeApiKey(html);
+        // Check if playability status allows (simulated)
+        if (html.includes('class="g-recaptcha"')) {
+            throw new errors_1.TooManyRequests(videoId);
+        }
+        if (!apiKey) {
+            throw new errors_1.VideoUnavailable(videoId);
+        }
+        const response = await this.http_client.post(constants_1.INNERTUBE_API_URL.replace('{apiKey}', apiKey), {
+            context: constants_1.INNERTUBE_CONTEXT,
+            videoId: videoId,
+        });
+        const data = response.data;
+        if (!data.playabilityStatus || data.playabilityStatus.status !== 'OK') {
+            if (data.playabilityStatus.reason) {
+                throw new errors_1.VideoUnavailable(videoId);
+            }
+        }
+        const captions = (_a = data.captions) === null || _a === void 0 ? void 0 : _a.playerCaptionsTracklistRenderer;
+        if (!captions) {
+            throw new errors_1.TranscriptsDisabled(videoId);
+        }
+        return captions;
+    }
+    _extractInnertubeApiKey(html) {
+        const match = html.match(/"INNERTUBE_API_KEY":\s*"([a-zA-Z0-9_-]+)"/);
+        return match ? match[1] : null;
+    }
+    _buildTranscriptList(videoId, captionsJson) {
+        const translationLanguages = (captionsJson.translationLanguages || []).map((lang) => ({
+            language: lang.languageName.runs[0].text,
+            languageCode: lang.languageCode,
+        }));
+        const manuallyCreatedTranscripts = {};
+        const generatedTranscripts = {};
+        for (const caption of captionsJson.captionTracks || []) {
+            const isGenerated = caption.kind === 'asr';
+            const transcriptDict = isGenerated
+                ? generatedTranscripts
+                : manuallyCreatedTranscripts;
+            const languageCode = caption.languageCode;
+            transcriptDict[languageCode] = new Transcript_1.Transcript(videoId, caption.baseUrl.replace(/&fmt=srv3/, ''), caption.name.runs[0].text, languageCode, isGenerated, caption.isTranslatable ? translationLanguages : []);
+        }
+        return new TranscriptList_1.TranscriptList(videoId, manuallyCreatedTranscripts, generatedTranscripts);
+    }
+}
+exports.TranscriptListFetcher = TranscriptListFetcher;

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const WATCH_URL = "https://www.youtube.com/watch?v={videoId}";
+export declare const INNERTUBE_API_URL = "https://www.youtube.com/youtubei/v1/player?key={apiKey}";
+export declare const INNERTUBE_CONTEXT: {
+    client: {
+        clientName: string;
+        clientVersion: string;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INNERTUBE_CONTEXT = exports.INNERTUBE_API_URL = exports.WATCH_URL = void 0;
+exports.WATCH_URL = 'https://www.youtube.com/watch?v={videoId}';
+exports.INNERTUBE_API_URL = 'https://www.youtube.com/youtubei/v1/player?key={apiKey}';
+exports.INNERTUBE_CONTEXT = {
+    client: {
+        clientName: 'ANDROID',
+        clientVersion: '20.10.38',
+    },
+};

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+export declare class YouTubeTranscriptError extends Error {
+    message: string;
+    constructor(message: string);
+}
+export declare class VideoUnavailable extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}
+export declare class YouTubeRequestFailed extends YouTubeTranscriptError {
+    videoId: string;
+    cause: any;
+    constructor(videoId: string, cause: any);
+}
+export declare class TranscriptsDisabled extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}
+export declare class NoTranscriptFound extends YouTubeTranscriptError {
+    videoId: string;
+    languages: string[];
+    constructor(videoId: string, languages: string[]);
+}
+export declare class NotTranslatable extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}
+export declare class TranslationLanguageNotAvailable extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}
+export declare class InvalidVideoId extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}
+export declare class TooManyRequests extends YouTubeTranscriptError {
+    videoId: string;
+    constructor(videoId: string);
+}

package/dist/errors.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TooManyRequests = exports.InvalidVideoId = exports.TranslationLanguageNotAvailable = exports.NotTranslatable = exports.NoTranscriptFound = exports.TranscriptsDisabled = exports.YouTubeRequestFailed = exports.VideoUnavailable = exports.YouTubeTranscriptError = void 0;
+class YouTubeTranscriptError extends Error {
+    constructor(message) {
+        super(message);
+        this.message = message;
+        this.name = 'YouTubeTranscriptError';
+    }
+}
+exports.YouTubeTranscriptError = YouTubeTranscriptError;
+class VideoUnavailable extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`The video ${videoId} is unavailable`);
+        this.videoId = videoId;
+        this.name = 'VideoUnavailable';
+    }
+}
+exports.VideoUnavailable = VideoUnavailable;
+class YouTubeRequestFailed extends YouTubeTranscriptError {
+    constructor(videoId, cause) {
+        super(`Request failed for video ${videoId}: ${cause.message}`);
+        this.videoId = videoId;
+        this.cause = cause;
+        this.name = 'YouTubeRequestFailed';
+    }
+}
+exports.YouTubeRequestFailed = YouTubeRequestFailed;
+class TranscriptsDisabled extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`Transcripts are disabled for video ${videoId}`);
+        this.videoId = videoId;
+        this.name = 'TranscriptsDisabled';
+    }
+}
+exports.TranscriptsDisabled = TranscriptsDisabled;
+class NoTranscriptFound extends YouTubeTranscriptError {
+    constructor(videoId, languages) {
+        super(`No transcript found for video ${videoId} in languages: ${languages.join(', ')}`);
+        this.videoId = videoId;
+        this.languages = languages;
+        this.name = 'NoTranscriptFound';
+    }
+}
+exports.NoTranscriptFound = NoTranscriptFound;
+class NotTranslatable extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`Video ${videoId} is not translatable`);
+        this.videoId = videoId;
+        this.name = 'NotTranslatable';
+    }
+}
+exports.NotTranslatable = NotTranslatable;
+class TranslationLanguageNotAvailable extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`Translation language not available for video ${videoId}`);
+        this.videoId = videoId;
+        this.name = 'TranslationLanguageNotAvailable';
+    }
+}
+exports.TranslationLanguageNotAvailable = TranslationLanguageNotAvailable;
+class InvalidVideoId extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`Invalid video id: ${videoId}`);
+        this.videoId = videoId;
+        this.name = 'InvalidVideoId';
+    }
+}
+exports.InvalidVideoId = InvalidVideoId;
+class TooManyRequests extends YouTubeTranscriptError {
+    constructor(videoId) {
+        super(`YouTube is receiving too many requests from this IP and now requires solving a captcha to fetch the transcript for video ${videoId}`);
+        this.videoId = videoId;
+        this.name = 'TooManyRequests';
+    }
+}
+exports.TooManyRequests = TooManyRequests;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { TranscriptResponse } from './types';
+export interface TranscriptConfig {
+    lang?: string;
+    country?: string;
+}
+export declare class YoutubeTranscript {
+    /**
+     * Fetch transcript as a list of objects (default).
+     */
+    static fetchTranscript(videoId: string, config?: TranscriptConfig & {
+        format?: 'object';
+    }): Promise<TranscriptResponse[]>;
+    /**
+     * Fetch transcript as a single string.
+     */
+    static fetchTranscript(videoId: string, config?: TranscriptConfig & {
+        format: 'text';
+    }): Promise<string>;
+    static fetchTranscriptList(videoId: string): Promise<import("./TranscriptList").TranscriptList>;
+}

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YoutubeTranscript = void 0;
+const axios_1 = __importDefault(require("axios"));
+const TranscriptListFetcher_1 = require("./TranscriptListFetcher");
+class YoutubeTranscript {
+    static async fetchTranscript(videoId, config) {
+        const httpClient = axios_1.default.create();
+        const fetcher = new TranscriptListFetcher_1.TranscriptListFetcher(httpClient);
+        const list = await fetcher.fetch(videoId);
+        // Default behavior: try to find 'en' or use the first available? 
+        // The Python logic: find_transcript(['en']) is default. 
+        // We will stick to 'en' as default or provided lang.
+        const langList = (config === null || config === void 0 ? void 0 : config.lang) ? [config.lang] : ['en'];
+        let transcriptItems;
+        try {
+            const transcript = list.findTranscript(langList);
+            transcriptItems = await transcript.fetch();
+        }
+        catch (e) {
+            throw e;
+        }
+        if ((config === null || config === void 0 ? void 0 : config.format) === 'text') {
+            return transcriptItems.map(t => t.text).join(' ');
+        }
+        return transcriptItems;
+    }
+    static async fetchTranscriptList(videoId) {
+        const httpClient = axios_1.default.create();
+        const fetcher = new TranscriptListFetcher_1.TranscriptListFetcher(httpClient);
+        return await fetcher.fetch(videoId);
+    }
+}
+exports.YoutubeTranscript = YoutubeTranscript;

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export interface TranscriptConfig {
+    lang: string;
+}
+export interface TranscriptResponse {
+    text: string;
+    duration: number;
+    offset: number;
+    lang?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "youtube-transcript-api-ts",
+  "version": "1.0.0",
+  "description": "A lightweight TypeScript library to fetch YouTube video transcripts.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/test_fetch.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "youtube",
+    "transcript",
+    "captions",
+    "subtitle",
+    "scraper",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yogesh-G-3468/youtube-transcript-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Yogesh-G-3468/youtube-transcript-ts/issues"
+  },
+  "homepage": "https://github.com/Yogesh-G-3468/youtube-transcript-ts#readme",
+  "dependencies": {
+    "axios": "^1.13.5",
+    "fast-xml-parser": "^5.3.5",
+    "he": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/he": "^1.2.3",
+    "@types/node": "^25.2.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}