Skip to content

clear-groups.md

Latest commit

 

History

History
135 lines (99 loc) · 3.96 KB

clear-groups.md

File metadata and controls

135 lines (99 loc) · 3.96 KB

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.