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.
131 lines
3.2 KiB
Markdown
131 lines
3.2 KiB
Markdown
# KeyMappings Library API
|
|
|
|
> PHP module for reading and writing the global ProPresenter `KeyMappings` file
|
|
> (raw protobuf, no extension) and exposing configured hot-key mappings.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\KeyMappingsFileReader;
|
|
use ProPresenter\Parser\KeyMappingsFileWriter;
|
|
|
|
$library = KeyMappingsFileReader::read('/path/to/KeyMappings');
|
|
|
|
foreach ($library->getMappings() as $mapping) {
|
|
$mapping->getName(); // string
|
|
$mapping->getUuid(); // string
|
|
$mapping->getHotKey(); // ?\Rv\Data\HotKey
|
|
$mapping->getTarget(); // raw bytes
|
|
}
|
|
|
|
KeyMappingsFileWriter::write($library, '/path/to/KeyMappings');
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `KeyMappings` file is the protobuf-serialised
|
|
[`KeyMappingsDocument`](../../proto/keyMappings.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `application_info` | `ApplicationInfo` | ProPresenter writer metadata |
|
|
| `mappings` | repeated `KeyMappingsDocument.Mapping` | Configured key bindings |
|
|
|
|
Each `Mapping` carries:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `uuid` | `UUID` | Optional stable mapping identifier |
|
|
| `hot_key` | `HotKey` | Key combo that fires the action |
|
|
| `target` | bytes | Raw target reference |
|
|
| `name` | string | Optional display name |
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
use ProPresenter\Parser\KeyMappingsFileReader;
|
|
|
|
$library = KeyMappingsFileReader::read('/Users/me/.../KeyMappings');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## KeyMappingsLibrary
|
|
|
|
Top-level wrapper around `Rv\Data\KeyMappingsDocument`. Indexes mappings by UUID
|
|
(case-insensitive) and name.
|
|
|
|
```php
|
|
$library->getMappings();
|
|
$library->count();
|
|
$library->getMappingByUuid('...');
|
|
$library->getMappingByName('Macro trigger');
|
|
$library->addMapping('Macro trigger', 'UUID', $targetBytes);
|
|
$library->removeMapping('UUID');
|
|
$library->getApplicationInfo();
|
|
$library->setApplicationInfo($infoOrNull);
|
|
$library->getDocument(); // \Rv\Data\KeyMappingsDocument
|
|
```
|
|
|
|
---
|
|
|
|
## KeyMapping
|
|
|
|
```php
|
|
$mapping->getName();
|
|
$mapping->setName('New Name');
|
|
$mapping->getUuid();
|
|
$mapping->setUuid('...');
|
|
$mapping->getHotKey();
|
|
$mapping->setHotKey($hotKeyOrNull);
|
|
$mapping->getTarget();
|
|
$mapping->setTarget($bytes);
|
|
$mapping->getProto(); // \Rv\Data\KeyMappingsDocument\Mapping
|
|
```
|
|
|
|
Targets are raw bytes because ProPresenter may encode several internal target
|
|
types here. Keeping bytes opaque preserves round-trip safety.
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-key-mappings.php /path/to/KeyMappings
|
|
```
|
|
|
|
Output for the reference sample:
|
|
|
|
```
|
|
KeyMappings (0):
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/KeyMappingsLibrary.php` | Document-level wrapper with UUID/name lookups |
|
|
| `src/KeyMapping.php` | Single mapping wrapper |
|
|
| `src/KeyMappingsFileReader.php` | Reads the `KeyMappings` file |
|
|
| `src/KeyMappingsFileWriter.php` | Writes the `KeyMappings` file |
|
|
| `bin/parse-key-mappings.php` | CLI tool |
|
|
| `proto/keyMappings.proto` | Protobuf schema |
|
|
| `generated/Rv/Data/KeyMappingsDocument.php` | Generated message class |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
The reference sample contains only `ApplicationInfo` and no mappings. The API
|
|
still supports mapping additions/removals so configured user files can be edited
|
|
and round-tripped safely.
|