4d10db4f17
PHP 8.4 library and CLI tools to read, modify, and generate ProPresenter 7 files: songs (.pro), playlists (.proplaylist), bundles (.probundle), themes, and the global library files (Macros, Labels, Groups, ClearGroups, CCLI, Messages, Timers, Stage, Workspace, Props, TestPatterns, Calendar, KeyMappings, CommunicationDevices). Built on the MIT-licensed ProPresenter7-Proto schema by greyshirtguy (v7.16.2). Includes 18 CLI parsers, comprehensive API docs in doc/, binary-format specs, and a synthetic 369-test PHPUnit suite covering RTF extraction, translation slides, ZIP64 repair, round-trip fidelity, and end-to-end generation.
193 lines
6.1 KiB
Markdown
193 lines
6.1 KiB
Markdown
# Macros Library API
|
|
|
|
> PHP module for reading the global ProPresenter `Macros` file (raw protobuf,
|
|
> no extension) and exposing each macro's name, UUID, and collection
|
|
> membership.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\MacrosFileReader;
|
|
use ProPresenter\Parser\MacrosFileWriter;
|
|
|
|
$library = MacrosFileReader::read('/path/to/Macros');
|
|
|
|
foreach ($library->getMacros() as $macro) {
|
|
$macro->getName(); // "Gottesdienst START"
|
|
$macro->getUuid(); // "FA0602E4-EDA2-4457-BB62-68AA17184217"
|
|
$macro->getColor(); // ['r'=>..,'g'=>..,'b'=>..,'a'=>..] | null
|
|
$macro->getImageType(); // int — see ImageType enum
|
|
$macro->getImageData(); // bytes — custom icon (empty for built-ins)
|
|
|
|
foreach ($library->getCollectionsForMacro($macro) as $collection) {
|
|
$collection->getName();
|
|
$collection->getUuid();
|
|
}
|
|
}
|
|
|
|
// Modify and persist
|
|
$library->addMacro('NewMacro', '...uuid...');
|
|
$library->getMacroByName('NewMacro')?->setColor(['r'=>0.5, 'g'=>0, 'b'=>1]);
|
|
MacrosFileWriter::write($library, '/path/to/Macros');
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Macros` file is the protobuf-serialised
|
|
[`MacrosDocument`](../../proto/macros.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `application_info` | message | ProPresenter version + flags that wrote the file |
|
|
| `macros` | repeated `Macro` | Definitions: UUID, name, color, actions, icon, startup flag |
|
|
| `macro_collections` | repeated `MacroCollection` | UUID, name, ordered list of `macro_id` references |
|
|
|
|
Macros and collections live at the document root. Membership is by UUID
|
|
reference — a macro may appear in zero, one, or multiple collections.
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
use ProPresenter\Parser\MacrosFileReader;
|
|
|
|
$library = MacrosFileReader::read('/Users/me/.../Macros');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## Writing
|
|
|
|
```php
|
|
use ProPresenter\Parser\MacrosFileWriter;
|
|
|
|
MacrosFileWriter::write($library, '/Users/me/.../Macros');
|
|
```
|
|
|
|
Serialises the underlying `MacrosDocument` to bytes. Round-trip preserves the
|
|
overall byte length; field ordering can vary slightly because the protobuf
|
|
PHP runtime is not guaranteed to be canonical.
|
|
|
|
---
|
|
|
|
## MacroLibrary
|
|
|
|
Top-level wrapper around `Rv\Data\MacrosDocument`. Indexes macros and
|
|
collections for fast lookup.
|
|
|
|
```php
|
|
$library->getMacros(); // Macro[]
|
|
$library->getMacroByUuid('FA06...'); // ?Macro (case-insensitive)
|
|
$library->getMacroByName('Lied 1.Folie'); // ?Macro
|
|
|
|
$library->getCollections(); // MacroCollection[]
|
|
$library->getCollectionByUuid('8D02...'); // ?MacroCollection (case-insensitive)
|
|
$library->getCollectionByName('Ablauf'); // ?MacroCollection
|
|
|
|
// Cross-reference helpers
|
|
$library->getMacrosForCollection($collection); // Macro[] in declared order
|
|
$library->getCollectionsForMacro($macro); // MacroCollection[] (membership)
|
|
|
|
// Mutators
|
|
$library->addMacro('NewMacro', '...uuid...'); // Macro
|
|
$library->removeMacro('...uuid...'); // bool
|
|
$library->addCollection('NewCollection', '...uuid...'); // MacroCollection
|
|
$library->removeCollection('...uuid...'); // bool
|
|
|
|
$library->getDocument(); // \Rv\Data\MacrosDocument (raw protobuf)
|
|
```
|
|
|
|
---
|
|
|
|
## Macro
|
|
|
|
```php
|
|
$macro->getUuid(); // "FA0602E4-..."
|
|
$macro->setUuid('...'); // self
|
|
$macro->getName(); // "Gottesdienst START"
|
|
$macro->setName('...'); // self
|
|
$macro->getColor(); // ['r'=>..,'g'=>..,'b'=>..,'a'=>..] | null
|
|
$macro->setColor(['r'=>0.5,'g'=>0,'b'=>1]); // self (or null to clear)
|
|
$macro->getTriggerOnStartup(); // bool
|
|
$macro->setTriggerOnStartup(true); // self
|
|
$macro->getActionCount(); // int — number of attached Action entries
|
|
$macro->getImageType(); // int — see Rv\Data\MacrosDocument\Macro\ImageType
|
|
$macro->setImageType(...); // self — pass an ImageType enum value
|
|
$macro->getImageData(); // string — custom icon bytes (empty for built-ins)
|
|
$macro->setImageData($pngBytes); // self — set a custom icon
|
|
$macro->getProto(); // \Rv\Data\MacrosDocument\Macro
|
|
```
|
|
|
|
Action payloads are not unwrapped by this library; reach for `getProto()` and
|
|
walk `getActions()` directly when needed.
|
|
|
|
---
|
|
|
|
## MacroCollection
|
|
|
|
```php
|
|
$collection->getUuid(); // "8D02FC57-..."
|
|
$collection->setUuid('...'); // self
|
|
$collection->getName(); // "Ablauf"
|
|
$collection->setName('...'); // self
|
|
$collection->getMacroUuids(); // string[] — referenced macro UUIDs in order
|
|
$collection->setMacroUuids(['...']); // self — replace all referenced UUIDs
|
|
$collection->addMacroUuid('...'); // self — append a single reference
|
|
$collection->getProto(); // \Rv\Data\MacrosDocument\MacroCollection
|
|
```
|
|
|
|
Items use a protobuf `oneof ItemType`; only `macro_id` is currently defined.
|
|
Items without a populated reference are skipped.
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-macros.php /path/to/Macros
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
Macros (24):
|
|
[1] Gottesdienst START :: FA0602E4-EDA2-4457-BB62-68AA17184217 (1 action) [in: Ablauf]
|
|
...
|
|
|
|
Collections (3):
|
|
[1] Ablauf :: 8D02FC57-83F8-4042-9B90-81C229728426 (12 macros)
|
|
1. Gottesdienst START :: FA0602E4-EDA2-4457-BB62-68AA17184217
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/MacroLibrary.php` | Document-level wrapper with lookup + add / remove helpers |
|
|
| `src/Macro.php` | Single macro wrapper with setters |
|
|
| `src/MacroCollection.php` | Collection wrapper with setters |
|
|
| `src/MacrosFileReader.php` | Reads the `Macros` file |
|
|
| `src/MacrosFileWriter.php` | Writes the `Macros` file |
|
|
| `bin/parse-macros.php` | CLI tool |
|
|
| `proto/macros.proto` | Protobuf schema |
|
|
| `generated/Rv/Data/MacrosDocument.php` | Generated message classes |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
Action editing (the inner `repeated Action actions` field on each macro) and
|
|
slide-side macro references on `.pro` files (see `Slide::getMacroUuid()` /
|
|
`Slide::setMacro()`) are out of scope. This module covers the global
|
|
`Macros` document only; reach for `getProto()->getActions()` for raw action
|
|
inspection.
|