22ba4aff7d
- Move src/, tests/, bin/, generated/, proto/, composer.json, composer.lock, phpunit.xml from php/ to repo root - Move ref/ to doc/reference_samples/ for better organization - Remove vendor/ from git tracking (now properly gitignored) - Update all test file paths (dirname adjustments and ref/ -> doc/reference_samples/) - Update all documentation paths (AGENTS.md, doc/*.md) - Remove php.bak/ directory - All 252 tests pass
136 lines
4.7 KiB
Markdown
136 lines
4.7 KiB
Markdown
# 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](api/song.md) |
|
|
| Parse/modify `.proplaylist` files | [api/playlist.md](api/playlist.md) |
|
|
| Parse/modify `.probundle` files | [api/bundle.md](api/bundle.md) |
|
|
| Understand `.pro` binary format | [formats/pp_song_spec.md](formats/pp_song_spec.md) |
|
|
| Understand `.proplaylist` format | [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) |
|
|
| Understand `.probundle` format | [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) |
|
|
| Add new documentation | [CONTRIBUTING.md](CONTRIBUTING.md) |
|
|
| Search by keyword | [keywords.md](keywords.md) |
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
### File Format Specifications
|
|
- [formats/pp_song_spec.md](formats/pp_song_spec.md) — ProPresenter 7 `.pro` file format (protobuf structure, RTF handling, field reference)
|
|
- [formats/pp_playlist_spec.md](formats/pp_playlist_spec.md) — ProPresenter 7 `.proplaylist` file format (ZIP64 container, item types)
|
|
- [formats/pp_bundle_spec.md](formats/pp_bundle_spec.md) — ProPresenter 7 `.probundle` file format (ZIP container, media assets)
|
|
|
|
### PHP API Documentation
|
|
- [api/song.md](api/song.md) — Song parser API (read, modify, generate `.pro` files)
|
|
- [api/playlist.md](api/playlist.md) — Playlist parser API (read, modify, generate `.proplaylist` files)
|
|
- [api/bundle.md](api/bundle.md) — Bundle parser API (read, write `.probundle` files with media)
|
|
|
|
### Internal Reference
|
|
- [internal/learnings.md](internal/learnings.md) — Development learnings and conventions discovered
|
|
- [internal/decisions.md](internal/decisions.md) — Architectural decisions and rationale
|
|
- [internal/issues.md](internal/issues.md) — Known issues and edge cases
|
|
|
|
### Meta
|
|
- [keywords.md](keywords.md) — Searchable keyword index
|
|
- [CONTRIBUTING.md](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
|
|
└── 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 |
|
|
|
|
### CLI Tools
|
|
|
|
```bash
|
|
# 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
|
|
```
|