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;

$library = MacrosFileReader::read('/path/to/Macros');

foreach ($library->getMacros() as $macro) {
    $macro->getName();   // "Gottesdienst START"
    $macro->getUuid();   // "FA0602E4-EDA2-4457-BB62-68AA17184217"

    foreach ($library->getCollectionsForMacro($macro) as $collection) {
        $collection->getName();   // "Ablauf"
        $collection->getUuid();   // "8D02FC57-83F8-4042-9B90-81C229728426"
    }
}

---

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.

---

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)

$library->getDocument();   // \Rv\Data\MacrosDocument (raw protobuf)

---

Macro

$macro->getUuid();                // "FA0602E4-..."
$macro->getName();                // "Gottesdienst START"
$macro->getColor();               // ['r'=>..,'g'=>..,'b'=>..,'a'=>..] | null
$macro->getTriggerOnStartup();    // bool
$macro->getActionCount();         // int — number of attached Action entries
$macro->getImageType();           // int — see Rv\Data\MacrosDocument\Macro\ImageType
$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->getName();         // "Ablauf"
$collection->getMacroUuids();   // string[] — referenced macro UUIDs in order
$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 helpers
src/Macro.php	Single macro wrapper
src/MacroCollection.php	Collection wrapper
src/MacrosFileReader.php	Reads the Macros file
bin/parse-macros.php	CLI tool
proto/macros.proto	Protobuf schema
generated/Rv/Data/MacrosDocument.php	Generated message classes

---

Scope Notes

This module is read-only by design. Action editing, slide-side macro references on .pro files (see Slide::getMacroUuid() / Slide::setMacro()), and writing the Macros file back are not implemented here. Add them by mirroring the ProFileWriter / ProFileGenerator pattern when needed.