Audio collection API

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

These functions are for exploring the audio collection. PHP's array-manipulation functions can be used to do interesting things with the results. To understand the behaviour of these functions, consider the following example collection. There is one album with two tracks from two different artists, remixed by Dave Seaman, and an 80's track.

fileyeargenreproducerartistalbumTrack title
(not indexed)
101.mp31997DanceDave SeamanMidi BrotherhoodBack to Mine CD1The Superself
102.mp31997DanceDave SeamanCraig ArmstrongBack to Mine CD1Weather Storm
in_too_deep.mp31986RockGenesisInvisible TouchIn Too Deep

The function descriptions below will draw on this example. Notice that the Producer variable is empty for the soundtrack. It really only makes sense on remix albums, or a few soundtracks.

* array biys_list_files()

* array biys_list_genres()
* array biys_list_producers()
* array biys_list_artists()
* array biys_list_albums()
* array biys_list_years()

* array biys_xref_genre(string genre)
* array biys_xref_producer(string producer)
* array biys_xref_artist(string artist)
* array biys_xref_album(string album)
* array biys_xref_year(string year)


* array biys_get_attributes_for_path(string path)


array biys_list_files()

Returns an array with the full pathnames of all the audio tracks identified on the user's computer.

With the above example, this would return
( "/path/to/101.mp3", "/path/to/102.mp3", "/path/to/in_too_deep.mp3" )


array biys_list_genres()

Returns an array of genre names. This array will contain the list of all the distinct Genre names that occur in your collection. For the exmample, this would be a two-entry array: ("Dance", "Rock").

array biys_list_producers()

Returns an array of producer names. This array will contain the list of all the distinct Producers that occur in your collection. For the example, this would be a one-entry array: ("Dave Seaman").

array biys_list_artists()

Returns an array of artist names. This array will contain the list of all the Artists that occur in your collection. For the example, the return value can be two possible arrays:
  1. ("Dave Seaman", "Genesis") if the plugin is configured to have the Producer override the Author attribute if it's set.
  2. ("Midi Brotherhood", "Craig Armstrong", and "Genesis") otherwise

array biys_list_albums()

Returns an array of album names. This array will contain the list of all the Albums that occur in your collection. For the example, this will be a two-value array ("Invisible Touch", "Back to Mine CD1").

array biys_list_years()

Returns an array of years (rendered as strings). This array will contain the list of all the Years that occur in your collection. For the example, this will be a two-value array ("1986, 1997").

array biys_xref_genre(string genre)

This function performs a cross-reference on Genre, retrieving all the attributes which occur on files ion the same Genre.

The function returns a hash of arrays:

 
['matching'] - an array of the paths for the tracks that matched
['genre'][] - list of matching genres 
['year'][] - list of matching years 
['producer'][] - list of matching producers 
['album'][] - list of matching albums 
['arist'][] - list of matching artists 
In the scenario above, given the following code:
	$result = biys_xref_genre("Dance");

	# print_r is a built-in functions that prints out a variable
	# recursively: it dumps arrays, hashes, and scalars.
	print_r($result);
the output would be as follows:
Array 
( 
    [genre] => Array 
        ( 
            [0] => Dance
        ) 

    [artist] => Array 
        ( 
            [0] => Midi Brotherhood
            [1] => Craig Armstrong
        ) 

    [producer] => Array 
        ( 
            [0] => Dave Seaman
        ) 

    [album] => Array 
        ( 
            [0] => Back to Mine CD1
        ) 

    [matching] => Array
        (
        	[0] => /boot/home/music/101.mp3
        	[1] => /boot/home/music/102.mp3
        )
)

array biys_xref_producer(string producer)

* This function performs a cross-reference on the given Producer, retrieving all the attributes which occur on files by this Producer.

The function returns a hash of arrays as with biys_xref_genre. The output of this code:

	$result = biys_xref_producer("Dave Seaman");
	print_r($result);

would be
Array 
( 
    [genre] => Array 
        ( 
            [0] => Dance
        ) 

    [artist] => Array 
        ( 
            [0] => Midi Brotherhood
            [1] => Craig Armstrong
        ) 

    [producer] => Array 
        ( 
            [0] => Dave Seaman
        ) 

    [album] => Array 
        ( 
            [0] => Back to Mine CD1
        ) 

    [matching] => Array
        (
        	[0] => /boot/home/music/101.mp3
        	[1] => /boot/home/music/102.mp3
        )
)

array biys_xref_artist(string artist)

This function performs a cross-reference on the given Artist, retrieving all the attributes which occur on files by this Artist.

The function returns a hash of arrays as with biys_xref_genre. The output of this code:

	$result = biys_xref_artist("Geneis");
	print_r($result);
would be
Array 
( 
    [genre] => Array 
        ( 
            [0] => Rock
        ) 

    [artist] => Array 
        ( 
            [0] => Genesis
        ) 

    [producer] => Array 
        ( 
        ) 

    [album] => Array 
        ( 
            [0] => Invisible Touch
        ) 

    [matching] => Array
        (
        	[0] => /boot/home/music/in_too_deep.mp3
        )
)

array biys_xref_album(string album)

This function performs a cross-reference on the given Album, retrieving all the attributes which occur on files from the given Album.

The function returns a hash of arrays as with biys_xref_genre.


array biys_xref_year(string year)

This function performs a cross-reference on the given Year, retrieving all the attributes which occur on files from the given Year.

The function returns a hash of arrays as with biys_xref_genre.


array biys_get_attributes_for_path(string path)

See also biys_get_attributes_for_id.

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. Common attributes include:

Using the results of the function is easy:
	$trivia = biys_get_attributes_for_path("/boot/blah/test.mp3");
	print "The genre is ".$trivia['Audio:Genre']." and the song's play time is ";
	print $trivia['Audio:Length'];
Note that you're not just restricted to retrieving the attributes for audio tracks. You could examine the attributes of e-mail or People files if you felt like it.

next: closing notes