ytsubs

Extracts the transcript/ subtitles/ captions of Youtube videos.

Installation

npm install --global ytsubs

Note: For CLI usage only, no installation is required.

Note: Node.Js v22+ recommended.

Usage

CLI usage

Run npx -y ytsubs followed by either a Youtube URL, or an 11-character ID.

For example, all of the following will extract from the same Youtube video.

npx -y ytsubs "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

npx -y ytsubs "youtu.be/dQw4w9WgXcQ"

npx -y ytsubs dQw4w9WgXcQ

There aren't any options, just one CLI argument to identify which video. If you would like to specify options, use the SDK programmatically instead.

SDK usage

In your project, install ytsubs:

npm install ytsubs

Import the following methods from the SDK:

import {
    extractFromVideo,
    outputTextOnly,
    outputAsMarkdown,
} from 'ytsubs';

Optionally, create an options object to override defaults:

const options = {
    noCache: true, // default: false - saves in `.yt-subs-cache` under home
    noRetry: true, // default: false - if first attempt fails, retry with backoff
    language: 'es', // default: 'en' - can be any 2-letter language code
    textType: 'srt', // default: 'text' - can be 'text', 'srt', or 'vtt'
};

To extract the transcript:

const result = await extractFromVideo({
    videoUrl, // youtube URL or video ID
    options, // optional
});

The result object will contain the following fields:

• videoUrl: The video URL or ID that was passed in
• title: Video title
• metadata: Miscellaneous info (video ID, thumbnail URLs, etc.)
• description: Video description
• text: Video transcript (as text, SRT, or VTT)

To convert the transcript to markdown format:

const markdown = outputAsMarkdown(result);

To convert the transcript to text format:

const text = outputTextOnly(result);

Generative AI agent-skill usage

This module comes with its own agent-skill, which complies with the agent skills specification.

To use it, you need to place a copy where your generative AI harness (e.g. Claude Code, Kimi-CLI) is able to find it:

npx skills add bguiz/ytsubs --skill youtube-transcript-extract

To invoke it explicitly within your harness use a command, e.g.

/youtube-transcript-extract youtu.be/dQw4w9WgXcQ

You can also use natural language to invoke it within your harness, e.g.

download subtitles of youtu.be/dQw4w9WgXcQ and save to subtitles.txt

Read the skill file to see how it works: ./.agents/skills/youtube-transcript-extract/SKILL.md

MCP server usage

This module comes with its own MCP server, which complies with the Model Context Protocol specification (dated 2025/11/25). It supports both stdio and streamable HTTP transports.

Terminal: To run the MCP server in a terminal, enter the following command:

npx -y -p ytsubs ytsubs-mcp stdio # for stdio transport
npx -y -p ytsubs ytsubs-mcp http # for streamable HTTP transport

Inspector: To connect using the MCP inspector tool:

MCP_AUTO_OPEN_ENABLED=false DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector $( which node ) $PWD/yt-subs-mcp.js

Run the above command to start an MCP client that is connected to the MCP server over stdio. You should output similar to:

🚀 MCP Inspector is up and running at:
   http://localhost:6274

Visit that URL in a browser, press the "connect" button, then press the "list tools" button, then press the "youtube-transcript-extract" button, and finally, press the "run tool" button.

In the "history" pane, you should see a new invocation of "tools/call". Expand the view from this using the triangular icon, and yopu will be able to see both the request and response in full.

Programmatically: To run and connect programmatically from Node.JS:

Import MCP modules.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

For MCP over stdio, initialise a transport object like this (simple):

const transport = new StdioClientTransport({
    command: 'ytsubs-mcp',
    args: ['stdio'],
    stderr: 'pipe',
});

For MCP over streamable HTTP, initialise a transport object like this (complex):

serverProcess = spawn(
    'ytsubs-mcp',
    ['http'], {
        stdio: ['ignore', 'ignore', 'pipe'],
    },
);

let port;
try {
    port = await new Promise((resolve, reject) => {
        let stderr = '';
        serverProcess.stderr.on('data', (chunk) => {
            stderr += chunk.toString();
            const match = stderr.match(/LISTEN (\d+)/);
            if (match) {
                resolve(parseInt(match[1], 10));
            }
        });
        serverProcess.on('error', reject);
        serverProcess.on('close', (code) => {
            reject(new Error(`server exited (code ${code}) before announcing port`));
        });
    });
} catch (err) {
    if (err.code === 'ENOENT') {
        assert.fail('ytsubs-mcp not found on PATH — run in the project directory: npm link');
    }
    throw err;
}

const transport = new StreamableHTTPClientTransport(
    new URL(`http://127.0.0.1:${port}/mcp`),
);

Then create na MCP client that connects to the transport.

client = new Client({ name: 'test-client', version: '0.0.1' });
await client.connect(transport);

// interact with MCP server using client
await client.listTools();
await client.callTool({
    name: 'youtube-transcript-extract',
    arguments: { videoUrl: VIDEO_URL },
});

Contributing

Your contributions are welcome!

Submitting an update

Base set up:

Fork this repo on Github.

git clone git@github.com:${YOUR_GITHUB_USERNAME}/ytsubs.git
cd ytsubs
npm install
npm link # needed to test `npx` equivalent
ytsubs # test that npm link is active

Create a new branch prefixed with feat/, fix/, docs/, refactor/, or test/.

git fetch origin main:main
git checkout main

git checkout -b feat/my-new-feature # for features
git checkout -b fix/my-bug-fix # for bugs
git checkout -b docs/my-docs-update # for documentation
git checkout -b refactor/my-code-quality-improvement # for refactors
git checkout -b test/my-new-test # for refactors

Make your changes, then ensure that:

• there are no regressions, and
• that code coverage has not worsened

npm run test # run both unit tests and end-to-end tests

npm run coverage # run unit tests and measure code coverage

Push your git branch to the github remote of your fork:

git push origin ${YOUR_BRANCH_NAME}

Then submit a Github PR based on the branch that you have just pushed.

Submitting a request

Submit a Github issue.

Author

Brendan Graetz

Licence

MIT