- Add MIT LICENSE (Thorsten Buss) with attribution to the upstream
MIT-licensed greyshirtguy/ProPresenter7-Proto definitions.
- Add comprehensive README.md: badges, feature matrix, install,
seven runnable getting-started examples (read/modify/generate
songs, playlists, bundles, global libraries), CLI tool reference,
documentation index, project structure, caveats.
- Update composer.json with package name (bussnet/propresenter7-php-api),
MIT license, keywords, author, homepage, support URLs, dev autoload,
and a `composer test` script.
- Polish doc/INDEX.md, doc/keywords.md, and doc/CONTRIBUTING.md so they
read well for both humans and AI assistants; remove README-duplicate
content from INDEX.md and link to the top-level README instead.
- Expand .gitignore to cover IDE/OS metadata and agent workspaces.
All 370 tests still pass (9,200 assertions). README examples #3 and #5
verified end-to-end (generate -> read back -> assert metadata).
Add full IO support for every global ProPresenter library file plus
theme folders, and extend the existing Labels/Macros readers with
exporters and editable accessors so every supported document is now a
round-trippable, mutable object.
New library readers/writers (each: FileReader, FileWriter, Library
wrapper, element wrapper where applicable, CLI tool, tests, doc/api/*.md):
- Groups (ProGroupsDocument) + GroupDefinition
- ClearGroups (ClearGroupsDocument) + ClearGroupDefinition
- CCLI (CCLIDocument)
- Messages (MessageDocument) + Message
- Timers (TimersDocument + Clock) + Timer
- Stage (Stage.Document) + StageLayout
- Workspace (ProPresenterWorkspace) + Screen
- Props (PropDocument) + Prop
- TestPatterns (TestPatternDocument)
- Calendar (new CalendarDocument) + CalendarEvent
- KeyMappings (new KeyMappingsDocument) + KeyMapping
- CommunicationDevices (JSON file) + CommunicationDevice
- Theme bundles (Template.Document folder + Assets/) + ThemeBundle/Slide/Asset
Extensions to existing modules:
- LabelsFileWriter; Label and LabelLibrary gain setters, addLabel,
removeLabel, setColor / setColorHex helpers
- MacrosFileWriter; Macro/MacroCollection/MacroLibrary gain UUID, name,
color, image_type, image_data, trigger_on_startup setters plus
add/remove for macros and collections
Two new minimal proto schemas were defined for documents that lacked
upstream definitions:
- proto/calendar.proto - CalendarDocument with Event entries, raw
bytes for the action/macro sub-messages so the schema can evolve
- proto/keyMappings.proto - KeyMappingsDocument with ApplicationInfo
and a forward-looking Mapping message (sample only carries the info)
The Theme file turned out to be a regular Rv\Data\Template\Document, so
no new proto was required for theme content; ThemeBundle layers folder
+ Assets/ handling on top in the same spirit as PresentationBundle.
GroupDefinition is intentionally distinct from the existing Group class
(which wraps song-level CueGroup) to avoid breaking song APIs.
Verified with the full PHPUnit suite: 370 tests, 9200 assertions, all
green; LSP diagnostics clean across src/. The unmodified reference
samples for Labels, Groups, ClearGroups, TestPatterns, Calendar and
KeyMappings round-trip byte-for-byte; the others round-trip with the
same byte length (PHP protobuf is not canonically deterministic but
re-write-after-write stabilises).
doc/INDEX.md, doc/keywords.md and AGENTS.md updated so every new module
is discoverable from the top level.
Mirrors the Macros reader: LabelsFileReader -> LabelLibrary -> Label wraps
the protobuf ProLabelsDocument and exposes each label's name (the proto
'text' field) plus optional RGBA color with a #RRGGBB hex helper. Includes
CLI tool, PHPUnit suite against the bundled reference Labels sample, and
api/labels.md docs.
Importer for ProPresenter's protobuf-encoded `Macros` document. Exposes
each macro's UUID and name plus the collections that group them.
- src/MacroLibrary.php: top-level wrapper indexed by UUID and name
- src/Macro.php, src/MacroCollection.php: per-entry wrappers
- src/MacrosFileReader.php: file -> MacroLibrary entry point
- bin/parse-macros.php: CLI listing macros and collections
- tests/MacrosFileReaderTest.php: 10 tests against reference sample
- doc/api/macros.md: API reference, plus INDEX/keywords updates
BREAKING: Bundle media entries are now flat filenames (no directories).
ProBundleWriter flattens all media paths to basename() automatically.
ProFileGenerator supports bundleRelative flag for ROOT_CURRENT_RESOURCE
URLs, enabling bundles that work on any machine without absolute paths.
ProPresenter .probundle files are ZIP archives containing a single .pro
presentation with embedded media assets. This adds read/write support
verified against actual ProPresenter 7 exports.
- PresentationBundle: wrapper class (Song + media files + .pro filename)
- ProBundleReader: reads .probundle ZIPs, applies Zip64Fixer for PP exports
- ProBundleWriter: writes standard ZIP with media-first entry order
- ProFileGenerator: media URLs now include URL.local with LocalRelativePath
- 9 tests covering error handling, round-trip, PP export compat, ZIP format
- ref/TestBild.probundle: verified importable by ProPresenter 7
Replace byte-identical round-trip assertion with JSON-decoded semantic
comparison. Protobuf serialization does not guarantee byte-level
ordering, so the previous test failed on all 169 fixtures despite
data being functionally identical.
- Modified generate() method to loop through arrangements and find 'normal' (case-insensitive)
- Falls back to first arrangement if 'normal' not found
- Added test: testGenerateSelectsNormalArrangementWhenPresent
- Added test: testGenerateFallsBackToFirstArrangementWhenNoNormal
- All 12 ProFileGenerator tests pass (82 assertions)
All acceptance criteria verified and marked complete:
- Task 1-13: Implementation acceptance criteria (all verified)
- Definition of Done: All 5 criteria met
- Final Verification: All 4 phases approved
- Final Checklist: All 7 items complete
Total: 87/87 checkboxes complete (29 main tasks + 58 acceptance criteria)
- Record final project status in learnings.md
- Add all task evidence files (43 files)
- Add work plan with all 29 checkboxes complete
- Add boulder state tracking
Project complete: 99 tests passing, all deliverables verified
- Implement ProPlaylistReader::read() following ProFileReader pattern
- ZIP handling: fix headers with Zip64Fixer, extract data + embedded files
- Comprehensive error handling: missing file, empty file, invalid ZIP, missing data entry
- Temp file cleanup in finally block (no leaks on error paths)
- 11 tests, 31 assertions — all pass
- Verified with all 4 .proplaylist test files
Task 7 of proplaylist-module plan complete
- Implement PlaylistEntry wrapper for PlaylistItem proto (23 tests, 40 assertions)
- Support all 4 item types: header, presentation, placeholder, cue
- Expose arrangement_name (field 5) for presentation items
- Type-specific getters with null safety
- Implement PlaylistNode wrapper for Playlist proto (15 tests, 37 assertions)
- Handle both container nodes (child playlists) and leaf nodes (items)
- Recursive wrapping of nested playlist structures
- Implement PlaylistArchive wrapper for PlaylistDocument proto (18 tests, 37 assertions)
- Top-level integration of nodes, entries, and embedded files
- Lazy parsing of embedded .pro files into Song objects
- File partitioning: .pro files vs media files
Wave 2 of proplaylist-module plan complete (Tasks 4-6)
- Add arrangement_name field 5 to PlaylistItem.Presentation proto
- Regenerate PHP proto classes with new field
- Implement Zip64Fixer utility to patch ProPresenter's broken ZIP headers
- Add comprehensive test suite for Zip64Fixer (7 tests, 37 assertions)
- Create pp_playlist_spec.md documenting .proplaylist file format
Wave 1 of proplaylist-module plan complete (Tasks 1-3)
