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

223 lines
12 KiB
Markdown
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](formats/pp_song_spec.md) |
| `.proplaylist` | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) |
| `.probundle` | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
| protobuf | [formats/pp_song_spec.md](formats/pp_song_spec.md) |
| ZIP | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md), [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) |
| ZIP64 | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md), [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
| binary format | [formats/pp_song_spec.md](formats/pp_song_spec.md), [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md), [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
| JSON | [api/communication-devices.md](api/communication-devices.md) |
## Song Structure
| Keyword | Document |
|---------|----------|
| song | [api/song.md](api/song.md) |
| group | [api/song.md](api/song.md), [api/groups.md](api/groups.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 4 |
| slide | [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5 |
| arrangement | [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 6 |
| translation | [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 7 |
| verse | [api/song.md](api/song.md) |
| chorus | [api/song.md](api/song.md) |
| lyrics | [api/song.md](api/song.md) |
| CCLI | [api/ccli.md](api/ccli.md), [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 3 |
## Bundle Structure
| Keyword | Document |
|---------|----------|
| bundle | [api/bundle.md](api/bundle.md), [api/theme.md](api/theme.md), [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
| probundle | [api/bundle.md](api/bundle.md), [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
| pro6x | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 1 |
| LocalRelativePath | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 3 |
| absolute path | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 2 |
| theme | [api/theme.md](api/theme.md) |
| theme folder | [api/theme.md](api/theme.md) |
| assets | [api/theme.md](api/theme.md), [api/bundle.md](api/bundle.md) |
## Playlist Structure
| Keyword | Document |
|---------|----------|
| playlist | [api/playlist.md](api/playlist.md) |
| entry | [api/playlist.md](api/playlist.md) |
| header | [api/playlist.md](api/playlist.md) |
| presentation | [api/playlist.md](api/playlist.md) |
| placeholder | [api/playlist.md](api/playlist.md) |
| embedded | [api/playlist.md](api/playlist.md) |
## Text Handling
| Keyword | Document |
|---------|----------|
| RTF | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
| text | [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5 |
| plain text | [api/song.md](api/song.md) |
| Unicode | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
| encoding | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
| Windows-1252 | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
| German characters | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
| umlauts | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 9 |
## Actions
| Keyword | Document |
|---------|----------|
| macro | [api/macros.md](api/macros.md), [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5 |
| Macros file | [api/macros.md](api/macros.md) |
| MacroCollection | [api/macros.md](api/macros.md) |
| MacroLibrary | [api/macros.md](api/macros.md) |
| media | [api/song.md](api/song.md), [api/bundle.md](api/bundle.md), [api/theme.md](api/theme.md) |
| image | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5, [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 3, [api/theme.md](api/theme.md) |
| video | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5, [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 6 |
| cue | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5, [api/props.md](api/props.md) |
| label | [api/labels.md](api/labels.md), [api/song.md](api/song.md), [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5 |
| Labels file | [api/labels.md](api/labels.md) |
| LabelLibrary | [api/labels.md](api/labels.md) |
| LabelsFileReader | [api/labels.md](api/labels.md) |
| color | [api/labels.md](api/labels.md), [api/macros.md](api/macros.md), [api/groups.md](api/groups.md), [api/clear-groups.md](api/clear-groups.md) |
## Global library files
| Keyword | Document |
|---------|----------|
| Groups file | [api/groups.md](api/groups.md) |
| GroupLibrary | [api/groups.md](api/groups.md) |
| GroupDefinition | [api/groups.md](api/groups.md) |
| ClearGroups file | [api/clear-groups.md](api/clear-groups.md) |
| ClearGroup | [api/clear-groups.md](api/clear-groups.md) |
| ClearGroupDefinition | [api/clear-groups.md](api/clear-groups.md) |
| CCLI file | [api/ccli.md](api/ccli.md) |
| CCLILibrary | [api/ccli.md](api/ccli.md) |
| copyright | [api/ccli.md](api/ccli.md) |
| license | [api/ccli.md](api/ccli.md) |
| Messages file | [api/messages.md](api/messages.md) |
| MessageLibrary | [api/messages.md](api/messages.md) |
| Message | [api/messages.md](api/messages.md) |
| token | [api/messages.md](api/messages.md) |
| Timers file | [api/timers.md](api/timers.md) |
| TimersLibrary | [api/timers.md](api/timers.md) |
| Timer | [api/timers.md](api/timers.md) |
| Clock | [api/timers.md](api/timers.md) |
| countdown | [api/timers.md](api/timers.md) |
| Stage file | [api/stage.md](api/stage.md) |
| StageLibrary | [api/stage.md](api/stage.md) |
| StageLayout | [api/stage.md](api/stage.md) |
| stage display | [api/stage.md](api/stage.md) |
| Workspace file | [api/workspace.md](api/workspace.md) |
| WorkspaceLibrary | [api/workspace.md](api/workspace.md) |
| Screen | [api/workspace.md](api/workspace.md) |
| audience look | [api/workspace.md](api/workspace.md) |
| mask | [api/workspace.md](api/workspace.md) |
| video input | [api/workspace.md](api/workspace.md) |
| Props file | [api/props.md](api/props.md) |
| PropLibrary | [api/props.md](api/props.md) |
| Prop | [api/props.md](api/props.md) |
| TestPatterns file | [api/test-patterns.md](api/test-patterns.md) |
| TestPatternsLibrary | [api/test-patterns.md](api/test-patterns.md) |
| test pattern | [api/test-patterns.md](api/test-patterns.md) |
| Calendar file | [api/calendar.md](api/calendar.md) |
| CalendarLibrary | [api/calendar.md](api/calendar.md) |
| CalendarEvent | [api/calendar.md](api/calendar.md) |
| schedule | [api/calendar.md](api/calendar.md) |
| KeyMappings file | [api/key-mappings.md](api/key-mappings.md) |
| KeyMappingsLibrary | [api/key-mappings.md](api/key-mappings.md) |
| KeyMapping | [api/key-mappings.md](api/key-mappings.md) |
| hot key | [api/key-mappings.md](api/key-mappings.md), [api/groups.md](api/groups.md) |
| CommunicationDevices file | [api/communication-devices.md](api/communication-devices.md) |
| CommunicationDevicesLibrary | [api/communication-devices.md](api/communication-devices.md) |
| CommunicationDevice | [api/communication-devices.md](api/communication-devices.md) |
| MIDI | [api/communication-devices.md](api/communication-devices.md) |
| OSC | [api/communication-devices.md](api/communication-devices.md) |
| Theme | [api/theme.md](api/theme.md) |
| ThemeBundle | [api/theme.md](api/theme.md) |
| ThemeSlide | [api/theme.md](api/theme.md) |
| ThemeAsset | [api/theme.md](api/theme.md) |
## PHP API
| Keyword | Document |
|---------|----------|
| read | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/bundle.md](api/bundle.md), [api/macros.md](api/macros.md), [api/labels.md](api/labels.md), [api/groups.md](api/groups.md) |
| write | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/bundle.md](api/bundle.md), [api/macros.md](api/macros.md), [api/labels.md](api/labels.md), [api/groups.md](api/groups.md), [api/theme.md](api/theme.md) |
| generate | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md) |
| parse | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/bundle.md](api/bundle.md), [api/macros.md](api/macros.md), [api/labels.md](api/labels.md), [api/groups.md](api/groups.md) |
| MacrosFileReader | [api/macros.md](api/macros.md) |
| MacrosFileWriter | [api/macros.md](api/macros.md) |
| LabelsFileWriter | [api/labels.md](api/labels.md) |
| GroupsFileReader | [api/groups.md](api/groups.md) |
| GroupsFileWriter | [api/groups.md](api/groups.md) |
| ProFileReader | [api/song.md](api/song.md) |
| ProFileWriter | [api/song.md](api/song.md) |
| ProFileGenerator | [api/song.md](api/song.md) |
| ProPlaylistReader | [api/playlist.md](api/playlist.md) |
| ProPlaylistWriter | [api/playlist.md](api/playlist.md) |
| ProPlaylistGenerator | [api/playlist.md](api/playlist.md) |
| ProBundleReader | [api/bundle.md](api/bundle.md) |
| ProBundleWriter | [api/bundle.md](api/bundle.md) |
| PresentationBundle | [api/bundle.md](api/bundle.md) |
| ThemeFileReader | [api/theme.md](api/theme.md) |
| ThemeFileWriter | [api/theme.md](api/theme.md) |
| Song | [api/song.md](api/song.md) |
| PlaylistArchive | [api/playlist.md](api/playlist.md) |
| CLI | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/macros.md](api/macros.md), [api/labels.md](api/labels.md), [api/groups.md](api/groups.md) |
| command line | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/macros.md](api/macros.md), [api/labels.md](api/labels.md) |
## Protobuf
| Keyword | Document |
|---------|----------|
| Presentation | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 3 |
| CueGroup | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 4 |
| Cue | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5, [api/props.md](api/props.md) |
| Action | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 5 |
| Playlist | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) Section 3 |
| PlaylistItem | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) Section 5 |
| UUID | [formats/pp_song_spec.md](formats/pp_song_spec.md), [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) |
| field number | [formats/pp_song_spec.md](formats/pp_song_spec.md) Appendix |
| proto | [formats/pp_song_spec.md](formats/pp_song_spec.md) |
| Template.Document | [api/theme.md](api/theme.md) |
| ProPresenterWorkspace | [api/workspace.md](api/workspace.md) |
| ProGroupsDocument | [api/groups.md](api/groups.md) |
| ClearGroupsDocument | [api/clear-groups.md](api/clear-groups.md) |
| MessageDocument | [api/messages.md](api/messages.md) |
| TimersDocument | [api/timers.md](api/timers.md) |
| Stage.Document | [api/stage.md](api/stage.md) |
| PropDocument | [api/props.md](api/props.md) |
| TestPatternDocument | [api/test-patterns.md](api/test-patterns.md) |
| CalendarDocument | [api/calendar.md](api/calendar.md) |
| KeyMappingsDocument | [api/key-mappings.md](api/key-mappings.md) |
| CCLIDocument | [api/ccli.md](api/ccli.md) |
## Troubleshooting
| Keyword | Document |
|---------|----------|
| error | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/bundle.md](api/bundle.md) |
| exception | [api/song.md](api/song.md), [api/playlist.md](api/playlist.md), [api/bundle.md](api/bundle.md) |
| empty file | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 8 |
| edge case | [formats/pp_song_spec.md](formats/pp_song_spec.md) Section 8, [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) Section 9 |
| ZIP64 bug | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) Section 4, [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) Section 4, [api/playlist.md](api/playlist.md) |
| round-trip | [internal/learnings.md](internal/learnings.md) |
| fidelity | [internal/issues.md](internal/issues.md) |
## Development
| Keyword | Document |
|---------|----------|
| TDD | [internal/learnings.md](internal/learnings.md) |
| PHPUnit | [internal/learnings.md](internal/learnings.md) |
| composer | [internal/learnings.md](internal/learnings.md) |
| architecture | [internal/decisions.md](internal/decisions.md) |
| decision | [internal/decisions.md](internal/decisions.md) |
| convention | [internal/learnings.md](internal/learnings.md) |
| issue | [internal/issues.md](internal/issues.md) |
| gotcha | [internal/issues.md](internal/issues.md) |
Reference in a new issue View git blame Copy permalink