propresenter-php/doc/api/clear-groups.md

ClearGroups Library API

PHP module for reading and writing the global ProPresenter ClearGroups file (raw protobuf, no extension) and exposing each clear group definition.

Quick Reference

use ProPresenter\Parser\ClearGroupsFileReader;
use ProPresenter\Parser\ClearGroupsFileWriter;

$library = ClearGroupsFileReader::read('/path/to/ClearGroups');

foreach ($library->getGroups() as $group) {
    $group->getName();      // "Alles ausblenden"
    $group->getUuid();      // "A91C6AFE-..."
    $group->getImageType(); // 11
    $group->getColorHex();  // "#FFFFFF" | null
}

ClearGroupsFileWriter::write($library, '/path/to/ClearGroups');

---

File Layout

The ClearGroups file is the protobuf-serialised ClearGroupsDocument:

Field	Type	Description
application_info	ApplicationInfo	ProPresenter writer metadata
groups	repeated ClearGroupsDocument.ClearGroup	Clear button definitions

Each ClearGroup carries:

Field	Type	Description
uuid	UUID	Stable identifier
name	string	Display name
layer_targets	repeated Action.ClearType	Layers cleared by the button
is_hidden_in_preview	bool	Whether preview UI hides the button
image_data	bytes	Custom icon payload
image_type	enum	Built-in icon identifier
is_icon_tinted	bool	Whether icon_tint_color applies
icon_tint_color	Color	RGBA float channels in 0..1
timeline_targets	repeated Action.ContentDestination	Timeline destinations
clear_presentation_next_slide	bool	Also clear the queued next slide

---

Reading

use ProPresenter\Parser\ClearGroupsFileReader;

$library = ClearGroupsFileReader::read('/Users/me/.../ClearGroups');

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

---

ClearGroupsLibrary

Top-level wrapper around Rv\Data\ClearGroupsDocument. Indexes groups by UUID (case-insensitive) and name.

$library->getGroups();                         // ClearGroupDefinition[]
$library->count();                             // int
$library->getClearGroupByUuid('A91C...');      // ?ClearGroupDefinition
$library->getClearGroupByName('Alles ...');    // ?ClearGroupDefinition
$library->addClearGroup('Name', 'UUID');       // ClearGroupDefinition
$library->removeClearGroup('UUID');            // bool
$library->getDocument();                       // \Rv\Data\ClearGroupsDocument

---

ClearGroupDefinition

$group->getName();
$group->setName('New Name');
$group->getUuid();
$group->setUuid('...');
$group->getLayerTargets();
$group->getImageType();
$group->getColor();       // ['r'=>..,'g'=>..,'b'=>..,'a'=>..] | null
$group->getColorHex();    // "#RRGGBB" uppercase, alpha dropped, or null
$group->getProto();       // \Rv\Data\ClearGroupsDocument\ClearGroup

Color channels are floats in 0..1 as ProPresenter stores them. getColorHex() clamps and rounds each channel to 8 bits before formatting.

---

CLI Tool

php bin/parse-clear-groups.php /path/to/ClearGroups

Output:

ClearGroups (1):
  [1] Alles ausblenden :: A91C6AFE-098F-4559-B2CF-D8373C589589 :: image_type=11 :: #FFFFFF

---

Key Files

File	Purpose
src/ClearGroupsLibrary.php	Document-level wrapper with UUID/name lookups
src/ClearGroupDefinition.php	Single clear group wrapper
src/ClearGroupsFileReader.php	Reads the ClearGroups file
src/ClearGroupsFileWriter.php	Writes the ClearGroups file
bin/parse-clear-groups.php	CLI tool
proto/clearGroups.proto	Protobuf schema
generated/Rv/Data/ClearGroupsDocument.php	Generated message class

---

Scope Notes

The wrapper preserves unknown / uninterpreted protobuf data by mutating the generated message in place and serialising it back. It does not execute clear actions or modify slide content.