youtube-cli

Lightweight CLI for two fast workflows built on top of yt-dlp:

• search YouTube with the native YouTube search engine and return the top K results;
• extract a clean transcript from a video's subtitles or automatic captions.

The project uses the Python standard library only and calls yt-dlp through subprocesses to stay simple and fast.

Requirements

• Python 3.11+
• yt-dlp available on PATH

Installation

python3 -m pip install -e .

On macOS/Homebrew, the system pip may be blocked by PEP 668. The recommended development setup is:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Once the environment is activated, youtube-cli is available from any directory, not only from the project root.

If you want a globally available command without activating a virtual environment:

brew install pipx
pipx install --editable /Users/mohamed/Documents/indé/portfolio/youtube-cli

Usage

Fast search for the first 5 results:

youtube-cli search "python tutorial" -k 5

JSON output:

youtube-cli search "python tutorial" -k 5 --format json

Search with richer metadata, but slower:

youtube-cli search "python tutorial" -k 5 --full-metadata

Transcript from a video ID:

youtube-cli transcript K5KVEU3aaeQ

Transcript with a preferred language:

youtube-cli transcript K5KVEU3aaeQ --lang en-orig
youtube-cli transcript K5KVEU3aaeQ --lang fr

By default, the output removes common speech fillers such as um, uh, and erm. If you want to keep a more literal transcript:

youtube-cli transcript K5KVEU3aaeQ --keep-fillers

Transcript as JSON:

youtube-cli transcript K5KVEU3aaeQ --format json

Without an editable install, you can also run the CLI directly from the repository root:

PYTHONPATH=src python3 -m youtube_cli search "python tutorial" -k 5
PYTHONPATH=src python3 -m youtube_cli transcript K5KVEU3aaeQ

Implementation Notes

• search uses ytsearchK: and --flat-playlist by default to minimize latency.
• transcript first reads the video JSON to choose a single subtitle language, then downloads only the targeted .vtt file.
• Cleaning removes VTT/HTML tags, simple non-speech blocks such as [Music], common speech fillers such as um and uh, and repeated fragments caused by auto-generated captions.

Development

Run the tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Performance measurements and latency budget:

• docs/performance-spec.md

Real output examples:

• docs/example/README.md