propresenter-php/doc/INDEX.md

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 the global Macros file	api/macros.md
Read the global Labels file	api/labels.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

• formats/pp_song_spec.md — ProPresenter 7 .pro file format (protobuf structure, RTF handling, field reference)
• formats/pp_playlist_spec.md — ProPresenter 7 .proplaylist file format (ZIP64 container, item types)
• formats/pp_bundle_spec.md — ProPresenter 7 .probundle file format (ZIP container, media assets)

PHP API Documentation

• 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/macros.md — Macros library API (read the global Macros file)
• api/labels.md — Labels library API (read the global Labels file)

Internal Reference

• internal/learnings.md — Development learnings and conventions discovered
• internal/decisions.md — Architectural decisions and rationale
• internal/issues.md — Known issues and edge cases

Meta

• keywords.md — Searchable keyword index
• CONTRIBUTING.md — How to document new features

---

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
│   ├── macros.md
│   └── labels.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: "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

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/MacroLibrary.php	Macros library wrapper (read global Macros file)
src/MacrosFileReader.php	Read global Macros file
src/LabelLibrary.php	Labels library wrapper (read global Labels file)
src/LabelsFileReader.php	Read global Labels file

CLI Tools

# Parse and display song structure
php bin/parse-song.php path/to/song.pro

# Parse and display playlist structure
php bin/parse-playlist.php path/to/playlist.proplaylist

# Parse and display the global Macros file
php bin/parse-macros.php path/to/Macros

# Parse and display the global Labels file
php bin/parse-labels.php path/to/Labels