UnifiedPlaylist

A Unified Reader of playlist formats. Supports all popular playlist file formats and all their features.

1. Features
2. Installation
3. Usage - Advanced usage
4. Formats

Features

• Support for all popular formats and their variants: aimppl (and aimppl4), asx, xspf, zpl, m3u (and m3u8), pls, upf.
• Unified interface to all data
• Easy work with track data: just treat the class as an array of Track objects (support for iteration over class)
• Support for all additional track data (length, bitrate, file size, genre, release year and so on)
• Support reading and writing of all formats (writing support is in progress)
• White and black lists of formats

Installation

Install package via composer:

composer require wapmorgan/unified-playlist

Usage

Firsly, check that file looks like a playlist. Then, try to open it with open() static method. In case of success it will return an instance of UnifiedPlaylist with all needed information.

use wapmorgan\UnifiedPlaylist\UnifiedPlaylist;

if (UnifiedPlaylist::isPlaylist($tmpfile)) {
    $playlist = UnifiedPlaylist::open($tmpfile);
    /// ... operations here
}

Available operations:

1. Reading a Playlist. If you work with an instance of UnifiedPlaylist like with an array, it will contain all information about tracks as `Track` objects. (For detailed information about all `Track` fields and methods see section below)

   if (UnifiedPlaylist::isPlaylist($tmpfile)) {
       $playlist = UnifiedPlaylist::open($tmpfile);
   
       foreach ($playlist as $track) {
           echo $track->artist . ' - ' . $track->song.PHP_EOL.' ('.$track->formatDuration().')';
       }
   }
   
   // Information about all playlist like title, duration of size
   echo 'Title: '.$playlist->getTitle().PHP_EOL;
   echo 'Total playlist duration: '.$playlist->formatTotalDuration().PHP_EOL;
   echo 'Total playlist size: '.$playlist->getTotalSize().PHP_EOL;
   

2. Creating a playlist
   $playlist = new UnifiedPlaylist();
   $playlist[] = (new Track('filename.mp3'))->set('duration', 10)->set('artist', 'Abba')->set('song', 'Happy new year');
   $playlist->save('Playlist.m3u');
   

3. Modifying a playlist
   $playlist = UnifiedPlaylist::open($tmpfile);
   foreach ($playlist as $i => $track) {
       $track->genre = 'Pop';
       $playlist[$i] = $track;
   }
   $playlist->save('Edited.m3u');
   

API

UnifiedPlaylist

Method | Description ----------------------------------------|---------------------------------------------------------------------------------------------- @isPlaylist($filename): boolean | Checks that file format is one of supporting @isAllowed($filename): boolean | Checks white and black lists for restrictions about specified format @open($filename): UnifiedPlaylist | Opens a playlist and returns a UnifiedPlaylist instance getTitle(): string | Returns title of playlist, if present getTotalTracks(): integer | Returns number of tracks in playlist getTotalDuration(): integer | Returns total duration of tracks in playlist getTotalSize(): integer | Returns total size of playlist, if present formatTotalDuration($format = 'auto'): string | Returns formatted duration of playlist. Format can be: m:s, h:m:s or h:m. If auto, the best format will be used. save($filename[, $format]): boolean | Saves the playlist

Track

All available properties (real information can be nulled due to format limitations or generator configuration):

Property | Description -----------------|---------- string $url | File path if file or an url if stream string $artist | Artist of track string $song | Track name string $album | Album of track string $genre | Genre of track int $year | Year of track int $bitrate | Track bitrate (in kb/s) int $samplerate| Track samplerate (in Hz) int $duration | Track duration (in seconds)

Method | Description -----------------------------------|---------------------------------------------------------------------------------------------- formatDuration($format = 'auto') | Formats tracks duration as m:s, h:m:s or h:m. If auto, the best format will be used. isStream() | Checks if track is a network stream

Advanced usage

White and black lists

You can limit the list of formats that will be supported by your service. To allow the use of certain formats, use the whitelist:

UnifiedPlaylist::$whiteList = array(UnifiedPlaylist::M3U, UnifiedPlaylist::PLS);

To prohibit the use of certain formats, use the blacklist. All other formats will be allowed to use:

UnifiedPlaylist::$blackList = array(UnifiedPlaylist::ASX);

Now, it's important to properly handle the situation when a user tries to open a playlist of a prohibited format. In this case, the isAllowed() method returns false:

use wapmorgan\UnifiedPlaylist\FormatRestrictionException;
use wapmorgan\UnifiedPlaylist\UnifiedPlaylist;

UnifiedPlaylist::$blackList = array(UnifiedPlaylist::ASX);

if (UnifiedPlaylist::isPlaylist($tmpfile)) {
    if (UnifiedPlaylist::isAllowed($tmpfile)) {
        $playlist = UnifiedPlaylist::open($tmpfile);

        /// ... import operations here

    } else {
        echo 'Sorry, but we don\'t support this format. Please, try another.'.PHP_EOL;
    }
}

Formats

| Format | aimppl | asx | xpl | xspf | zpl | m3u | pls | upf | |----------|--------|-----|-----|------|-----|-----|-----|-----| | Reading | + | + | - | + | + | + | + | + | | Writing | + | + | - | - | - | + | - | - |