Run the application

yt-summarizer supports two storage modes:

Run without Notion

Provide a playlist URL to populate a local bundle:

yt_summarizer \
  --playlist-url "https://www.youtube.com/playlist?list=PLAYLIST_ID" \
  --model "ollama/llama3.2" \
  --api-base "http://localhost:11434" \
  --workers 4

Use --output-dir to write somewhere other than docs/:

yt_summarizer \
  --playlist-url "https://www.youtube.com/playlist?list=PLAYLIST_ID" \
  --output-dir "knowledge" \
  --model "ollama/llama3.2"

--output-dir selects filesystem mode even if NOTION_DATABASE_ID is set in the environment. To use a GitHub collection such as yt-conferences, check it out locally and pass its directory as --output-dir.

Run with Notion

The application reads a Notion token from /etc/notion/secrets.txt by default. For local testing, put configuration in a .env file in the directory where you run yt_summarizer:

NOTION_TOKEN=your-notion-token-here
NOTION_DATABASE_ID=your-database-id
LLM_MODEL=ollama/llama3.2
LLM_API_BASE=http://localhost:11434

Then run the CLI with no credential or model flags:

yt_summarizer

The CLI loads .env automatically. Variables already exported in the shell take precedence over .env, and command-line options take precedence over both. The repository ignores .env files; do not commit credentials.

Alternatively, you can:

  1. Create the token file (recommended for production):
echo "your-notion-token-here" > /etc/notion/secrets.txt
chmod 600 /etc/notion/secrets.txt
  1. Or use environment variable (for quick testing):
export NOTION_TOKEN="your-notion-token-here"

Then execute the CLI with your Notion database ID:

yt_summarizer --notion-db-id "your-database-id" --model "ollama/llama3.2" --api-base "http://localhost:11434"

Or specify a custom token file location:

yt_summarizer --notion-db-id "your-database-id" --notion-token-file "/path/to/token/file"

You can combine Notion input with a playlist. Existing URLs are skipped, and new playlist videos are added to the current processing queue:

yt_summarizer \
  --notion-db-id "your-database-id" \
  --playlist-url "https://www.youtube.com/playlist?list=PLAYLIST_ID" \
  --model "ollama/llama3.2"

Configuration options

During video processing, the CLI displays an overall progress bar and a bar for each worker, showing completed/assigned videos, percentage, and remaining videos. Videos are assigned to worker queues in round-robin order. Each bar advances after a video has finished processing and storage. The executive summary starts after all videos finish and has a separate spinner.

In an interactive terminal, the bars update in place. Redirected output records progress snapshots without terminal cursor-control sequences.

If you use Ollama locally, make sure the service is running before starting the CLI. When the configured LLM endpoint cannot be reached, the CLI now exits with a specific connection error that includes the failing --api-base and model values.

Environment Variables

Name Default Description
NOTION_TOKEN   Notion API token - overrides token file (optional)
NOTION_TOKEN_FILE /etc/notion/secrets.txt Path to file containing Notion API token
NOTION_DATABASE_ID   Optional Notion database ID
LLM_MODEL ollama/llama3.2 LLM model identifier for analysis
LLM_API_BASE http://localhost:11434 Base URL for the LLM API endpoint
OUTPUT_DIR   OKF bundle root
WORKERS CPU core count Number of videos to process concurrently
PROXY_USERNAME   Optional Webshare proxy username
PROXY_PASSWORD   Optional Webshare proxy password

NOTION_TOKEN takes precedence over NOTION_TOKEN_FILE when both are set. For models whose name starts with github_copilot/, the application uses the provider default endpoint unless --api-base is explicitly supplied.

Notion database schema

The database must expose a URL property named URL. The application reads these properties when present:

When writing to Notion, the application updates Title, URL, Summary, and Main Points. Records without a URL are skipped.

Run in Docker

When running with Docker, mount the secrets file:

docker run -v /path/to/secrets.txt:/etc/notion/secrets.txt \
  -e NOTION_DATABASE_ID="your-database-id" \
  yt-summarizer:latest

Or pass the token via environment variable:

docker run \
  -e NOTION_TOKEN="your-notion-token-here" \
  -e NOTION_DATABASE_ID="your-database-id" \
  yt-summarizer:latest

Run the tests

To run the test suite, use the make test command. This will clean up any build artifacts, ensure the required dependencies are installed, and execute the tests using tox.

make test

Ensure that you have the necessary tools installed, such as uvx, which will be automatically installed if missing.

Troubleshoot common problems

Common Issues