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

Raw Permalink Blame History

CCLI Library API

PHP module for reading and writing the global ProPresenter CCLI file (raw protobuf, no extension) that controls copyright display settings.

Quick Reference

use ProPresenter\Parser\CCLIFileReader;
use ProPresenter\Parser\CCLIFileWriter;

$library = CCLIFileReader::read('/path/to/CCLI');

$library->isCCLIDisplayEnabled(); // bool
$library->getCCLILicense();       // string
$library->getDisplayType();       // int enum value
$library->getTemplate();          // ?\Rv\Data\Template\Slide

$library->setCCLILicense('1234567');
CCLIFileWriter::write($library, '/path/to/CCLI');

File Layout

The CCLI file is the protobuf-serialised CCLIDocument:

Field	Type	Description
`application_info`	`ApplicationInfo`	ProPresenter writer metadata
`enable_ccli_display`	bool	Whether copyright info is shown
`ccli_license`	string	CCLI license number
`display_type`	`CCLIDocument.DisplayType`	First, last, first+last, or all slides
`template`	`Template.Slide`	Text/template styling for display

Reading

use ProPresenter\Parser\CCLIFileReader;

$library = CCLIFileReader::read('/Users/me/.../CCLI');

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

CCLILibrary

Top-level wrapper around Rv\Data\CCLIDocument. This is a single-document configuration file; count() returns 1 when read successfully.

$library->count();
$library->isCCLIDisplayEnabled();
$library->setCCLIDisplayEnabled(true);
$library->getCCLILicense();
$library->setCCLILicense('1234567');
$library->getDisplayType();
$library->setDisplayType(3);
$library->getTemplate();
$library->setTemplate($slideOrNull);
$library->getDocument();                  // \Rv\Data\CCLIDocument

CLI Tool

php bin/parse-ccli.php /path/to/CCLI

Output:

CCLI (1):
  [1] enabled=yes :: license=(empty) :: display_type=0 :: template=yes

Key Files

File	Purpose
`src/CCLILibrary.php`	Document-level wrapper
`src/CCLIFileReader.php`	Reads the `CCLI` file
`src/CCLIFileWriter.php`	Writes the `CCLI` file
`bin/parse-ccli.php`	CLI tool
`proto/ccli.proto`	Protobuf schema
`generated/Rv/Data/CCLIDocument.php`	Generated message class

Scope Notes

The wrapper preserves template data and application metadata by mutating the generated protobuf in place. It does not inspect or render the slide template.

2.5 KiB Raw Permalink Blame History