propresenter-php/doc/api/macros.md

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

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:

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

use ProPresenter\Parser\MacrosFileReader;

$library = MacrosFileReader::read('/Users/me/.../Macros');

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

---

Writing

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.

$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

$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

$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

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.