v0.4.0: getTranscriptLanguages for GET /transcript/languages (free)

Author: TubeAgentKit

README.md

@@ -58,6 +58,15 @@ Each segment is `{ start, duration, text }` with `start` and `duration` in secon
 | `cached` | `true` when served from the stored copy rather than fetched from YouTube just now |
 | `fetched_at` | ISO 8601 time it was fetched from YouTube |
 
+Not sure which languages a video has? `getTranscriptLanguages` lists them for free, before you spend a credit:
+
+```ts
+const { default_language_code, languages } = await client.getTranscriptLanguages({ v: "kJQP7kiw5Fk" });
+for (const lang of languages) console.log(lang.language_code, lang.caption_type, lang.name); // "es manual Spanish"
+```
+
+An empty `languages` list means the video has captions turned off.
+
 ### Batch: many videos at once
 
 Queue up to 100 videos in one call; transcripts are fetched in the background. Submitting is free, each video that returns a transcript costs 1 credit, and failed videos are never charged (10 videos where 2 have no captions = 8 credits).
@@ -163,6 +172,7 @@ try {
 | Method | Endpoint | Credits |
 | --- | --- | --- |
 | `getTranscript(params)` | `GET /transcript` (optional `timestamps: true`) | 1 |
+| `getTranscriptLanguages(params)` | `GET /transcript/languages` | free |
 | `createBatch(params)` | `POST /batch` (up to 100 videos) | 1 per successful video |
 | `getBatch(params)` / `waitForBatch(id)` | `GET /batch` | free |
 | `search(params)` | `GET /search` | 1 |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tubeagentkit/getyoutubetranscript",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "YouTube transcript API for Node.js and TypeScript: get YouTube video transcripts, captions and subtitles with timestamps, search YouTube, and list channel and playlist videos. No proxies or headless browser.",
   "type": "module",
   "main": "./dist/index.cjs",

src/client.ts

@@ -12,6 +12,7 @@ import type {
   CreditsData,
   GetChannelLatestParams,
   GetPlaylistParams,
+  GetTranscriptLanguagesParams,
   GetTranscriptParams,
   GetYouTubeTranscriptOptions,
   ListChannelVideosParams,
@@ -23,6 +24,7 @@ import type {
   SearchParams,
   SignupResponse,
   TranscriptData,
+  TranscriptLanguagesData,
   VerifySignupResponse,
 } from "./types.js";
 
@@ -154,6 +156,14 @@ export class GetYouTubeTranscript {
     });
   }
 
+  /**
+   * The caption languages a video offers (manual and auto-generated), before
+   * fetching one. Free. An empty `languages` list means captions are turned off.
+   */
+  getTranscriptLanguages(params: GetTranscriptLanguagesParams): Promise<TranscriptLanguagesData> {
+    return this.get<TranscriptLanguagesData>("/transcript/languages", { v: params.v });
+  }
+
   /**
    * Queue transcripts for up to 100 videos in one call. Free to submit:
    * 1 credit per video that returns a transcript, failed videos are never

src/index.ts

@@ -17,6 +17,7 @@ export type {
   GetBatchParams,
   GetChannelLatestParams,
   GetPlaylistParams,
+  GetTranscriptLanguagesParams,
   GetTranscriptParams,
   GetYouTubeTranscriptOptions,
   ListChannelVideosParams,
@@ -32,6 +33,8 @@ export type {
   SignupResponse,
   TranscriptData,
   TranscriptFields,
+  TranscriptLanguage,
+  TranscriptLanguagesData,
   VerifySignupResponse,
   VideoResult,
   WaitForBatchOptions,

src/types.ts

@@ -74,6 +74,30 @@ export interface TranscriptData extends TranscriptFields {
   cached: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// GET /transcript/languages (free)
+// ---------------------------------------------------------------------------
+
+export interface GetTranscriptLanguagesParams {
+  /** YouTube video URL (full or short) or an 11-character video ID. */
+  v: string;
+}
+
+export interface TranscriptLanguage {
+  language_code: string;
+  /** YouTube's display name, e.g. "English (auto-generated)". */
+  name: string;
+  caption_type: "manual" | "auto";
+}
+
+export interface TranscriptLanguagesData {
+  video_id: string;
+  /** What `getTranscript` returns with no `language`; `null` when the video has no captions. */
+  default_language_code: string | null;
+  /** One per language and caption type. Empty when the video has captions turned off. */
+  languages: TranscriptLanguage[];
+}
+
 // ---------------------------------------------------------------------------
 // POST /batch, GET /batch
 // ---------------------------------------------------------------------------

test/batch.test.ts

@@ -21,6 +21,13 @@ describe("batch methods", () => {
     client = new GetYouTubeTranscript({ apiKey: "sk_live_test123", fetch: fetchMock as unknown as typeof fetch });
   });
 
+  it("getTranscriptLanguages sends the video param", async () => {
+    const data = { video_id: "kJQP7kiw5Fk", default_language_code: "en", languages: [{ language_code: "en", name: "English", caption_type: "manual" }] };
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { success: true, data }));
+    expect(await client.getTranscriptLanguages({ v: "https://youtu.be/kJQP7kiw5Fk" })).toEqual(data);
+    expect(fetchMock.mock.calls[0][0]).toBe(`${BASE}/transcript/languages?v=https%3A%2F%2Fyoutu.be%2FkJQP7kiw5Fk`);
+  });
+
   it("createBatch POSTs a JSON body with the Idempotency-Key header", async () => {
     fetchMock.mockResolvedValueOnce(jsonResponse(202, batch("queued", { webhook_secret: "whsec_x" })));
     const result = await client.createBatch({

test/live.integration.test.ts

@@ -36,6 +36,12 @@ describe.skipIf(!apiKey)("live integration", () => {
     20_000,
   );
 
+  it("getTranscriptLanguages lists caption languages (free)", async () => {
+    const data = await client.getTranscriptLanguages({ v: "jNQXAC9IVRw" });
+    expect(data.languages.length).toBeGreaterThan(0);
+    expect(data.languages.map((lang) => lang.language_code)).toContain(data.default_language_code);
+  }, 20_000);
+
   it("getCredits returns the key's plan and balance (free)", async () => {
     const data = await client.getCredits();
     expect(typeof data.plan_credits_left).toBe("number");