timers.md

Timers Library API

PHP module for reading and writing the global ProPresenter Timers file (raw protobuf, no extension), including the top-level clock format.

Quick Reference

use ProPresenter\Parser\TimersFileReader;

$library = TimersFileReader::read('/path/to/Timers');
$library->getClockFormat(); // "HH:mm"

foreach ($library->getTimers() as $timer) {
    $timer->getName();
    $timer->isCountdown();
    $timer->getDurationSeconds();
}

---

File Layout

The Timers file is the protobuf-serialised TimersDocument:

Field	Type	Description
application_info	ApplicationInfo	ProPresenter metadata
clock	Clock	Global clock display settings
timers	repeated Timer	Timer definitions

---

Reading

$library = TimersFileReader::read('/Users/me/.../Timers');

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

---

TimersLibrary

$library->getTimers();              // Timer[]
$library->count();                  // int
$library->getTimerByUuid($uuid);    // ?Timer (case-insensitive)
$library->getTimerByName($name);    // ?Timer
$library->addTimer($name, $uuid);   // Timer
$library->removeTimer($uuid);       // bool
$library->getClockFormat();         // string
$library->setClockFormat('HH:mm');  // void
$library->getApplicationInfo();     // ?\Rv\Data\ApplicationInfo
$library->getDocument();            // \Rv\Data\TimersDocument

---

Timer

$timer->getUuid();
$timer->setUuid($uuid);
$timer->getName();
$timer->setName($name);
$timer->getConfiguration();     // ?\Rv\Data\Timer\Configuration
$timer->isCountdown();
$timer->isCountdownToTime();
$timer->isElapsedTime();
$timer->getDurationSeconds();   // ?int for countdown timers
$timer->getProto();             // \Rv\Data\Timer

---

CLI Tool

php bin/parse-timers.php /path/to/Timers

---

Key Files

File	Purpose
src/TimersLibrary.php	Document wrapper with UUID / name indexes
src/Timer.php	Single timer wrapper
src/TimersFileReader.php	Reads the Timers file
src/TimersFileWriter.php	Writes the Timers file
bin/parse-timers.php	CLI summary tool
generated/Rv/Data/TimersDocument.php	Generated document class

---

Scope Notes

Timer configuration is exposed as the generated protobuf sub-message. Helper methods cover the oneof timer type and countdown duration without hiding raw access for callers that need advanced fields.