yt-tabs

Description

yt-tabs is a command-line tool that extracts guitar sheet/tab images from YouTube videos and optionally compiles them into a PDF.
The pipeline is:

1. Download the video.
2. Extract frames with FFmpeg.
3. Detect sheet/tab regions from frames.
4. Save sheet images and/or generate a PDF.

The project also includes a cache management CLI so you can inspect and clean generated artifacts (videos, frames, sheets, and PDFs).

Documentation

1) Installation

Prerequisites

• Python 3.10+ (recommended)
• FFmpeg available in your system PATH

Install dependencies

pip install -r requirements.txt

Install the project in editable mode

pip install -e .

After installation, the CLI command is available as:

yt-tabs --help

---

2) Usage

Main command

yt-tabs extract <youtube_url> [OPTIONS]

Common examples

Generate a PDF:

yt-tabs extract "https://www.youtube.com/watch?v=<id>" --out-pdf output.pdf

Save detected sheets as images (without generating PDF):

yt-tabs extract "https://www.youtube.com/watch?v=<id>" --save-sheets

Reuse previously cached sheets when generating PDF:

yt-tabs extract "https://www.youtube.com/watch?v=<id>" --use-sheets-cache --out-pdf output.pdf

Use debug logging:

yt-tabs --verbose extract "https://www.youtube.com/watch?v=<id>" --out-pdf output.pdf

Cache management

List cache entries:

yt-tabs cache list

Show cache size:

yt-tabs cache size

Clear all cache data:

yt-tabs cache clear

Purge specific artifact types:

yt-tabs cache purge-videos [VIDEO_ID]
yt-tabs cache purge-frames [VIDEO_ID]
yt-tabs cache purge-sheets [VIDEO_ID]
yt-tabs cache purge-pdfs [VIDEO_ID]

---

3) Configuration

You can configure extraction behavior in three ways:

1. Default config (built-in values)
2. Profile-based config (--profile)
3. Explicit overrides via CLI flags

Profile presets

Available profiles:

• extra_safe
• safe
• aggressive

Example:

yt-tabs extract "https://www.youtube.com/watch?v=<id>" --profile safe --out-pdf output.pdf

Config file

You can load a simple key-value config file with --config-file.

Example file:

fps=1
qscale=3
frame_diff_threshold=0.025
sheet_intensity_threshold=200
staff_pattern_match_thresh=0.8

Usage:

yt-tabs extract "https://www.youtube.com/watch?v=<id>" --config-file ./config.ini --out-pdf output.pdf

Note: keys can be written with underscores (e.g. frame_diff_threshold).

---

4) Customization

All runtime parameters from the Config dataclass are exposed as CLI flags in yt-tabs extract.
You can inspect all options with:

yt-tabs extract --help

Important customization flags include:

• --cache-path: cache directory
• --video-download-path: where downloaded videos are stored
• --fps, --qscale: frame extraction parameters
• --sheet-intensity-threshold: sheet detection sensitivity
• --frame-diff-threshold: frame difference threshold
• --initial-frame-offset, --intersheet-discards: frame selection tuning
• --pixel-avg-window-size: sheet Y-position estimation window
• --staff-pattern-width, --staff-line-thickness, --staff-space-to-line-ratio, --staff-lines: staff pattern geometry
• --staff-min-scale-percent, --staff-max-scale-percent: template matching scale range
• --staff-pattern-match-thresh: staff matching confidence threshold
• --sheet-area-ratio: minimum sheet area ratio in frame

Example with custom detection tuning:

yt-tabs extract "https://www.youtube.com/watch?v=<id>" \
  --fps 2 \
  --frame-diff-threshold 0.02 \
  --sheet-intensity-threshold 190 \
  --staff-line-thickness 1 \
  --out-pdf tuned-output.pdf

Results

This is a sample from the result of the latest stages of the extraction pipeline. You can check the full breakdown of the pipeline here

Sheet extraction pipeline result

Development

Run tests with coverage:

pytest --cov=src --cov-report=term-missing --cov-report=html