Thorsten Bus 9e3e719806 feat(library): add readers + writers for all ProPresenter global libraries and theme bundles

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.

2026-05-03 21:40:09 +02:00

4.3 KiB

Raw Blame History

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

Check doc/INDEX.md for the topic overview
Use doc/keywords.md to search by keyword
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/write the global `Macros` file	`doc/api/macros.md`
Read/write the global `Labels` file	`doc/api/labels.md`
Read/write the global `Groups` file	`doc/api/groups.md`
Read/write the global `ClearGroups` file	`doc/api/clear-groups.md`
Read/write the global `CCLI` file	`doc/api/ccli.md`
Read/write the global `Messages` file	`doc/api/messages.md`
Read/write the global `Timers` file	`doc/api/timers.md`
Read/write the global `Stage` file	`doc/api/stage.md`
Read/write the global `Workspace` file	`doc/api/workspace.md`
Read/write the global `Props` file	`doc/api/props.md`
Read/write the global `TestPatterns` file	`doc/api/test-patterns.md`
Read/write the global `Calendar` file	`doc/api/calendar.md`
Read/write the global `KeyMappings` file	`doc/api/key-mappings.md`
Read/write the `CommunicationDevices` JSON file	`doc/api/communication-devices.md`
Read/write a theme folder (Theme + Assets/)	`doc/api/theme.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
Themes (folder with Theme + Assets/) — Template document plus media used as a slide theme
Global library files (no extension) — Macros, Labels, Groups, ClearGroups, CCLI, Messages, Timers, Stage, Workspace, Props, TestPatterns, Calendar, KeyMappings (protobuf) and CommunicationDevices (JSON)

CLI Tools

# Songs / playlists / bundles
php bin/parse-song.php path/to/song.pro
php bin/parse-playlist.php path/to/playlist.proplaylist

# Global library files (one parser per type)
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

Key Source Files

All PHP source code is in src/. Generated protobuf classes are in generated/. Tests are in tests/.

4.3 KiB Raw Blame History