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
Understand .pro binary format	formats/pp_song_spec.md
Understand .proplaylist format	formats/pp_playlist_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)

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)

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
├── api/               ← PHP API documentation
│   ├── song.md
│   └── playlist.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: "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/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

Key Components

File	Purpose
php/src/Song.php	Song wrapper (read/modify .pro files)
php/src/ProFileReader.php	Read .pro files
php/src/ProFileWriter.php	Write .pro files
php/src/ProFileGenerator.php	Generate .pro files from scratch
php/src/PlaylistArchive.php	Playlist wrapper (read/modify .proplaylist files)
php/src/ProPlaylistReader.php	Read .proplaylist files
php/src/ProPlaylistWriter.php	Write .proplaylist files
php/src/ProPlaylistGenerator.php	Generate .proplaylist files from scratch

CLI Tools

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

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