Initial commit: lesson-highlights generator

2026-05-03 03:07:22 +08:00
commit 9e62247a60
55 changed files with 6189 additions and 0 deletions
@@ -0,0 +1,148 @@
+# 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.