9e3e719806
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.
81 lines
1.5 KiB
Markdown
81 lines
1.5 KiB
Markdown
# Props Library API
|
|
|
|
> PHP module for reading, modifying, and writing the global ProPresenter `Props` file.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\PropsFileReader;
|
|
use ProPresenter\Parser\PropsFileWriter;
|
|
|
|
$library = PropsFileReader::read('/path/to/Props');
|
|
|
|
foreach ($library->getProps() as $prop) {
|
|
$prop->getName();
|
|
$prop->getUuid();
|
|
$prop->isEnabled();
|
|
}
|
|
|
|
PropsFileWriter::write($library, '/path/to/Props');
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Props` file is `Rv\Data\PropDocument` from `propDocument.proto`.
|
|
Each prop is stored as a `Rv\Data\Cue` in the document's `cues` field.
|
|
|
|
---
|
|
|
|
## PropLibrary
|
|
|
|
```php
|
|
$library->getDocument();
|
|
$library->getProps();
|
|
$library->getPropByUuid('1FB2...'); // case-insensitive
|
|
$library->getPropByName('Props #1');
|
|
$library->addProp($prop);
|
|
$library->removeProp($uuid);
|
|
$library->count();
|
|
$library->getApplicationInfo();
|
|
```
|
|
|
|
---
|
|
|
|
## Prop
|
|
|
|
```php
|
|
$prop->getName();
|
|
$prop->setName('Lower Third');
|
|
$prop->getUuid();
|
|
$prop->setUuid('...');
|
|
$prop->isEnabled();
|
|
$prop->setEnabled(true);
|
|
$prop->getCompletionTime();
|
|
$prop->getActions();
|
|
$prop->getProto();
|
|
```
|
|
|
|
Use `getProto()` for full Cue/action access.
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-props.php /path/to/Props
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/PropsFileReader.php` | Reads the `Props` file |
|
|
| `src/PropsFileWriter.php` | Writes the `Props` file |
|
|
| `src/PropLibrary.php` | Document wrapper and indexes |
|
|
| `src/Prop.php` | Single Cue/prop wrapper |
|
|
| `bin/parse-props.php` | CLI summary tool |
|