Extract → Select → Reconstruct → Cut → Preview → Export
ScoreHack is a Windows-focused desktop application for turning sheet music displayed in YouTube videos or local video files into clean, printable PDF pages.
It is designed for videos where the score moves across the screen as the music progresses. The application keeps the important visual decisions in the user's hands: frame selection, overlap, page cuts, and final A4 composition.
Many sheet-music videos do not contain independent pages. Instead, the viewer sees a moving viewport over one long score.
ScoreHack turns that into a controlled reconstruction workflow:
Video
↓
Frame extraction
↓
Crop the score area
↓
Select useful frames
↓
Reconstruct horizontally
↓
Adjust frame-to-frame joins
↓
Place page cuts
↓
Preview the A4 document
↓
Export PDF
The result is a raster-based PDF intended for printing or archiving.
| Capability | Description |
|---|---|
| YouTube input | Download a source video through yt-dlp |
| Local video | Open common video formats directly |
| Frame extraction | Sample the video at a configurable interval |
| Cropping | Control top and bottom crop independently |
| Frame selection | Build the reconstruction manually and in order |
| Reconstruction | Join frames horizontally into one score |
| Join control | Adjust every frame pair independently |
| Auto alignment | Use automatic overlap estimation as a starting point |
| Page cuts | Add and drag manual page boundaries |
| A4 output | Compose the final document on a fixed A4 canvas |
| Preview | Review the document before final export |
| Windows workflow | Run the application directly on Windows |
Run:
run.bat
The launcher creates or reuses the virtual environment, installs missing dependencies, and starts ScoreHack.
For developers who prefer to run the project manually:
python -m venv venv
venv\Scripts\activate
python -m pip install -r requirements.txt
python -m app.main
At the top of the application you will find the source selector.
- Select YouTube.
- Paste the video URL.
- Click Analyze video.
- Wait until the frames are extracted.
- Select Local video.
- Click Browse, or drag the video into the drop area.
- Confirm that the filename is displayed.
- Click Analyze video.
Supported local containers include common formats such as MP4, MKV, AVI, MOV, WEBM, and M4V.
The Frame interval determines how often ScoreHack samples the video.
Examples:
0.5 sec → more frames
1.0 sec → balanced starting point
2.0 sec → fewer frames
Use a smaller interval when the score moves quickly or when each frame contains only a small amount of new information.
Use a larger interval when the score changes slowly and you want fewer frames to review.
The Crop section has two independent controls:
- Top — removes pixels from the top.
- Bottom — removes pixels from the bottom.
Use them to remove video controls, borders, empty space, or other material that is not part of the score.
The objective is to leave only the useful sheet-music area.
┌──────────────────────────────────────┐
│ SHEET MUSIC │
│ │
│ musical notation and score │
│ │
└──────────────────────────────────────┘
These crop values are applied when the selected frames are processed.
Use the frame slider in the main workspace to move through the extracted frames.
Look for frames that:
- contain a useful portion of the score,
- overlap with the previous portion,
- continue the score in the correct direction,
- do not contain unnecessary transitions or unrelated video content.
This is where you decide which frames should form the final reconstruction.
For videos where the score moves sideways, open Mode and choose:
Horizontal join
The reconstruction workspace becomes available.
This mode is intended for a moving viewport over a longer score, rather than independent complete pages.
Find the first useful frame and click:
Add frame
Move to the next useful frame and add it.
Continue in the order in which the score should appear.
Example:
Frame 12
↓
Frame 18
↓
Frame 25
↓
Frame 31
↓
Frame 39
The selected frames appear in the frame strip.
Selection order matters. The reconstruction follows the order you selected.
Every adjacent frame pair has its own join.
For example:
Frame 12 → Frame 18 Join 1
Frame 18 → Frame 25 Join 2
Frame 25 → Frame 31 Join 3
Frame 31 → Frame 39 Join 4
Each join has a separate overlap value.
Join 1 → 120 px
Join 2 → 185 px
Join 3 → 96 px
Join 4 → 160 px
This is important because the correct overlap can change from one frame pair to another.
ScoreHack can estimate the overlap automatically.
Treat that value as a suggestion. Repeated musical notation and similar visual patterns can make image matching ambiguous.
Use the slider belonging to the specific join that looks incorrect.
Each join is independent, so correcting Join 3 does not alter Join 1, Join 2, or Join 4.
The join list keeps its scroll position while you edit long sequences.
The reconstruction preview shows the selected frames as one continuous score.
Scroll horizontally and inspect the entire result.
Look for:
- duplicated notes,
- doubled clefs,
- visible seams,
- incorrect overlaps,
- missing portions,
- frames that should be removed.
Correct the individual joins until the continuous score looks right.
Do not move to page layout until the reconstruction itself is correct.
Once the reconstruction is correct, decide where the long score should be divided into printable systems.
Click:
Add cut here
A cut marker is added to the reconstruction.
You can drag the marker directly over the score.
──────────────────────────────────────────────────────────────
│ │
Cut 1 Cut 2
│ │
──────────────────────────────────────────────────────────────
You can also edit cut positions numerically in the Score layout section.
ScoreHack does not try to guess the musical meaning of every system. You decide where each printable section should begin and end.
This makes the final result predictable.
In Score layout, choose the number of reconstructed segments per page.
For example:
1 system / page
2 systems / page
3 systems / page
4 systems / page
The final document uses a fixed A4 canvas.
Score systems keep their proportions and are scaled together when necessary.
Click:
Preview
Preview uses the current:
- selected frames,
- crop,
- join overlaps,
- page cuts,
- page distribution,
- A4 layout.
A typical iteration is:
Adjust
↓
Preview
↓
Inspect
↓
Adjust again
↓
Preview again
Repeat until the composition looks correct.
When the preview looks correct:
- Click Generate PDF.
- Select the destination.
- Save the document.
The exported PDF uses the same reconstruction and layout settings that you reviewed in Preview.
For the most reliable results:
- Analyze the video.
- Set the crop.
- Inspect the frame timeline.
- Switch to Horizontal join.
- Select only useful frames.
- Correct every join.
- Inspect the complete reconstruction.
- Add page cuts.
- Select systems per A4 page.
- Preview.
- Fine-tune.
- Generate the final PDF.
app/
├── core/
│ ├── crop.py
│ ├── deduplicator.py
│ ├── downloader.py
│ ├── frame_extractor.py
│ ├── layout.py
│ ├── models.py
│ ├── pdf_exporter.py
│ ├── pipeline.py
│ ├── stitcher.py
│ └── workspace.py
│
├── ui/
│ ├── controller.py
│ ├── launcher.py
│ └── qml/
│ ├── Main.qml
│ └── components/
│
└── main.py
tests/
├── test_core.py
└── test_stitcher.py
The processing core is independent from the QML presentation layer.
- Python 3.10+
- Windows is the primary packaged target
- Internet access is required only for YouTube downloads
run.bat
python -m pytest -q
GitHub Actions runs the automated test suite on Python 3.10 and 3.12.
Automatic processing assists the workflow but does not make irreversible visual decisions for the user.
Every selected frame and every overlap remains visible and editable.
The user decides where the score is divided into systems and how those systems are distributed across A4 pages.
Preview and final PDF generation use the same current layout configuration.
- ScoreHack extracts sheet music as raster images.
- It does not recognize notes, chords, lyrics, or musical symbols.
- It does not generate MusicXML or MIDI.
- Automatic overlap detection is an assistive estimate and may require manual correction.
- Final quality depends on the source video's resolution, compression, and clarity.
Only process and download video content you are authorized to use.
YouTube content remains subject to the rights of its owners and to YouTube's applicable terms and policies.
Version 3.0.0
See CHANGELOG.md for release notes.
Released under the MIT License.
ScoreHack
Qt 6 · QML · Python · OpenCV