9e3e719806
Add full IO support for every global ProPresenter library file plus theme folders, and extend the existing Labels/Macros readers with exporters and editable accessors so every supported document is now a round-trippable, mutable object. New library readers/writers (each: FileReader, FileWriter, Library wrapper, element wrapper where applicable, CLI tool, tests, doc/api/*.md): - Groups (ProGroupsDocument) + GroupDefinition - ClearGroups (ClearGroupsDocument) + ClearGroupDefinition - CCLI (CCLIDocument) - Messages (MessageDocument) + Message - Timers (TimersDocument + Clock) + Timer - Stage (Stage.Document) + StageLayout - Workspace (ProPresenterWorkspace) + Screen - Props (PropDocument) + Prop - TestPatterns (TestPatternDocument) - Calendar (new CalendarDocument) + CalendarEvent - KeyMappings (new KeyMappingsDocument) + KeyMapping - CommunicationDevices (JSON file) + CommunicationDevice - Theme bundles (Template.Document folder + Assets/) + ThemeBundle/Slide/Asset Extensions to existing modules: - LabelsFileWriter; Label and LabelLibrary gain setters, addLabel, removeLabel, setColor / setColorHex helpers - MacrosFileWriter; Macro/MacroCollection/MacroLibrary gain UUID, name, color, image_type, image_data, trigger_on_startup setters plus add/remove for macros and collections Two new minimal proto schemas were defined for documents that lacked upstream definitions: - proto/calendar.proto - CalendarDocument with Event entries, raw bytes for the action/macro sub-messages so the schema can evolve - proto/keyMappings.proto - KeyMappingsDocument with ApplicationInfo and a forward-looking Mapping message (sample only carries the info) The Theme file turned out to be a regular Rv\Data\Template\Document, so no new proto was required for theme content; ThemeBundle layers folder + Assets/ handling on top in the same spirit as PresentationBundle. GroupDefinition is intentionally distinct from the existing Group class (which wraps song-level CueGroup) to avoid breaking song APIs. Verified with the full PHPUnit suite: 370 tests, 9200 assertions, all green; LSP diagnostics clean across src/. The unmodified reference samples for Labels, Groups, ClearGroups, TestPatterns, Calendar and KeyMappings round-trip byte-for-byte; the others round-trip with the same byte length (PHP protobuf is not canonically deterministic but re-write-after-write stabilises). doc/INDEX.md, doc/keywords.md and AGENTS.md updated so every new module is discoverable from the top level.
230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# ProPresenter Parser Documentation
|
|
|
|
> **For AI Agents**: Load only the documents you need. Use the keyword index to find relevant sections.
|
|
|
|
## Quick Navigation
|
|
|
|
| Need | Load |
|
|
|------|------|
|
|
| Parse/modify `.pro` song files | [api/song.md](api/song.md) |
|
|
| Parse/modify `.proplaylist` files | [api/playlist.md](api/playlist.md) |
|
|
| Parse/modify `.probundle` files | [api/bundle.md](api/bundle.md) |
|
|
| Read/write the global `Macros` file | [api/macros.md](api/macros.md) |
|
|
| Read/write the global `Labels` file | [api/labels.md](api/labels.md) |
|
|
| Read/write the global `Groups` file | [api/groups.md](api/groups.md) |
|
|
| Read/write the global `ClearGroups` file | [api/clear-groups.md](api/clear-groups.md) |
|
|
| Read/write the global `CCLI` file | [api/ccli.md](api/ccli.md) |
|
|
| Read/write the global `Messages` file | [api/messages.md](api/messages.md) |
|
|
| Read/write the global `Timers` file | [api/timers.md](api/timers.md) |
|
|
| Read/write the global `Stage` file | [api/stage.md](api/stage.md) |
|
|
| Read/write the global `Workspace` file | [api/workspace.md](api/workspace.md) |
|
|
| Read/write the global `Props` file | [api/props.md](api/props.md) |
|
|
| Read/write the global `TestPatterns` file | [api/test-patterns.md](api/test-patterns.md) |
|
|
| Read/write the global `Calendar` file | [api/calendar.md](api/calendar.md) |
|
|
| Read/write the global `KeyMappings` file | [api/key-mappings.md](api/key-mappings.md) |
|
|
| Read/write the global `CommunicationDevices` JSON file | [api/communication-devices.md](api/communication-devices.md) |
|
|
| Read/write theme folders (Theme + Assets/) | [api/theme.md](api/theme.md) |
|
|
| Understand `.pro` binary format | [formats/pp_song_spec.md](formats/pp_song_spec.md) |
|
|
| Understand `.proplaylist` format | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) |
|
|
| Understand `.probundle` format | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
|
|
| Add new documentation | [CONTRIBUTING.md](CONTRIBUTING.md) |
|
|
| Search by keyword | [keywords.md](keywords.md) |
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
### File Format Specifications
|
|
- [formats/pp_song_spec.md](formats/pp_song_spec.md) — ProPresenter 7 `.pro` file format (protobuf structure, RTF handling, field reference)
|
|
- [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) — ProPresenter 7 `.proplaylist` file format (ZIP64 container, item types)
|
|
- [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) — ProPresenter 7 `.probundle` file format (ZIP container, media assets)
|
|
|
|
### PHP API Documentation
|
|
#### Document containers
|
|
- [api/song.md](api/song.md) — Song parser API (read, modify, generate `.pro` files)
|
|
- [api/playlist.md](api/playlist.md) — Playlist parser API (read, modify, generate `.proplaylist` files)
|
|
- [api/bundle.md](api/bundle.md) — Bundle parser API (read, write `.probundle` files with media)
|
|
- [api/theme.md](api/theme.md) — Theme bundle API (folder with `Theme` proto + `Assets/`)
|
|
|
|
#### Global library files (read + write)
|
|
- [api/macros.md](api/macros.md) — `Macros` library (macros + collections, with editable accessors)
|
|
- [api/labels.md](api/labels.md) — `Labels` library (named slide labels with optional UI colors)
|
|
- [api/groups.md](api/groups.md) — `Groups` library (named library groups with UUID, color, hot keys)
|
|
- [api/clear-groups.md](api/clear-groups.md) — `ClearGroups` library (clear-action groups)
|
|
- [api/ccli.md](api/ccli.md) — `CCLI` settings (license, display behaviour, copyright template)
|
|
- [api/messages.md](api/messages.md) — `Messages` library (lower-third / overlay messages)
|
|
- [api/timers.md](api/timers.md) — `Timers` library (timer definitions + clock format)
|
|
- [api/stage.md](api/stage.md) — `Stage` document (stage display layouts)
|
|
- [api/workspace.md](api/workspace.md) — `Workspace` document (screens, looks, masks, audio/video inputs)
|
|
- [api/props.md](api/props.md) — `Props` document (prop cues + transition)
|
|
- [api/test-patterns.md](api/test-patterns.md) — `TestPatterns` document (currently selected pattern + saved overrides)
|
|
- [api/calendar.md](api/calendar.md) — `Calendar` document (scheduled events firing macros)
|
|
- [api/key-mappings.md](api/key-mappings.md) — `KeyMappings` document (custom hot-key bindings)
|
|
- [api/communication-devices.md](api/communication-devices.md) — `CommunicationDevices` JSON list (MIDI / serial / OSC bindings)
|
|
|
|
### Internal Reference
|
|
- [internal/learnings.md](internal/learnings.md) — Development learnings and conventions discovered
|
|
- [internal/decisions.md](internal/decisions.md) — Architectural decisions and rationale
|
|
- [internal/issues.md](internal/issues.md) — Known issues and edge cases
|
|
|
|
### Meta
|
|
- [keywords.md](keywords.md) — Searchable keyword index
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to document new features
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
doc/
|
|
├── INDEX.md ← You are here (main entry point)
|
|
├── keywords.md ← Keyword search index
|
|
├── CONTRIBUTING.md ← Documentation guidelines
|
|
├── formats/ ← File format specifications
|
|
│ ├── pp_song_spec.md
|
|
│ ├── pp_playlist_spec.md
|
|
│ └── pp_bundle_spec.md
|
|
├── api/ ← PHP API documentation
|
|
│ ├── song.md
|
|
│ ├── playlist.md
|
|
│ ├── bundle.md
|
|
│ ├── theme.md
|
|
│ ├── macros.md
|
|
│ ├── labels.md
|
|
│ ├── groups.md
|
|
│ ├── clear-groups.md
|
|
│ ├── ccli.md
|
|
│ ├── messages.md
|
|
│ ├── timers.md
|
|
│ ├── stage.md
|
|
│ ├── workspace.md
|
|
│ ├── props.md
|
|
│ ├── test-patterns.md
|
|
│ ├── calendar.md
|
|
│ ├── key-mappings.md
|
|
│ └── communication-devices.md
|
|
└── internal/ ← Development notes (optional context)
|
|
├── learnings.md
|
|
├── decisions.md
|
|
└── issues.md
|
|
```
|
|
|
|
---
|
|
|
|
## When to Load What
|
|
|
|
### Task: "Parse a song file"
|
|
```
|
|
Load: doc/api/song.md
|
|
```
|
|
|
|
### Task: "Generate a new playlist"
|
|
```
|
|
Load: doc/api/playlist.md
|
|
```
|
|
|
|
### Task: "Read/write a .probundle"
|
|
```
|
|
Load: doc/api/bundle.md
|
|
```
|
|
|
|
### Task: "Edit a global library file (Macros, Labels, Groups, etc.)"
|
|
```
|
|
Load: doc/api/<library>.md
|
|
```
|
|
|
|
### Task: "Round-trip a Theme folder with assets"
|
|
```
|
|
Load: doc/api/theme.md
|
|
Load: doc/api/bundle.md (for the bundle pattern reference)
|
|
```
|
|
|
|
### Task: "Debug protobuf parsing issues"
|
|
```
|
|
Load: doc/formats/pp_song_spec.md (sections 2-5)
|
|
```
|
|
|
|
### Task: "Understand translation handling"
|
|
```
|
|
Load: doc/api/song.md (section: Translations)
|
|
Load: doc/formats/pp_song_spec.md (section 7: Translations)
|
|
```
|
|
|
|
### Task: "Fix ZIP64 issues"
|
|
```
|
|
Load: doc/formats/pp_playlist_spec.md (section 4: ZIP64 Container Format)
|
|
Load: doc/formats/pp_bundle_spec.md (section 4: ZIP64 EOCD Quirk)
|
|
Load: doc/internal/learnings.md (search: Zip64Fixer)
|
|
```
|
|
|
|
---
|
|
|
|
## Project Overview
|
|
|
|
This project provides PHP tools to parse, modify, and generate ProPresenter 7 files:
|
|
|
|
- **Songs** (`.pro`) — Presentation files containing lyrics with groups, slides, arrangements, and translations
|
|
- **Playlists** (`.proplaylist`) — ZIP archives containing playlist metadata and embedded song files
|
|
- **Bundles** (`.probundle`) — ZIP archives containing a single presentation with embedded media assets
|
|
- **Global library files** — `Macros`, `Labels`, `Groups`, `ClearGroups`, `CCLI`, `Messages`, `Timers`, `Stage`, `Workspace`, `Props`, `TestPatterns`, `Calendar`, `KeyMappings`, `CommunicationDevices` (JSON)
|
|
- **Theme folders** — directory with a `Theme` protobuf file plus an `Assets/` subdirectory of media
|
|
|
|
### Key Components
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/Song.php` | Song wrapper (read/modify `.pro` files) |
|
|
| `src/ProFileReader.php` | Read `.pro` files |
|
|
| `src/ProFileWriter.php` | Write `.pro` files |
|
|
| `src/ProFileGenerator.php` | Generate `.pro` files from scratch |
|
|
| `src/PlaylistArchive.php` | Playlist wrapper (read/modify `.proplaylist` files) |
|
|
| `src/ProPlaylistReader.php` | Read `.proplaylist` files |
|
|
| `src/ProPlaylistWriter.php` | Write `.proplaylist` files |
|
|
| `src/ProPlaylistGenerator.php` | Generate `.proplaylist` files from scratch |
|
|
| `src/PresentationBundle.php` | Bundle wrapper (read/write `.probundle` files) |
|
|
| `src/ProBundleReader.php` | Read `.probundle` files |
|
|
| `src/ProBundleWriter.php` | Write `.probundle` files |
|
|
| `src/ThemeBundle.php` | Theme folder wrapper (Template.Document + Assets/) |
|
|
| `src/ThemeFileReader.php` / `ThemeFileWriter.php` | Read/write theme folders |
|
|
| `src/MacroLibrary.php` / `MacrosFileReader.php` / `MacrosFileWriter.php` | Macros file IO |
|
|
| `src/LabelLibrary.php` / `LabelsFileReader.php` / `LabelsFileWriter.php` | Labels file IO |
|
|
| `src/GroupLibrary.php` / `GroupsFileReader.php` / `GroupsFileWriter.php` | Groups file IO |
|
|
| `src/ClearGroupsLibrary.php` / `ClearGroupsFileReader.php` / `ClearGroupsFileWriter.php` | ClearGroups file IO |
|
|
| `src/CCLILibrary.php` / `CCLIFileReader.php` / `CCLIFileWriter.php` | CCLI file IO |
|
|
| `src/MessageLibrary.php` / `MessagesFileReader.php` / `MessagesFileWriter.php` | Messages file IO |
|
|
| `src/TimersLibrary.php` / `TimersFileReader.php` / `TimersFileWriter.php` | Timers file IO |
|
|
| `src/StageLibrary.php` / `StageFileReader.php` / `StageFileWriter.php` | Stage file IO |
|
|
| `src/WorkspaceLibrary.php` / `WorkspaceFileReader.php` / `WorkspaceFileWriter.php` | Workspace file IO |
|
|
| `src/PropLibrary.php` / `PropsFileReader.php` / `PropsFileWriter.php` | Props file IO |
|
|
| `src/TestPatternsLibrary.php` / `TestPatternsFileReader.php` / `TestPatternsFileWriter.php` | TestPatterns file IO |
|
|
| `src/CalendarLibrary.php` / `CalendarFileReader.php` / `CalendarFileWriter.php` | Calendar file IO |
|
|
| `src/KeyMappingsLibrary.php` / `KeyMappingsFileReader.php` / `KeyMappingsFileWriter.php` | KeyMappings file IO |
|
|
| `src/CommunicationDevicesLibrary.php` / `CommunicationDevicesFileReader.php` / `CommunicationDevicesFileWriter.php` | CommunicationDevices JSON file IO |
|
|
|
|
### CLI Tools
|
|
|
|
```bash
|
|
# Songs / playlists / bundles
|
|
php bin/parse-song.php path/to/song.pro
|
|
php bin/parse-playlist.php path/to/playlist.proplaylist
|
|
|
|
# Global library files
|
|
php bin/parse-macros.php path/to/Macros
|
|
php bin/parse-labels.php path/to/Labels
|
|
php bin/parse-groups.php path/to/Groups
|
|
php bin/parse-clear-groups.php path/to/ClearGroups
|
|
php bin/parse-ccli.php path/to/CCLI
|
|
php bin/parse-messages.php path/to/Messages
|
|
php bin/parse-timers.php path/to/Timers
|
|
php bin/parse-stage.php path/to/Stage
|
|
php bin/parse-workspace.php path/to/Workspace
|
|
php bin/parse-props.php path/to/Props
|
|
php bin/parse-test-patterns.php path/to/TestPatterns
|
|
php bin/parse-calendar.php path/to/Calendar
|
|
php bin/parse-key-mappings.php path/to/KeyMappings
|
|
php bin/parse-communication-devices.php path/to/CommunicationDevices
|
|
|
|
# Theme folder
|
|
php bin/parse-theme.php path/to/ThemeFolder
|
|
```
|