A unified reader and writer of playlist formats (aimppl, asx, xspf, zpl, m3u, pls, upf)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
src
tests
.travis.yml
LICENSE
README.md
_config.yml
composer.json

README.md

UnifiedPlaylist

Composer package Latest Stable Version Total Downloads Latest Unstable Version License Tests

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 + + - - - + - -