guitar_score/.planning/REQUIREMENTS.md

Requirements

Objective

Rebuild youtube_tab_to_pdf.py Computer Vision pipeline from the ground up to achieve 100% continuous measure extraction without skips or overwrites, primarily resolving the "discontinuous measure numbers" issue in YouTube guitar tabs.

Scenarios

• SCN-1: The Playhead Problem. Videos often contain a vertical red/blue bar tracking the current play position. This cursor moves across the screen and disrupts image matching.
• SCN-2: The Repeating Chorus Problem. In music, measure 50 might look identical to measure 10. The system must not confuse current frame context with a previous frame 40 measures ago and overwrite the timeline.
• SCN-3: Sub-optimal measure bars. Videos compress measure bar lines making them hard to detect accurately, so the system must rely on chronological time-shift tracking.

Acceptance Criteria

• test_pipeline.py passes for all 3 sample URLs showing no missing sections between start and end.
• Output panoramas/chunks are continuously ordered from start to finish without jumping back to an earlier identical part of the song.
• The moving playhead indicator is fully removed in the final PDF chunks.
• CV Logic is moved out of the main wrapper into a concise, easily testable video_cv_tracker.py.

Out of Scope

• Building a UI/Frontend.
• Changing yt-dlp download logic.
• Supporting arbitrary instruments (Piano/Drums) other than 6-string Guitar Tabs.