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

Raw Blame History

Theme Bundle API

PHP module for reading, modifying, and writing folder-based ProPresenter themes.

Quick Reference

use ProPresenter\Parser\ThemeFileReader;
use ProPresenter\Parser\ThemeFileWriter;

$theme = ThemeFileReader::read('/path/to/theme-folder');

foreach ($theme->getSlides() as $slide) {
    $slide->getName();       // KeyVisual, Liedtext, ...
    $slide->getBaseSlide();  // ?\Rv\Data\Slide
}

foreach ($theme->getAssets() as $asset) {
    $asset->getName();
    $asset->getSize();
    $asset->getMimeType();
}

ThemeFileWriter::write($theme, '/path/to/output-folder');

Folder Layout

A theme is a directory, not a single protobuf file:

SampleTheme/
├── Theme          # Rv\Data\Template\Document protobuf
└── Assets/
    ├── BACKGROUND.jpg
    ├── BAUCHBIND_STREAM.jpg
    └── KEY_VISUAL.jpg

The Theme file is a Rv\Data\Template\Document from template.proto. Its slides are named theme layouts.

ThemeBundle

$theme->getDocument();
$theme->getSlides();
$theme->getSlideByName('KeyVisual');
$theme->addSlide($slide);
$theme->removeSlide('KeyVisual');
$theme->getAssets();
$theme->getAssetByName('BACKGROUND.jpg');
$theme->addAsset('NEW.jpg', $bytes);
$theme->removeAsset('NEW.jpg');
$theme->count();
$theme->getAssetCount();

ThemeSlide

$slide->getName();
$slide->setName('Liedtext');
$slide->getBaseSlide();
$slide->getProto();

ThemeAsset

$asset->getName();
$asset->getBytes();
$asset->getSize();
$asset->getMimeType(); // image/jpeg, image/png, ...

MIME type detection is extension-based and best-effort.

Writing Themes

ThemeFileWriter::write() creates the target folder if needed, writes the serialized Theme protobuf, creates Assets/, writes every ThemeAsset, and removes stale files from Assets/ that are not present in the bundle.

CLI Tool

php bin/parse-theme.php /path/to/theme-folder

The CLI prints slide names plus asset filenames, sizes, and MIME types.

Key Files

File	Purpose
`src/ThemeBundle.php`	Top-level theme wrapper
`src/ThemeFileReader.php`	Reads a theme folder
`src/ThemeFileWriter.php`	Writes a theme folder and cleans stale assets
`src/ThemeSlide.php`	Single template slide wrapper
`src/ThemeAsset.php`	Single asset value object
`bin/parse-theme.php`	CLI summary tool

2.4 KiB Raw Blame History