yousum

YouTube subtitles -> Russian summary -> Q&A chat (via OpenRouter).

yousum is a config-first CLI. You put all runtime options in parameters.json, then run:

yousum "https://www.youtube.com/watch?v=VIDEO_ID"

Table Of Contents

• What It Does
• Features
• How It Works
• Requirements
• Install
• Configure
• Run
• Configuration Reference
• YouTube Cookies / Authentication
• Cache And Outputs
• Chat
• Environment Variables
• Troubleshooting
• Security
• Development
• License

What It Does

Given a YouTube URL, yousum:

1. Extracts subtitles (human-made preferred, auto-captions as fallback) using yt-dlp.
2. Normalizes subtitles into a plain transcript and caches it locally.
3. Generates a Russian summary with a configurable target word count using an LLM via OpenRouter.
4. Opens an interactive terminal chat for Q&A grounded in the transcript.

Features

• Subtitles extraction via yt-dlp
  • manual subtitles preferred, auto captions as fallback
  • formats supported: vtt, srt, ttml, srv1/2/3, json3
• Russian summary (word count configurable)
  • chunking + two-pass summarization for long transcripts
  • best-effort target word count
• Q&A chat grounded in subtitles
  • if the answer is not present in the transcript, the assistant should say so
  • chat commands: /summary, /exit
  • user input is color-highlighted in TTY terminals
• Caching
  • transcript cache: .yousum_cache/<video_id>/...
  • summaries: outputs/<video_id>/summary_ru_<words>.txt
• Minimal CLI
  • no long flag lists: configure once in parameters.json, then run yousum <url>

How It Works

1. yt-dlp extracts video metadata and subtitle tracks.
2. yousum picks a subtitle language from prefer_langs (default ru, then en), with source priority manual -> auto.
3. Subtitles are downloaded, parsed, and normalized into a single transcript.
4. The transcript is summarized via OpenRouter Chat Completions.
5. Chat mode retrieves a few relevant transcript chunks and asks the LLM to answer based on them.

Requirements

• Python 3.10+
• Internet access
• OpenRouter API key

Notes:

• YouTube frequently changes access rules. If yt-dlp reports bot checks or JS challenges, you may need cookies and/or a JavaScript runtime (see Troubleshooting).

Install

Recommended: create a virtual environment and install from this repo.

python -m venv .venv
./.venv/bin/python -m ensurepip --upgrade
./.venv/bin/python -m pip install -U pip
./.venv/bin/python -m pip install -r requirements.txt

Verify:

./.venv/bin/yousum --help
./.venv/bin/python -m yousum --help

Configure

1) OpenRouter API key (recommended: .env)

Keep your key out of shell history and do not share it publicly.

1. Copy .env.example to .env
2. Set your key:

OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

Keep .env private.

2) parameters.json (all runtime settings)

Edit parameters.json (or parametrers.json) in the project root.

Safe default example (no secrets):

{
  "model": "openrouter/free",
  "summary_words": 250,
  "temperature": 0.2,
  "prefer_langs": ["ru", "en"],
  "cache_dir": ".yousum_cache",
  "out_dir": "outputs",
  "refresh": false,
  "cookies": null,
  "cookies_from_browser": null
}

Tip: if you do not want to keep personal settings (cookies, custom paths) in the main parameters.json, create parameters.local.json and run with YOUSUM_PARAMETERS_FILE=parameters.local.json.

Run

Shortest (summary + chat):

./.venv/bin/yousum "https://www.youtube.com/watch?v=VIDEO_ID"

Same thing via python -m:

./.venv/bin/python -m yousum "https://www.youtube.com/watch?v=VIDEO_ID"

Explicit commands:

./.venv/bin/yousum summarize "https://www.youtube.com/watch?v=VIDEO_ID"
./.venv/bin/yousum chat "https://www.youtube.com/watch?v=VIDEO_ID"
./.venv/bin/yousum run "https://www.youtube.com/watch?v=VIDEO_ID"

Caching behavior:

• If a summary file already exists in outputs/ and refresh=false, summarize/chat will reuse it.
• Set "refresh": true in parameters.json to force re-download and regeneration.

Configuration Reference

parameters.json keys:

• model (string): OpenRouter model name, e.g. openrouter/free
• summary_words (int): target Russian summary word count (default 250)
• temperature (number): LLM temperature (0..2, default 0.2)
• prefer_langs (array of strings OR comma-separated string): preferred subtitle languages, e.g. ["ru","en"] or "ru,en"
• cache_dir (string): transcript cache dir (default .yousum_cache)
• out_dir (string): output dir for summaries (default outputs)
• refresh (bool): force re-download and regeneration (default false)
• cookies (string|null): path to cookies.txt (Netscape format) for YouTube auth
• cookies_from_browser (string|null): browser cookies loader (yt-dlp format)

Examples:

Use cookies from Brave profile:

{ "cookies_from_browser": "brave:Default" }

Use an explicit profile path (supports ~ and environment variables like $HOME):

{
  "cookies_from_browser": "brave:$HOME/.config/BraveSoftware/Brave-Browser/Default"
}

Use exported cookies file:

{ "cookies": "~/Downloads/cookies.txt" }

YouTube Cookies / Authentication

YouTube may block anonymous requests with messages like:

• Sign in to confirm you're not a bot

In that case, configure cookies.

Option A: cookies_from_browser (recommended if it works)

Supported browsers:

• brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale
• yandex (Linux, Chromium-based; supported via profile discovery under ~/.config/yandex-browser)

Format (same as yt-dlp): BROWSER[+KEYRING][:PROFILE][::CONTAINER]

Examples:

• "brave:Default"
• "chrome:Default"
• "edge:Default"
• "firefox:default"
• "opera" (Opera typically does not use profile names)
• "safari" (macOS)

Linux note:

• cookies_from_browser may require keyring access.
• The project includes secretstorage on Linux, but your desktop session still needs a working keyring.
• If keyring access is unavailable (headless/sandboxed), use exported cookies.txt instead.

Option B: exported cookies.txt

Export YouTube cookies to Netscape format and point cookies to the file.

Treat exported cookies as secrets and do not share them publicly.

Cache And Outputs

Default layout:

• .yousum_cache/<video_id>/
  • transcript.txt (normalized text)
  • meta.json (metadata)
  • raw subtitle file (e.g. *.vtt)
• outputs/<video_id>/summary_ru_<words>.txt

Cleanup:

rm -rf .yousum_cache outputs

Chat

The chat starts automatically in run mode.

Commands:

• /summary print the saved summary
• /exit exit

Chat policy:

• answers should be based on subtitles context only
• if it is not mentioned in the transcript, the assistant should say so

Environment Variables

• OPENROUTER_API_KEY (required)
• OPENROUTER_BASE_URL (optional, default https://openrouter.ai/api/v1)
• OPENROUTER_APP_NAME (optional, sent as X-Title)
• OPENROUTER_REFERRER (optional, sent as HTTP-Referer)
• YOUSUM_PARAMETERS_FILE (optional, path to an alternative parameters JSON)

Troubleshooting

Missing OpenRouter API key

Error:

• Missing OpenRouter API key

Fix:

• set OPENROUTER_API_KEY via .env (recommended), or export OPENROUTER_API_KEY="..."

YouTube bot check

Error:

• Sign in to confirm you're not a bot

Fix:

• configure cookies_from_browser or cookies in parameters.json

Cookies database not found

Error:

• could not find <browser> cookies database ...

Fix:

1. Ensure the browser/profile exists.
2. In sandboxed terminals (Flatpak/Snap), set an explicit profile path, e.g.:

{ "cookies_from_browser": "brave:$HOME/.config/BraveSoftware/Brave-Browser/Default" }

3. If it still fails, use exported cookies.txt.

Keyring / secretstorage issues

Symptoms:

• secretstorage not available
• cookies cannot be decrypted

Fix:

• ensure secretstorage is installed in your venv
• ensure you have a working desktop keyring session
• otherwise use exported cookies.txt

No subtitles found

Error:

• No subtitles found (manual or auto)

Fix:

• try another language in prefer_langs
• some videos have no subtitles at all
• if extraction is failing due to YouTube restrictions, use cookies

yt-dlp warnings about JS challenges (EJS) / formats missing

Symptoms:

• warnings mentioning EJS
• Requested format is not available (even though you only need subtitles)

Notes:

• yousum sets ignore_no_formats_error to keep working when only subtitles are available.

Fixes to try:

• update yt-dlp: ./.venv/bin/python -m pip install -U yt-dlp
• install a supported JS runtime (node or deno) and follow yt-dlp EJS docs
• use cookies (often enough)

Security

Do not publish/share:

• .env (OpenRouter key)
• cookies*.txt (exported cookies)
• .venv/, .yousum_cache/, outputs/

Secret scan before sharing:

rg -n --hidden \
  --glob '!.venv/**' \
  --glob '!.yousum_cache/**' \
  --glob '!outputs/**' \
  -- "OPENROUTER_API_KEY=|cookies(\\.txt)?|BEGIN (RSA|OPENSSH) PRIVATE KEY" .

If you accidentally leaked a key/cookies: revoke/rotate them immediately.

Development

Install with dev extras:

./.venv/bin/python -m pip install -e ".[dev]"

Run tests:

./.venv/bin/python -m pytest -q

License

MIT. See LICENSE.