4e1ac9b7ea
Mirrors the Macros reader: LabelsFileReader -> LabelLibrary -> Label wraps the protobuf ProLabelsDocument and exposes each label's name (the proto 'text' field) plus optional RGBA color with a #RRGGBB hex helper. Includes CLI tool, PHPUnit suite against the bundled reference Labels sample, and api/labels.md docs.
75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
# ProPresenter Parser — Agent Instructions
|
|
|
|
## Documentation
|
|
|
|
All project documentation lives in `doc/`. Load only what you need.
|
|
|
|
**Start here:** Read `doc/INDEX.md` for the table of contents and quick navigation.
|
|
|
|
### How to Find What You Need
|
|
|
|
1. Check `doc/INDEX.md` for the topic overview
|
|
2. Use `doc/keywords.md` to search by keyword
|
|
3. Load the specific doc file — don't load everything
|
|
|
|
### Common Tasks
|
|
|
|
| Task | Load |
|
|
|------|------|
|
|
| Parse/modify `.pro` song files | `doc/api/song.md` |
|
|
| Parse/modify `.proplaylist` files | `doc/api/playlist.md` |
|
|
| Parse/modify `.probundle` files | `doc/api/bundle.md` |
|
|
| Read the global `Macros` file | `doc/api/macros.md` |
|
|
| Read the global `Labels` file | `doc/api/labels.md` |
|
|
| Understand `.pro` binary format | `doc/formats/pp_song_spec.md` |
|
|
| Understand `.proplaylist` binary format | `doc/formats/pp_playlist_spec.md` |
|
|
| Understand `.probundle` binary format | `doc/formats/pp_bundle_spec.md` |
|
|
| Debug or troubleshoot | `doc/internal/issues.md` |
|
|
| Add new documentation | `doc/CONTRIBUTING.md` |
|
|
|
|
### Structure
|
|
|
|
```
|
|
doc/
|
|
├── INDEX.md ← Start here (TOC + navigation)
|
|
├── keywords.md ← Keyword search index
|
|
├── CONTRIBUTING.md ← How to document new things
|
|
├── formats/ ← Binary file format specs
|
|
│ ├── pp_song_spec.md
|
|
│ ├── pp_playlist_spec.md
|
|
│ └── pp_bundle_spec.md
|
|
├── api/ ← PHP API docs (read/write/generate)
|
|
│ ├── song.md
|
|
│ ├── playlist.md
|
|
│ ├── bundle.md
|
|
│ ├── macros.md
|
|
│ └── labels.md
|
|
└── internal/ ← Dev notes (learnings, decisions, issues)
|
|
├── learnings.md
|
|
├── decisions.md
|
|
└── issues.md
|
|
```
|
|
|
|
## Project Overview
|
|
|
|
PHP tools for parsing, modifying, and generating ProPresenter 7 files:
|
|
|
|
- **Songs** (`.pro`) — Protobuf-encoded presentation files with lyrics, groups, slides, arrangements, translations
|
|
- **Playlists** (`.proplaylist`) — ZIP64 archives containing playlist metadata and embedded songs
|
|
- **Bundles** (`.probundle`) — ZIP archives containing a single presentation with embedded media assets
|
|
- **Macros** (`Macros`, no extension) — Global protobuf-encoded macro library with collections
|
|
- **Labels** (`Labels`, no extension) — Global protobuf-encoded label library (slide labels with optional UI colors)
|
|
|
|
### CLI Tools
|
|
|
|
```bash
|
|
php bin/parse-song.php path/to/song.pro
|
|
php bin/parse-playlist.php path/to/playlist.proplaylist
|
|
php bin/parse-macros.php path/to/Macros
|
|
php bin/parse-labels.php path/to/Labels
|
|
```
|
|
|
|
### Key Source Files
|
|
|
|
All PHP source code is in `src/`. Generated protobuf classes are in `generated/`. Tests are in `tests/`.
|