157740c072
- Record final project status in learnings.md - Add all task evidence files (43 files) - Add work plan with all 29 checkboxes complete - Add boulder state tracking Project complete: 99 tests passing, all deliverables verified
102 lines
2.8 KiB
Plaintext
102 lines
2.8 KiB
Plaintext
# ProPresenter Playlist Parser
|
|
|
|
Analyze and manage .proplaylist files.
|
|
|
|
## Spec
|
|
|
|
File: ./Test.proplaylist (file ext are always .proplaylist)
|
|
|
|
- every playlist is a ZIP archive containing metadata and embedded songs
|
|
- every playlist contains entries (songs or groups) with type-specific data
|
|
- entries can reference embedded songs or external song files
|
|
- songs are lazily parsed on demand to optimize performance
|
|
- playlists support custom metadata (name, notes, etc.)
|
|
|
|
## PHP Module Usage
|
|
|
|
The ProPresenter playlist parser is available as a PHP module in `./php`. Use it to read, parse, and modify .proplaylist files.
|
|
|
|
### Reading a Playlist
|
|
|
|
```php
|
|
use ProPresenter\Parser\ProPlaylistReader;
|
|
use ProPresenter\Parser\ProPlaylistWriter;
|
|
|
|
$archive = ProPlaylistReader::read('path/to/playlist.proplaylist');
|
|
```
|
|
|
|
### Accessing Playlist Structure
|
|
|
|
```php
|
|
// Basic playlist info
|
|
echo $archive->getName(); // Playlist name
|
|
echo $archive->getUuid(); // Playlist UUID
|
|
|
|
// Metadata
|
|
echo $archive->getNotes(); // Playlist notes
|
|
|
|
// Entries (songs or groups)
|
|
foreach ($archive->getEntries() as $entry) {
|
|
echo $entry->getType(); // 'song' or 'group'
|
|
echo $entry->getName(); // Entry name
|
|
echo $entry->getUuid(); // Entry UUID
|
|
|
|
// For song entries
|
|
if ($entry->getType() === 'song') {
|
|
echo $entry->getPath(); // File path or embedded reference
|
|
|
|
// Lazy-load embedded song
|
|
if ($entry->isEmbedded()) {
|
|
$song = $archive->getEmbeddedSong($entry);
|
|
echo $song->getName();
|
|
foreach ($song->getGroups() as $group) {
|
|
echo $group->getName();
|
|
}
|
|
}
|
|
}
|
|
|
|
// For group entries
|
|
if ($entry->getType() === 'group') {
|
|
$children = $entry->getChildren();
|
|
foreach ($children as $child) {
|
|
echo $child->getName();
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Modifying and Writing
|
|
|
|
```php
|
|
$archive->setName("New Playlist Name");
|
|
$archive->setNotes("Updated notes");
|
|
ProPlaylistWriter::write($archive, 'output.proplaylist');
|
|
```
|
|
|
|
### Generating a New Playlist
|
|
|
|
```php
|
|
use ProPresenter\Parser\ProPlaylistGenerator;
|
|
|
|
$archive = ProPlaylistGenerator::generate(
|
|
'Playlist Name',
|
|
[
|
|
['type' => 'song', 'name' => 'Song 1', 'path' => 'file:///path/to/song1.pro'],
|
|
['type' => 'group', 'name' => 'Group 1', 'children' => [
|
|
['type' => 'song', 'name' => 'Song 2', 'path' => 'file:///path/to/song2.pro'],
|
|
['type' => 'song', 'name' => 'Song 3', 'path' => 'file:///path/to/song3.pro'],
|
|
]],
|
|
],
|
|
['notes' => 'Sunday Service']
|
|
);
|
|
|
|
// Or generate and write in one call
|
|
ProPlaylistGenerator::generateAndWrite('output.proplaylist', 'Playlist Name', $entries, $metadata);
|
|
```
|
|
|
|
## CLI Tool
|
|
|
|
Parse and display playlist structure from the command line:
|
|
|
|
```bash
|