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.
116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
# Calendar Library API
|
|
|
|
> PHP module for reading and writing the global ProPresenter `Calendar` file
|
|
> (raw protobuf, no extension) and preserving scheduled macro events.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\CalendarFileReader;
|
|
|
|
$library = CalendarFileReader::read('/path/to/Calendar');
|
|
|
|
foreach ($library->getEvents() as $event) {
|
|
$event->getName();
|
|
$event->getStartTimeSeconds();
|
|
$event->getActionData(); // raw bytes
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Calendar` file is the protobuf-serialised
|
|
[`CalendarDocument`](../../proto/calendar.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `events` | repeated `CalendarDocument.Event` | Scheduled events |
|
|
| `mode` | `uint32` | Opaque document mode/source flag |
|
|
|
|
Each event includes UUID, name, start/end timestamps, opaque `flags`, and two
|
|
raw bytes fields: `action_data` (field 8) and `macro_data` (field 9). Those
|
|
bytes are intentionally not decoded by this wrapper.
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
$library = CalendarFileReader::read('/Users/me/.../Calendar');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## CalendarLibrary
|
|
|
|
```php
|
|
$library->getEvents(); // CalendarEvent[]
|
|
$library->count(); // int
|
|
$library->getEventByUuid($uuid); // ?CalendarEvent (case-insensitive)
|
|
$library->getEventByName($name); // ?CalendarEvent
|
|
$library->addEvent($name, $uuid); // CalendarEvent
|
|
$library->removeEvent($uuid); // bool
|
|
$library->getMode(); // int
|
|
$library->setMode(1); // void
|
|
$library->getDocument(); // \Rv\Data\CalendarDocument
|
|
```
|
|
|
|
---
|
|
|
|
## CalendarEvent
|
|
|
|
```php
|
|
$event->getUuid();
|
|
$event->setUuid($uuid);
|
|
$event->getName();
|
|
$event->setName($name);
|
|
$event->getStartTime();
|
|
$event->setStartTime($timestamp);
|
|
$event->getStartTimeSeconds();
|
|
$event->setStartTimeSeconds($seconds);
|
|
$event->getEndTime();
|
|
$event->getEndTimeSeconds();
|
|
$event->getFlags();
|
|
$event->setFlags($bytes);
|
|
$event->getActionData(); // raw protobuf bytes
|
|
$event->setActionData($bytes);
|
|
$event->getMacroData(); // raw protobuf bytes
|
|
$event->setMacroData($bytes);
|
|
$event->getProto();
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-calendar.php /path/to/Calendar
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/CalendarLibrary.php` | Document wrapper with UUID / name indexes |
|
|
| `src/CalendarEvent.php` | Single event wrapper |
|
|
| `src/CalendarFileReader.php` | Reads the `Calendar` file |
|
|
| `src/CalendarFileWriter.php` | Writes the `Calendar` file |
|
|
| `bin/parse-calendar.php` | CLI summary tool |
|
|
| `proto/calendar.proto` | Protobuf schema |
|
|
| `generated/Rv/Data/CalendarDocument.php` | Generated document class |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
`action_data` and `macro_data` are raw protobuf byte strings. They are exposed
|
|
directly for byte-preserving edits and round trips; semantic decoding belongs in
|
|
a future schema-specific module.
|