Thorsten Bus 4e1ac9b7ea feat(labels): add reader for global Labels file

Mirrors the Macros reader: LabelsFileReader -> LabelLibrary -> Label wraps
the protobuf ProLabelsDocument and exposes each label's name (the proto
'text' field) plus optional RGBA color with a #RRGGBB hex helper. Includes
CLI tool, PHPUnit suite against the bundled reference Labels sample, and
api/labels.md docs.

2026-05-03 20:53:45 +02:00

2.7 KiB

Raw Blame History

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

Check doc/INDEX.md for the topic overview
Use doc/keywords.md to search by keyword
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 the global `Macros` file	`doc/api/macros.md`
Read the global `Labels` file	`doc/api/labels.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
Macros (Macros, no extension) — Global protobuf-encoded macro library with collections
Labels (Labels, no extension) — Global protobuf-encoded label library (slide labels with optional UI colors)

CLI Tools

php bin/parse-song.php path/to/song.pro
php bin/parse-playlist.php path/to/playlist.proplaylist
php bin/parse-macros.php path/to/Macros
php bin/parse-labels.php path/to/Labels

Key Source Files

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

2.7 KiB Raw Blame History