# 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):**
```bash
sudo apt update
sudo apt install ffmpeg
```

**macOS:**
```bash
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:
```cmd
build.bat
```

   Or manually:
```cmd
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:
```bash
chmod +x build.sh
```

2. Run the build script:
```bash
./build.sh
```

   Or manually:
```bash
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`:

```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.