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

2.9 KiB

Raw Permalink Blame History

Calendar Library API

PHP module for reading and writing the global ProPresenter Calendar file (raw protobuf, no extension) and preserving scheduled macro events.

Quick Reference

use ProPresenter\Parser\CalendarFileReader;

$library = CalendarFileReader::read('/path/to/Calendar');

foreach ($library->getEvents() as $event) {
    $event->getName();
    $event->getStartTimeSeconds();
    $event->getActionData(); // raw bytes
}

File Layout

The Calendar file is the protobuf-serialised CalendarDocument:

Field	Type	Description
`events`	repeated `CalendarDocument.Event`	Scheduled events
`mode`	`uint32`	Opaque document mode/source flag

Each event includes UUID, name, start/end timestamps, opaque flags, and two raw bytes fields: action_data (field 8) and macro_data (field 9). Those bytes are intentionally not decoded by this wrapper.

Reading

$library = CalendarFileReader::read('/Users/me/.../Calendar');

Throws InvalidArgumentException for missing files and RuntimeException for empty / unreadable files.

CalendarLibrary

$library->getEvents();              // CalendarEvent[]
$library->count();                  // int
$library->getEventByUuid($uuid);    // ?CalendarEvent (case-insensitive)
$library->getEventByName($name);    // ?CalendarEvent
$library->addEvent($name, $uuid);   // CalendarEvent
$library->removeEvent($uuid);       // bool
$library->getMode();                // int
$library->setMode(1);               // void
$library->getDocument();            // \Rv\Data\CalendarDocument

CalendarEvent

$event->getUuid();
$event->setUuid($uuid);
$event->getName();
$event->setName($name);
$event->getStartTime();
$event->setStartTime($timestamp);
$event->getStartTimeSeconds();
$event->setStartTimeSeconds($seconds);
$event->getEndTime();
$event->getEndTimeSeconds();
$event->getFlags();
$event->setFlags($bytes);
$event->getActionData(); // raw protobuf bytes
$event->setActionData($bytes);
$event->getMacroData();  // raw protobuf bytes
$event->setMacroData($bytes);
$event->getProto();

CLI Tool

php bin/parse-calendar.php /path/to/Calendar

Key Files

File	Purpose
`src/CalendarLibrary.php`	Document wrapper with UUID / name indexes
`src/CalendarEvent.php`	Single event wrapper
`src/CalendarFileReader.php`	Reads the `Calendar` file
`src/CalendarFileWriter.php`	Writes the `Calendar` file
`bin/parse-calendar.php`	CLI summary tool
`proto/calendar.proto`	Protobuf schema
`generated/Rv/Data/CalendarDocument.php`	Generated document class

Scope Notes

action_data and macro_data are raw protobuf byte strings. They are exposed directly for byte-preserving edits and round trips; semantic decoding belongs in a future schema-specific module.

2.9 KiB Raw Permalink Blame History