lesson-highlights/README_BUILD.md

Piano Highlight Generator - Build Instructions

Prerequisites

1. Python

• Version: Python 3.10 or higher (3.12 recommended)
• Download: https://www.python.org/downloads/
• Note: Ensure Python is added to PATH

2. FFmpeg (Runtime Requirement)

FFmpeg is required for video processing at runtime, NOT for building.

Windows:

• Download from https://ffmpeg.org/download.html
• Or use: winget install ffmpeg
• Add FFmpeg binary location to system PATH

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

macOS:

brew install ffmpeg

3. Additional Build Tools (Windows)

• Visual Studio Build Tools or MinGW may be required for Nuitka compilation
• Download: https://visualstudio.microsoft.com/visual-cpp-build-tools/

---

Build Steps

Windows

1. Open Command Prompt or PowerShell in project directory

2. Run the build script:

build.bat

Or manually:

pip install nuitka pandas
python -m nuitka --standalone --onefile --windows-console-mode=disable --output-dir=dist --output-name=PianoHighlightGenerator --enable-plugin=pyside6 src/main.py

Linux/macOS

1. Make build script executable:

chmod +x build.sh

2. Run the build script:

./build.sh

Or manually:

pip3 install nuitka pandas
python3 -m nuitka --standalone --onefile --output-dir=dist --output-name=PianoHighlightGenerator --enable-plugin=pyside6 src/main.py

---

Output

Platform	Output Location	Filename
Windows	dist/	PianoHighlightGenerator.exe
Linux	dist/	PianoHighlightGenerator.bin
macOS	dist/	PianoHighlightGenerator.bin

---

Expected Size

• Standalone executable: ~150-250 MB
• This includes Python interpreter, PySide6, and all dependencies

---

Testing the Built Executable

1. Copy FFmpeg to the same directory as the executable OR ensure FFmpeg is in PATH

2. Run the executable:

   • Windows: Double-click PianoHighlightGenerator.exe or run from cmd
   • Linux/macOS: Run ./PianoHighlightGenerator.bin in terminal

3. Test basic functionality:

   • App should launch with GUI
   • Video selection should work
   • Processing pipeline should execute

---

Troubleshooting

"ffmpeg not found" error

• Ensure FFmpeg is installed and in system PATH
• Test by running ffmpeg -version in terminal

"Missing DLL" errors on Windows

• Install Visual C++ Redistributable: https://aka.ms/vs/17/release/vc_redist.x64.exe

Build fails with memory error

• Reduce parallelism: Add --jobs=2 to build command
• Close other applications

PySide6 plugin issues

• Ensure --enable-plugin=pyside6 is included
• For special PySide6 handling, add --pyside6-option=--no-sandbox

---

Data Files

If you have a prompts/ directory with template files, ensure:

• Path: src/core/prompts/
• Files are copied with --include-data-files=src/core/prompts=prompts

Currently, no prompts directory exists in the project. Create src/core/prompts/ if needed for custom prompt templates.

---

Nuitka Configuration (pyproject.toml)

The project includes Nuitka settings in pyproject.toml:

[tool.nuitka]
assume_yes_for_downloads = true
show_progress = true
output_dir = "dist"
output_name = "PianoHighlightGenerator"
python_version = "3.10"
standalone = true
onefile = true

You can also use the command line options documented above for more control.