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.
136 lines
4 KiB
Markdown
136 lines
4 KiB
Markdown
# 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
|
|
|
|
```php
|
|
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`](../../proto/clearGroups.proto):
|
|
|
|
| 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
|
|
|
|
```php
|
|
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.
|
|
|
|
```php
|
|
$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
|
|
|
|
```php
|
|
$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
|
|
|
|
```bash
|
|
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.
|