propresenter7-php-lib/AGENTS.md

ProPresenter Parser — Agent Instructions

Documentation

All project documentation lives in doc/. Load only what you need.

Start here: Read doc/INDEX.md for the table of contents and quick navigation.

How to Find What You Need

1. Check doc/INDEX.md for the topic overview
2. Use doc/keywords.md to search by keyword
3. Load the specific doc file — don't load everything

Common Tasks

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

Structure

doc/
├── INDEX.md           ← Start here (TOC + navigation)
├── keywords.md        ← Keyword search index
├── CONTRIBUTING.md    ← How to document new things
├── formats/           ← Binary file format specs
│   ├── pp_song_spec.md
│   ├── pp_playlist_spec.md
│   └── pp_bundle_spec.md
├── api/               ← PHP API docs (read/write/generate)
│   ├── song.md
│   ├── playlist.md
│   ├── bundle.md
│   ├── macros.md
│   └── labels.md
└── internal/          ← Dev notes (learnings, decisions, issues)
    ├── learnings.md
    ├── decisions.md
    └── issues.md

Project Overview

PHP tools for parsing, modifying, and generating ProPresenter 7 files:

• Songs (.pro) — Protobuf-encoded presentation files with lyrics, groups, slides, arrangements, translations
• Playlists (.proplaylist) — ZIP64 archives containing playlist metadata and embedded songs
• Bundles (.probundle) — ZIP archives containing a single presentation with embedded media assets
• Themes (folder with Theme + Assets/) — Template document plus media used as a slide theme
• Global library files (no extension) — Macros, Labels, Groups, ClearGroups, CCLI, Messages, Timers, Stage, Workspace, Props, TestPatterns, Calendar, KeyMappings (protobuf) and CommunicationDevices (JSON)

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 (one parser per type)
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

Key Source Files

All PHP source code is in src/. Generated protobuf classes are in generated/. Tests are in tests/.