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.6 KiB

Raw Blame History

Timers Library API

PHP module for reading and writing the global ProPresenter Timers file (raw protobuf, no extension), including the top-level clock format.

Quick Reference

use ProPresenter\Parser\TimersFileReader;

$library = TimersFileReader::read('/path/to/Timers');
$library->getClockFormat(); // "HH:mm"

foreach ($library->getTimers() as $timer) {
    $timer->getName();
    $timer->isCountdown();
    $timer->getDurationSeconds();
}

File Layout

The Timers file is the protobuf-serialised TimersDocument:

Field	Type	Description
`application_info`	`ApplicationInfo`	ProPresenter metadata
`clock`	`Clock`	Global clock display settings
`timers`	repeated `Timer`	Timer definitions

Reading

$library = TimersFileReader::read('/Users/me/.../Timers');

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

TimersLibrary

$library->getTimers();              // Timer[]
$library->count();                  // int
$library->getTimerByUuid($uuid);    // ?Timer (case-insensitive)
$library->getTimerByName($name);    // ?Timer
$library->addTimer($name, $uuid);   // Timer
$library->removeTimer($uuid);       // bool
$library->getClockFormat();         // string
$library->setClockFormat('HH:mm');  // void
$library->getApplicationInfo();     // ?\Rv\Data\ApplicationInfo
$library->getDocument();            // \Rv\Data\TimersDocument

Timer

$timer->getUuid();
$timer->setUuid($uuid);
$timer->getName();
$timer->setName($name);
$timer->getConfiguration();     // ?\Rv\Data\Timer\Configuration
$timer->isCountdown();
$timer->isCountdownToTime();
$timer->isElapsedTime();
$timer->getDurationSeconds();   // ?int for countdown timers
$timer->getProto();             // \Rv\Data\Timer

CLI Tool

php bin/parse-timers.php /path/to/Timers

Key Files

File	Purpose
`src/TimersLibrary.php`	Document wrapper with UUID / name indexes
`src/Timer.php`	Single timer wrapper
`src/TimersFileReader.php`	Reads the `Timers` file
`src/TimersFileWriter.php`	Writes the `Timers` file
`bin/parse-timers.php`	CLI summary tool
`generated/Rv/Data/TimersDocument.php`	Generated document class

Scope Notes

Timer configuration is exposed as the generated protobuf sub-message. Helper methods cover the oneof timer type and countdown duration without hiding raw access for callers that need advanced fields.

2.6 KiB Raw Blame History