propresenter-php/AGENTS.md

Analyze a file format of a song.

Spec

File: ./Test.pro (file ext are always .pro)

• every song contains parts (name group here) (here: Verse 1, Verse 2, Chorus, ...) but could be any name
• every group contains 1-x slides
• every song contains different arrangements (here normal and test2) that defines the existence and the order of the groups
• every slide CAN have another textbox which contains a translated version of the first textbox

Status

1. Analyse the file structure and find all of the described specs.
2. Test and verify if the definition is correct - there is a all-songs directory with lot of examples.
3. Describe the structure for future AI prompts to use these files in spec/pp_song_spec.md and describe the usage in the AGENTS.md (replace obsolete commands)
4. Write a PHP module (is later used in laravel) in ./php which can parse a song and let get/set every aspect of structure. Use Objects here (Song, Group, Slide, Arrangement, etc)
5. Create a simple PHP cli tool, which receive a param with a song file and show the structure of the song.

PHP Module Usage

The ProPresenter song parser is available as a PHP module in ./php. Use it to read, parse, and modify .pro song files.

Reading a Song

use ProPresenter\Parser\ProFileReader;
use ProPresenter\Parser\ProFileWriter;

$song = ProFileReader::read('path/to/song.pro');

Accessing Song Structure

// Basic song info
echo $song->getName();        // Song name
echo $song->getUuid();        // Song UUID

// Groups (song parts like Verse 1, Chorus, etc.)
foreach ($song->getGroups() as $group) {
    echo $group->getName();   // "Verse 1", "Chorus", etc.
    $slides = $song->getSlidesForGroup($group);
    foreach ($slides as $slide) {
        echo $slide->getPlainText();
        if ($slide->hasTranslation()) {
            echo $slide->getTranslation()->getPlainText();
        }
    }
}

// Arrangements (different song orderings)
foreach ($song->getArrangements() as $arr) {
    $groups = $song->getGroupsForArrangement($arr);
    // Groups in arrangement order
}

Modifying and Writing

$song->setName("New Name");
ProFileWriter::write($song, 'output.pro');

CLI Tool

Parse and display song structure from the command line:

php php/bin/parse-song.php path/to/song.pro

Format Specification

For detailed information about the .pro file format, see spec/pp_song_spec.md.

Key Files

• php/src/Song.php — Top-level song wrapper
• php/src/Group.php — Group (song part) wrapper
• php/src/Slide.php — Slide wrapper with text access
• php/src/TextElement.php — Text element with label + plain text
• php/src/Arrangement.php — Arrangement wrapper
• php/src/RtfExtractor.php — RTF to plain text converter
• php/src/ProFileReader.php — Reads .pro files
• php/src/ProFileWriter.php — Writes .pro files
• php/bin/parse-song.php — CLI tool
• spec/pp_song_spec.md — Format specification