public/propresenter-php
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
propresenter-php/doc/INDEX.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

11 KiB
Raw Blame History

ProPresenter Parser Documentation

For AI Agents: Load only the documents you need. Use the keyword index to find relevant sections.

Quick Navigation

Need Load
Parse/modify .pro song files api/song.md
Parse/modify .proplaylist files api/playlist.md
Parse/modify .probundle files api/bundle.md
Read/write the global Macros file api/macros.md
Read/write the global Labels file api/labels.md
Read/write the global Groups file api/groups.md
Read/write the global ClearGroups file api/clear-groups.md
Read/write the global CCLI file api/ccli.md
Read/write the global Messages file api/messages.md
Read/write the global Timers file api/timers.md
Read/write the global Stage file api/stage.md
Read/write the global Workspace file api/workspace.md
Read/write the global Props file api/props.md
Read/write the global TestPatterns file api/test-patterns.md
Read/write the global Calendar file api/calendar.md
Read/write the global KeyMappings file api/key-mappings.md
Read/write the global CommunicationDevices JSON file api/communication-devices.md
Read/write theme folders (Theme + Assets/) api/theme.md
Understand .pro binary format formats/pp_song_spec.md
Understand .proplaylist format formats/pp_playlist_spec.md
Understand .probundle format formats/pp_bundle_spec.md
Add new documentation CONTRIBUTING.md
Search by keyword keywords.md

Table of Contents

File Format Specifications

PHP API Documentation

Document containers

  • api/song.md — Song parser API (read, modify, generate .pro files)
  • api/playlist.md — Playlist parser API (read, modify, generate .proplaylist files)
  • api/bundle.md — Bundle parser API (read, write .probundle files with media)
  • api/theme.md — Theme bundle API (folder with Theme proto + Assets/)

Global library files (read + write)

Internal Reference

Meta

Directory Structure

doc/
├── INDEX.md           ← You are here (main entry point)
├── keywords.md        ← Keyword search index
├── CONTRIBUTING.md    ← Documentation guidelines
├── formats/           ← File format specifications
│   ├── pp_song_spec.md
│   ├── pp_playlist_spec.md
│   └── pp_bundle_spec.md
├── api/               ← PHP API documentation
│   ├── song.md
│   ├── playlist.md
│   ├── bundle.md
│   ├── theme.md
│   ├── macros.md
│   ├── labels.md
│   ├── groups.md
│   ├── clear-groups.md
│   ├── ccli.md
│   ├── messages.md
│   ├── timers.md
│   ├── stage.md
│   ├── workspace.md
│   ├── props.md
│   ├── test-patterns.md
│   ├── calendar.md
│   ├── key-mappings.md
│   └── communication-devices.md
└── internal/          ← Development notes (optional context)
    ├── learnings.md
    ├── decisions.md
    └── issues.md

When to Load What

Task: "Parse a song file"

Load: doc/api/song.md

Task: "Generate a new playlist"

Load: doc/api/playlist.md

Task: "Read/write a .probundle"

Load: doc/api/bundle.md

Task: "Edit a global library file (Macros, Labels, Groups, etc.)"

Load: doc/api/<library>.md

Task: "Round-trip a Theme folder with assets"

Load: doc/api/theme.md
Load: doc/api/bundle.md (for the bundle pattern reference)

Task: "Debug protobuf parsing issues"

Load: doc/formats/pp_song_spec.md (sections 2-5)

Task: "Understand translation handling"

Load: doc/api/song.md (section: Translations)
Load: doc/formats/pp_song_spec.md (section 7: Translations)

Task: "Fix ZIP64 issues"

Load: doc/formats/pp_playlist_spec.md (section 4: ZIP64 Container Format)
Load: doc/formats/pp_bundle_spec.md (section 4: ZIP64 EOCD Quirk)
Load: doc/internal/learnings.md (search: Zip64Fixer)

Project Overview

This project provides PHP tools to parse, modify, and generate ProPresenter 7 files:

  • Songs (.pro) — Presentation files containing lyrics with groups, slides, arrangements, and translations
  • Playlists (.proplaylist) — ZIP archives containing playlist metadata and embedded song files
  • Bundles (.probundle) — ZIP archives containing a single presentation with embedded media assets
  • Global library files — Macros, Labels, Groups, ClearGroups, CCLI, Messages, Timers, Stage, Workspace, Props, TestPatterns, Calendar, KeyMappings, CommunicationDevices (JSON)
  • Theme folders — directory with a Theme protobuf file plus an Assets/ subdirectory of media

Key Components

File Purpose
src/Song.php Song wrapper (read/modify .pro files)
src/ProFileReader.php Read .pro files
src/ProFileWriter.php Write .pro files
src/ProFileGenerator.php Generate .pro files from scratch
src/PlaylistArchive.php Playlist wrapper (read/modify .proplaylist files)
src/ProPlaylistReader.php Read .proplaylist files
src/ProPlaylistWriter.php Write .proplaylist files
src/ProPlaylistGenerator.php Generate .proplaylist files from scratch
src/PresentationBundle.php Bundle wrapper (read/write .probundle files)
src/ProBundleReader.php Read .probundle files
src/ProBundleWriter.php Write .probundle files
src/ThemeBundle.php Theme folder wrapper (Template.Document + Assets/)
src/ThemeFileReader.php / ThemeFileWriter.php Read/write theme folders
src/MacroLibrary.php / MacrosFileReader.php / MacrosFileWriter.php Macros file IO
src/LabelLibrary.php / LabelsFileReader.php / LabelsFileWriter.php Labels file IO
src/GroupLibrary.php / GroupsFileReader.php / GroupsFileWriter.php Groups file IO
src/ClearGroupsLibrary.php / ClearGroupsFileReader.php / ClearGroupsFileWriter.php ClearGroups file IO
src/CCLILibrary.php / CCLIFileReader.php / CCLIFileWriter.php CCLI file IO
src/MessageLibrary.php / MessagesFileReader.php / MessagesFileWriter.php Messages file IO
src/TimersLibrary.php / TimersFileReader.php / TimersFileWriter.php Timers file IO
src/StageLibrary.php / StageFileReader.php / StageFileWriter.php Stage file IO
src/WorkspaceLibrary.php / WorkspaceFileReader.php / WorkspaceFileWriter.php Workspace file IO
src/PropLibrary.php / PropsFileReader.php / PropsFileWriter.php Props file IO
src/TestPatternsLibrary.php / TestPatternsFileReader.php / TestPatternsFileWriter.php TestPatterns file IO
src/CalendarLibrary.php / CalendarFileReader.php / CalendarFileWriter.php Calendar file IO
src/KeyMappingsLibrary.php / KeyMappingsFileReader.php / KeyMappingsFileWriter.php KeyMappings file IO
src/CommunicationDevicesLibrary.php / CommunicationDevicesFileReader.php / CommunicationDevicesFileWriter.php CommunicationDevices JSON file IO

CLI Tools

# Songs / playlists / bundles
php bin/parse-song.php path/to/song.pro
php bin/parse-playlist.php path/to/playlist.proplaylist

# Global library files
php bin/parse-macros.php path/to/Macros
php bin/parse-labels.php path/to/Labels
php bin/parse-groups.php path/to/Groups
php bin/parse-clear-groups.php path/to/ClearGroups
php bin/parse-ccli.php path/to/CCLI
php bin/parse-messages.php path/to/Messages
php bin/parse-timers.php path/to/Timers
php bin/parse-stage.php path/to/Stage
php bin/parse-workspace.php path/to/Workspace
php bin/parse-props.php path/to/Props
php bin/parse-test-patterns.php path/to/TestPatterns
php bin/parse-calendar.php path/to/Calendar
php bin/parse-key-mappings.php path/to/KeyMappings
php bin/parse-communication-devices.php path/to/CommunicationDevices

# Theme folder
php bin/parse-theme.php path/to/ThemeFolder