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

2.8 KiB

Raw Blame History

Messages Library API

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

Quick Reference

use ProPresenter\Parser\MessagesFileReader;
use ProPresenter\Parser\MessagesFileWriter;

$library = MessagesFileReader::read('/path/to/Messages');

foreach ($library->getMessages() as $message) {
    $message->getTitle();
    $message->getUuid();
    $message->getMessageText();
}

$library->addMessage('Lobby Notice', '11111111-1111-1111-1111-111111111111');
MessagesFileWriter::write($library, '/path/to/Messages');

File Layout

The Messages file is the protobuf-serialised MessageDocument:

Field	Type	Description
`application_info`	`ApplicationInfo`	ProPresenter metadata
`messages`	repeated `Message`	Message definitions in document order

Reading

$library = MessagesFileReader::read('/Users/me/.../Messages');

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

MessageLibrary

$library->getMessages();                    // Message[]
$library->count();                          // int
$library->getMessageByUuid($uuid);          // ?Message (case-insensitive)
$library->getMessageByName($title);         // ?Message (case-sensitive title)
$library->addMessage($title, $uuid);        // Message
$library->removeMessage($uuid);             // bool
$library->getApplicationInfo();             // ?\Rv\Data\ApplicationInfo
$library->getDocument();                    // \Rv\Data\MessageDocument

Message

$message->getUuid();
$message->setUuid($uuid);
$message->getTitle();
$message->setTitle($title);
$message->getTimeToRemove();
$message->setTimeToRemove($seconds);
$message->isVisibleOnNetwork();
$message->setVisibleOnNetwork(true);
$message->getMessageText();
$message->setMessageText($text);
$message->getClearType();
$message->setClearType($enumValue);
$message->getTokens();      // raw repeated Token protos
$message->getProto();       // \Rv\Data\Message

CLI Tool

php bin/parse-messages.php /path/to/Messages

Key Files

File	Purpose
`src/MessageLibrary.php`	Document wrapper with title / UUID indexes
`src/Message.php`	Single message wrapper
`src/MessagesFileReader.php`	Reads the `Messages` file
`src/MessagesFileWriter.php`	Writes the `Messages` file
`bin/parse-messages.php`	CLI summary tool
`generated/Rv/Data/MessageDocument.php`	Generated document class

Scope Notes

Tokens and token values are preserved as raw generated protobuf objects. The wrapper exposes them for advanced callers but does not interpret template rendering semantics.

2.8 KiB Raw Blame History