Thorsten Buss 4d10db4f17 Initial public release

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.

2026-05-03 22:21:01 +02:00

3.2 KiB

Raw Blame History

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

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:

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

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.

$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

$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

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.

3.2 KiB Raw Blame History