# 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) |
| 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) |
| 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)

### 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)

### 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
├── 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

```bash
# 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
```