YouTube Transcript Tool (ytt)

A simple command-line interface (CLI) tool to fetch and display the transcript of a YouTube video using pre-configured preferred languages.

This tool wraps the youtube-transcript-api Python library, simplifying the process of fetching YouTube video transcripts.

Features

• Automatically extracts video ID from multiple YouTube URL formats (including Shorts)
• Outputs video title and description along with the transcript in Markdown format
• Automatically copies the output to the clipboard
• Prioritizes manually created transcripts based on preferred languages
• Falls back to automatically generated transcripts if no manual ones are available
• Caches previously fetched transcripts and metadata to speed up repeated requests

Installation

Try it instantly with uvx

uvx lets you run tools directly from a repository without installing them permanently:

uvx --from git+https://github.com/dudarev/ytt.git ytt --help

This downloads and executes the latest version of ytt. You can swap --help for any other command arguments.

Global installs with uv

Install the CLI globally when you want it always available on your PATH:

uv tool install --force --from git+https://github.com/dudarev/ytt.git ytt

The --force flag ensures you always get the latest version, even if the tool is already installed.

If you prefer to install from a local checkout (for example, after building release artifacts), run the following from inside the repository directory:

uv tool install --force --from . ytt

You can remove a global installation at any time with:

uv tool uninstall ytt

Develop from a local checkout

1. Clone the repository (or download the source code):

   git clone https://github.com/dudarev/ytt.git
   cd ytt

2. Sync the local uv environment with optional test dependencies:

   uv sync --python 3.12 --extra test

   This creates or updates the local .venv managed by uv. The [test] extra pulls in the tools required to run the local guardrails.

   Alternatively, you can use the provided Makefile helpers:

   make            # shows available commands
   make install-local       # syncs the local uv environment with test dependencies
   make install-global      # installs the current checkout globally (forced reinstall)
   make uninstall-global    # removes the globally installed ytt tool
   make lint                # runs ruff lint checks
   make fix                 # applies safe automated fixes
   make lint-fix            # applies safe ruff lint fixes
   make format              # formats Python code with ruff
   make test                # runs the test suite via pytest
   make package-smoke       # builds source and wheel distributions
   make check               # runs lint, tests, and package smoke checks

Local verification

Run the same default guardrails used by CI before opening a pull request:

make check

The target runs through uv run --python 3.12 --extra test, using the local uv-managed environment instead of whichever python is active in your shell. Override the version with make UV_PYTHON=3.13 check when needed. It runs ruff check ., the pytest suite, and a source/wheel build smoke check. Run make fix before make check to apply safe automated fixes first. Use make format when you want ruff to format Python files locally.

Usage

There are two main commands: config and fetch (which is the default).

1. Configure Preferred Languages (Required First Step)

Before fetching any transcripts, you must configure your preferred language codes. The tool will try these languages in the order you specify.

Run the config command:

ytt config languages <lang1>,<lang2>,...

Example: Set English, then Spanish, then French as preferred languages:

ytt config languages en,es,fr

This saves your preferences to a configuration file (e.g., ~/.config/ytt/config.json on Linux/macOS).

2. Fetch Transcript

Once languages are configured, run the tool providing the URL of the YouTube video. If you omit the URL entirely, YTT will try to read a YouTube link from your clipboard:

ytt "<youtube_url>"

(This implicitly uses the fetch command)

Tip: Always wrap the YouTube URL in quotes in your shell (this avoids issues with characters like &).

ytt  # Uses clipboard contents when no URL is supplied

Flag-only fetch invocations also fall back to clipboard when URL is omitted:

ytt fetch --refresh
ytt --refresh
ytt -l de-AT
ytt --language de-AT
ytt --refresh -l de-AT

By default, the tool will output the canonical video URL as the first line, followed by the video's title and description, and then the transcript, all formatted in Markdown. The output is also automatically copied to your clipboard.

Example:

ytt "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Output:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Video Title

## Description
Description text here...

## Transcript
[transcript lines]

The tool prioritizes manually created transcripts and will attempt your preferred languages in the given order. You can override language priority for a single fetch by passing -l/--language; if unavailable, YTT falls back to configured preferred languages. If successful, it will print the URL, title, description and the transcript text to standard output. Errors will be printed to standard error.

Controlling Output:

You can control the output with the following flags:

• --no-url: Suppress the video URL line.
• --no-title: Suppress the video title.
• --no-description: Suppress the video description.
• --no-metadata: Suppress the URL, title, and description.
• --refresh: Bypass local cache and fetch transcript/metadata from YouTube.
• -l, --language: Try this language first for this fetch only, then fall back to configured preferred languages.
• --no-copy: Do not copy the output to the clipboard.

Redirecting Output:

Even though the output is automatically copied to the clipboard, you can still redirect it to a file:

ytt "<youtube_url>" > transcript.md

Supported URL Formats

The tool attempts to extract the video ID from common YouTube URL formats, including:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• https://www.youtube.com/v/VIDEO_ID
• https://www.youtube.com/shorts/VIDEO_ID

License

MIT License