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.6 KiB

Raw Blame History

CommunicationDevices Library API

PHP module for reading and writing the global ProPresenter CommunicationDevices file. Unlike most config files in this project, this file is JSON, not protobuf.

Quick Reference

use ProPresenter\Parser\CommunicationDevice;
use ProPresenter\Parser\CommunicationDevicesFileReader;
use ProPresenter\Parser\CommunicationDevicesFileWriter;

$library = CommunicationDevicesFileReader::read('/path/to/CommunicationDevices');
$library->addDevice((new CommunicationDevice())->setId('device-1')->setName('Router'));
CommunicationDevicesFileWriter::write($library, '/path/to/CommunicationDevices');

File Layout

CommunicationDevices is a JSON array. The reference sample is [], so the wrapper preserves arbitrary object fields while exposing forward-looking common fields: id, name, type, and address.

Reading

$library = CommunicationDevicesFileReader::read('/Users/me/.../CommunicationDevices');

Throws InvalidArgumentException for missing files and RuntimeException for unreadable files or invalid JSON.

CommunicationDevicesLibrary

CommunicationDevicesLibrary::fromJson($json); // CommunicationDevicesLibrary
$library->toJson();                           // string
$library->getDocument();                      // raw decoded array
$library->getDevices();                       // CommunicationDevice[]
$library->addDevice($device);                 // CommunicationDevice
$library->removeDevice($id);                  // bool
$library->count();                            // int

CommunicationDevice

$device->getId();
$device->setId($id);
$device->getName();
$device->setName($name);
$device->getType();
$device->setType($type);
$device->getAddress();
$device->setAddress($address);
$device->toArray(); // full decoded JSON object

CLI Tool

php bin/parse-communication-devices.php /path/to/CommunicationDevices

Empty files print a useful (none configured) summary.

Key Files

File	Purpose
`src/CommunicationDevicesLibrary.php`	JSON-array wrapper
`src/CommunicationDevice.php`	Single JSON device value object
`src/CommunicationDevicesFileReader.php`	Reads and validates JSON
`src/CommunicationDevicesFileWriter.php`	Writes compact JSON
`bin/parse-communication-devices.php`	CLI summary tool

Scope Notes

Because only an empty sample is available, unknown JSON fields are preserved in each device's backing array. The writer uses compact JSON with unescaped slashes / Unicode for stable semantic round trips.

2.6 KiB Raw Blame History