Playlist API

for skins.
Intro | PHP
APIs: Playlist | Playback | Collection


* int biys_count_playlists()
* int biys_create_playlist()
* void biys_remove_playlist(int playlist=0)
* void biys_clear(int playlist=0)
* void biys_shuffle(int playlist=0)
* void biys_sort(int playlist=0)

* void biys_add(string path, int index=-1, int playlist=0)
* int biys_count(int playlist=0)
* int biys_get_id_for_index(int index, int playlist=0)
* void biys_remove(int ID, int playlist=0)

* string biys_get_path(int ID, int playlist=0)
* string biys_get_name(int ID, int playlist=0)
* void biys_set_name(int ID, string newName, int playlist=0)
* array biys_get_attributes_for_id(int ID, int playlist=0)
* array biys_get_trivia_for_id(int ID, int playlist=0)


int biys_count_playlists()

Returns the number of playlists that are created right now. This may be zero if there is no playlist.

int biys_create_playlist()

Creates a new playlist and returns its index. Returns -1 on failure.

Example:

	if (biys_count_playlists()==0) {
		# No playlists around, so I'll make one.
		$newlist = biys_create_playlist();
		biys_add("/boot/home/favourite.mp3", $newlist);
	}

void biys_remove_playlist(int playlist=0)

Removes the given playlist from SoundPlay.

void biys_clear(int playlist=0)

Clears the given playlist of all files, but does not remove it.

void biys_shuffle(int playlist=0)

Shuffles the files in the playlist.

void biys_sort(int playlist=0)

Sorts the playlist alphabetically by name.

void biys_add(string path, int index=-1, int playlist=0)

Adds a file, directory, or Shoutcast URL to the playlist. If index is given, the item is inserted at the given index within the playlist.

The notation means three ways to call this function:

	## one parameter version
	# The following specify only the path.  The track will be appended
	# to the first playlist (i.e. playlist 0).
	biys_add("/boot/home/media/mp3/file.mp3/");  # adds a file
	biys_add("/boot/home/media/mp3/");           # adds everything under that directory
	biys_add("http://24.112.37.89:8080/");       # adds a shoutcast URL

	## two-parameter version
	# The following specify the path and the index.  The first playlist will
	# be affected (i.e. playlist 0).
	biys_add("file.mp3", 0);              # adds a file at the top of the playlist
	biys_add("directory", 1);             # adds a directory's contents at the second-from-the-top slot
	
	## three-parameter version
	# The following specify everything.
	biys_add("http://beosradio.com/", -1, 4);     # appends to playlist 4
	biys_add("file.mp3", 0, 2);                   # at the top of playlist 2

int biys_count(int playlist=0)

Returns the number of items in the playlist, or zero if there aren't any.

int biys_get_id_for_index(int index, int playlist=0)

Returns the ID of a file at the given index. Returns -1 if the index doesn't exist. This function is essential for obtaining the ID of a file, which is used to manipulate it with the functions that follow.
	$id = biys_get_id_for_index(0);     # gets the ID of the first file
	biys_play_file($id);                # ... and start it playing

void biys_remove(int ID, int playlist=0)

Removes an entry from the playlist.

string biys_get_path(int ID, int playlist=0)

Gets the full path name or Shoutcast address of the given entry.
	biys_add("/boot/file.mp3", 0);     # put the file at the top
	$id = biys_get_id_for_index(0);    # get its ID
	$path = biys_get_path($id);        # $path is now "/boot/file.mp3".

string biys_get_name(int ID, int playlist=0)

Initially, this is the leaf filename or URL of the playlist entry.
	biys_add("/boot/file.mp3", 0);     # put the file at the top
	$id = biys_get_id_for_index(0);    # get its ID
	$name = biys_get_name($id);        # $path is now "file.mp3".

void biys_set_name(int ID, string newName, int playlist=0)

Changes the name SoundPlay reports for the file: this affects sorting and any filename displays. It does not change the file's filename in the filesystem.

array biys_get_attributes_for_id(int ID, int playlist=0)

This function will also retrieve all the BFS attributes it can for the file, and include them verbatim in a PHP hash. It understands string, integer, and floating-point attributes, and will copy up to 65,536 bytes of information out of each attribute and into php land. It is similar to get_attributes_for_path except it takes an ID from the playlist instead of a path name.

array biys_get_trivia_for_id(int ID, int playlist=0)

Returns an associative array with all kinds of audio trivia about the named file. There is a guaranteed amount of information provided by SoundPlay, plus whatever BFS attributes are available.

Watch out! This function can cause the SoundPlay playback to break up if you call it too frequently. Calling it once per file for a long list of files will disrupt playback.
keymeaning
nameThe url or path to the song
pretty_nameThe name given to the track by biys_set_name(), if any.
mimetypeThe MIME type of the track, e.g. "audio/x-mpeg"
pretty_typeA pretty rendition of the track's type, e.g. "pretty_mimetype = mpeg layer 3, 192kb, stereo"
samplerateThe number of samples per second in the track. e.g. 44100
bitrateThe bitrate of the track or stream, e.g. 192000
numchannelsThe number of audio channels in the track, e.g. 2.
granularity??
framcountNumber of frames in the file. framecount divided by samplerate = play length (in seconds)
samplesize??
byteorder??
sampleformat??
In addition, this function will also retrieve all the BFS attributes it can for the file, and include them verbatim. It understands string, integer, and floating-point attributes, and will copy up to 65,536 bytes of information out of each attribute and into PHP_land. Common attributes include:
  • Audio:Length = 08:25
  • Audio:Bitrate = 192 kbit
  • Audio:Track = 1
  • Audio:Artist = underworld
  • Audio:Title = cups
  • Audio:Album = GU014 Hong Kong CD1
  • Audio:Genre = Global Underground
  • Audio:Year = 1999
  • Audio:Producer = John Digweed
Using the results of the function is easy:

	$trivia = biys_get_trivia($id);
	print "The bit rate is ".$trivia['bitrate']." and there are ";
	print $trivia['channels']." audio channels.";
See also biys_get_attributes_for_path.

next: managing playback