public/propresenter-php
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
propresenter-php/doc/keywords.md
Thorsten Bus 9e3e719806 feat(library): add readers + writers for all ProPresenter global libraries and theme bundles 
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.
2026-05-03 21:40:09 +02:00

12 KiB
Raw Blame History

Keyword Index

Search this file to find which documents to load for specific topics.

File Formats

Keyword Document
.pro formats/pp_song_spec.md
.proplaylist formats/pp_playlist_spec.md
.probundle formats/pp_bundle_spec.md
protobuf formats/pp_song_spec.md
ZIP formats/pp_bundle_spec.md, formats/pp_playlist_spec.md
ZIP64 formats/pp_playlist_spec.md, formats/pp_bundle_spec.md
binary format formats/pp_song_spec.md, formats/pp_playlist_spec.md, formats/pp_bundle_spec.md
JSON api/communication-devices.md

Song Structure

Keyword Document
song api/song.md
group api/song.md, api/groups.md, formats/pp_song_spec.md Section 4
slide api/song.md, formats/pp_song_spec.md Section 5
arrangement api/song.md, formats/pp_song_spec.md Section 6
translation api/song.md, formats/pp_song_spec.md Section 7
verse api/song.md
chorus api/song.md
lyrics api/song.md
CCLI api/ccli.md, api/song.md, formats/pp_song_spec.md Section 3

Bundle Structure

Keyword Document
bundle api/bundle.md, api/theme.md, formats/pp_bundle_spec.md
probundle api/bundle.md, formats/pp_bundle_spec.md
pro6x formats/pp_bundle_spec.md Section 1
LocalRelativePath formats/pp_bundle_spec.md Section 3
absolute path formats/pp_bundle_spec.md Section 2
theme api/theme.md
theme folder api/theme.md
assets api/theme.md, api/bundle.md

Playlist Structure

Keyword Document
playlist api/playlist.md
entry api/playlist.md
header api/playlist.md
presentation api/playlist.md
placeholder api/playlist.md
embedded api/playlist.md

Text Handling

Keyword Document
RTF formats/pp_song_spec.md Section 9
text api/song.md, formats/pp_song_spec.md Section 5
plain text api/song.md
Unicode formats/pp_song_spec.md Section 9
encoding formats/pp_song_spec.md Section 9
Windows-1252 formats/pp_song_spec.md Section 9
German characters formats/pp_song_spec.md Section 9
umlauts formats/pp_song_spec.md Section 9

Actions

Keyword Document
macro api/macros.md, api/song.md, formats/pp_song_spec.md Section 5
Macros file api/macros.md
MacroCollection api/macros.md
MacroLibrary api/macros.md
media api/song.md, api/bundle.md, api/theme.md
image formats/pp_song_spec.md Section 5, formats/pp_bundle_spec.md Section 3, api/theme.md
video formats/pp_song_spec.md Section 5, formats/pp_bundle_spec.md Section 6
cue formats/pp_song_spec.md Section 5, api/props.md
label api/labels.md, api/song.md, formats/pp_song_spec.md Section 5
Labels file api/labels.md
LabelLibrary api/labels.md
LabelsFileReader api/labels.md
color api/labels.md, api/macros.md, api/groups.md, api/clear-groups.md

Global library files

Keyword Document
Groups file api/groups.md
GroupLibrary api/groups.md
GroupDefinition api/groups.md
ClearGroups file api/clear-groups.md
ClearGroup api/clear-groups.md
ClearGroupDefinition api/clear-groups.md
CCLI file api/ccli.md
CCLILibrary api/ccli.md
copyright api/ccli.md
license api/ccli.md
Messages file api/messages.md
MessageLibrary api/messages.md
Message api/messages.md
token api/messages.md
Timers file api/timers.md
TimersLibrary api/timers.md
Timer api/timers.md
Clock api/timers.md
countdown api/timers.md
Stage file api/stage.md
StageLibrary api/stage.md
StageLayout api/stage.md
stage display api/stage.md
Workspace file api/workspace.md
WorkspaceLibrary api/workspace.md
Screen api/workspace.md
audience look api/workspace.md
mask api/workspace.md
video input api/workspace.md
Props file api/props.md
PropLibrary api/props.md
Prop api/props.md
TestPatterns file api/test-patterns.md
TestPatternsLibrary api/test-patterns.md
test pattern api/test-patterns.md
Calendar file api/calendar.md
CalendarLibrary api/calendar.md
CalendarEvent api/calendar.md
schedule api/calendar.md
KeyMappings file api/key-mappings.md
KeyMappingsLibrary api/key-mappings.md
KeyMapping api/key-mappings.md
hot key api/key-mappings.md, api/groups.md
CommunicationDevices file api/communication-devices.md
CommunicationDevicesLibrary api/communication-devices.md
CommunicationDevice api/communication-devices.md
MIDI api/communication-devices.md
OSC api/communication-devices.md
Theme api/theme.md
ThemeBundle api/theme.md
ThemeSlide api/theme.md
ThemeAsset api/theme.md

PHP API

Keyword Document
read api/song.md, api/playlist.md, api/bundle.md, api/macros.md, api/labels.md, api/groups.md
write api/song.md, api/playlist.md, api/bundle.md, api/macros.md, api/labels.md, api/groups.md, api/theme.md
generate api/song.md, api/playlist.md
parse api/song.md, api/playlist.md, api/bundle.md, api/macros.md, api/labels.md, api/groups.md
MacrosFileReader api/macros.md
MacrosFileWriter api/macros.md
LabelsFileWriter api/labels.md
GroupsFileReader api/groups.md
GroupsFileWriter api/groups.md
ProFileReader api/song.md
ProFileWriter api/song.md
ProFileGenerator api/song.md
ProPlaylistReader api/playlist.md
ProPlaylistWriter api/playlist.md
ProPlaylistGenerator api/playlist.md
ProBundleReader api/bundle.md
ProBundleWriter api/bundle.md
PresentationBundle api/bundle.md
ThemeFileReader api/theme.md
ThemeFileWriter api/theme.md
Song api/song.md
PlaylistArchive api/playlist.md
CLI api/song.md, api/playlist.md, api/macros.md, api/labels.md, api/groups.md
command line api/song.md, api/playlist.md, api/macros.md, api/labels.md

Protobuf

Keyword Document
Presentation formats/pp_song_spec.md Section 3
CueGroup formats/pp_song_spec.md Section 4
Cue formats/pp_song_spec.md Section 5, api/props.md
Action formats/pp_song_spec.md Section 5
Playlist formats/pp_playlist_spec.md Section 3
PlaylistItem formats/pp_playlist_spec.md Section 5
UUID formats/pp_song_spec.md, formats/pp_playlist_spec.md
field number formats/pp_song_spec.md Appendix
proto formats/pp_song_spec.md
Template.Document api/theme.md
ProPresenterWorkspace api/workspace.md
ProGroupsDocument api/groups.md
ClearGroupsDocument api/clear-groups.md
MessageDocument api/messages.md
TimersDocument api/timers.md
Stage.Document api/stage.md
PropDocument api/props.md
TestPatternDocument api/test-patterns.md
CalendarDocument api/calendar.md
KeyMappingsDocument api/key-mappings.md
CCLIDocument api/ccli.md

Troubleshooting

Keyword Document
error api/song.md, api/playlist.md, api/bundle.md
exception api/song.md, api/playlist.md, api/bundle.md
empty file formats/pp_song_spec.md Section 8
edge case formats/pp_song_spec.md Section 8, formats/pp_playlist_spec.md Section 9
ZIP64 bug formats/pp_playlist_spec.md Section 4, formats/pp_bundle_spec.md Section 4, api/playlist.md
round-trip internal/learnings.md
fidelity internal/issues.md

Development

Keyword Document
TDD internal/learnings.md
PHPUnit internal/learnings.md
composer internal/learnings.md
architecture internal/decisions.md
decision internal/decisions.md
convention internal/learnings.md
issue internal/issues.md
gotcha internal/issues.md