From 0b3d7776b4f7ae6d641d396c9b9ef0a82e0738bd Mon Sep 17 00:00:00 2001 From: Stephan Schmidt Date: Mon, 28 Jun 2004 19:45:37 +0000 Subject: [PATCH] initial commit of id3 documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@162257 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/id3/constants.xml | 74 ++++++ reference/id3/functions/id3_get_genre_id.xml | 72 ++++++ .../id3/functions/id3_get_genre_list.xml | 223 ++++++++++++++++++ .../id3/functions/id3_get_genre_name.xml | 70 ++++++ reference/id3/functions/id3_get_tag.xml | 91 +++++++ reference/id3/functions/id3_get_version.xml | 83 +++++++ reference/id3/functions/id3_remove_tag.xml | 85 +++++++ reference/id3/functions/id3_set_tag.xml | 142 +++++++++++ reference/id3/reference.xml | 68 ++++++ 9 files changed, 908 insertions(+) create mode 100644 reference/id3/constants.xml create mode 100644 reference/id3/functions/id3_get_genre_id.xml create mode 100644 reference/id3/functions/id3_get_genre_list.xml create mode 100644 reference/id3/functions/id3_get_genre_name.xml create mode 100644 reference/id3/functions/id3_get_tag.xml create mode 100644 reference/id3/functions/id3_get_version.xml create mode 100644 reference/id3/functions/id3_remove_tag.xml create mode 100644 reference/id3/functions/id3_set_tag.xml create mode 100644 reference/id3/reference.xml diff --git a/reference/id3/constants.xml b/reference/id3/constants.xml new file mode 100644 index 0000000000..5f557ced5d --- /dev/null +++ b/reference/id3/constants.xml @@ -0,0 +1,74 @@ + + +
+ Predefined Constants + + Most of the id3 functions either let you specify + or return a tag version. In order to specify the version + please use on of these constants. + + + + + + ID3_V1_0 + (integer) + + + + ID3_V1_0 is used if you are working with + ID3 V1.0 tags. These tags may contain the fields title, artist, + album, genre, year and comment. + + + + + + ID3_V1_1 + (integer) + + + + ID3_V1_1 is used if you are working with + ID3 V1.1 tags. These tags may all information contained in v1.0 + tags plus the track number. + + + + + + ID3_V2 + (integer) + + + + ID3_V2 is used if you are working with + ID3 V2.x tags. These tags are quite flexible and are currently + not supported by the id3 extension. + + + + + +
+ + diff --git a/reference/id3/functions/id3_get_genre_id.xml b/reference/id3/functions/id3_get_genre_id.xml new file mode 100644 index 0000000000..f4f8309803 --- /dev/null +++ b/reference/id3/functions/id3_get_genre_id.xml @@ -0,0 +1,72 @@ + + + + + id3_get_genre_id + Get the id for a genre. + + + Description + + intid3_get_genre_name + stringgenre + + + id3_get_genre_id returns the if for a genre. If the + specified genre is not available in the genre list, id3_get_genre_id + will return &false; + + + Instead of a filename you may also pass a valid stream resource. + + + In an ID3 tag, the genre is stored using a integer ranging from 0 to + 147. + + + + <function>id3_get_genre_id</function> example + + +]]> + + + This will output: + + + + + + + + See also id3_get_genre_list and id3_get_genre_name. + + + + + diff --git a/reference/id3/functions/id3_get_genre_list.xml b/reference/id3/functions/id3_get_genre_list.xml new file mode 100644 index 0000000000..4b2c8e03c3 --- /dev/null +++ b/reference/id3/functions/id3_get_genre_list.xml @@ -0,0 +1,223 @@ + + + + + id3_get_genre_list + Get all possible genre values. + + + Description + + arrayid3_get_genre_list + void + + + id3_get_genre_list returns an array containing all + possible genres that may be stored in an ID3 tag. This list has been created + by Eric Kemp and later extended by WinAmp. + + + Instead of a filename you may also pass a valid stream resource. + + + This function is useful to provide you users a list of genres from which + they may choose one. When updating the ID3 tag you will always have to + specify the genre as an integer ranging from 0 to 147. + + + + <function>id3_get_genre_list</function> example + + +]]> + + + This will output: + + + Blues + [1] => Classic Rock + [2] => Country + [3] => Dance + [4] => Disco + [5] => Funk + [6] => Grunge + [7] => Hip-Hop + [8] => Jazz + [9] => Metal + [10] => New Age + [11] => Oldies + [12] => Other + [13] => Pop + [14] => R&B + [15] => Rap + [16] => Reggae + [17] => Rock + [18] => Techno + [19] => Industrial + [20] => Alternative + [21] => Ska + [22] => Death Metal + [23] => Pranks + [24] => Soundtrack + [25] => Euro-Techno + [26] => Ambient + [27] => Trip-Hop + [28] => Vocal + [29] => Jazz+Funk + [30] => Fusion + [31] => Trance + [32] => Classical + [33] => Instrumental + [34] => Acid + [35] => House + [36] => Game + [37] => Sound Clip + [38] => Gospel + [39] => Noise + [40] => Alternative Rock + [41] => Bass + [42] => Soul + [43] => Punk + [44] => Space + [45] => Meditative + [46] => Instrumental Pop + [47] => Instrumental Rock + [48] => Ethnic + [49] => Gothic + [50] => Darkwave + [51] => Techno-Industrial + [52] => Electronic + [53] => Pop-Folk + [54] => Eurodance + [55] => Dream + [56] => Southern Rock + [57] => Comedy + [58] => Cult + [59] => Gangsta + [60] => Top 40 + [61] => Christian Rap + [62] => Pop/Funk + [63] => Jungle + [64] => Native US + [65] => Cabaret + [66] => New Wave + [67] => Psychadelic + [68] => Rave + [69] => Showtunes + [70] => Trailer + [71] => Lo-Fi + [72] => Tribal + [73] => Acid Punk + [74] => Acid Jazz + [75] => Polka + [76] => Retro + [77] => Musical + [78] => Rock & Roll + [79] => Hard Rock + [80] => Folk + [81] => Folk-Rock + [82] => National Folk + [83] => Swing + [84] => Fast Fusion + [85] => Bebob + [86] => Latin + [87] => Revival + [88] => Celtic + [89] => Bluegrass + [90] => Avantgarde + [91] => Gothic Rock + [92] => Progressive Rock + [93] => Psychedelic Rock + [94] => Symphonic Rock + [95] => Slow Rock + [96] => Big Band + [97] => Chorus + [98] => Easy Listening + [99] => Acoustic + [100] => Humour + [101] => Speech + [102] => Chanson + [103] => Opera + [104] => Chamber Music + [105] => Sonata + [106] => Symphony + [107] => Booty Bass + [108] => Primus + [109] => Porn Groove + [110] => Satire + [111] => Slow Jam + [112] => Club + [113] => Tango + [114] => Samba + [115] => Folklore + [116] => Ballad + [117] => Power Ballad + [118] => Rhytmic Soul + [119] => Freestyle + [120] => Duet + [121] => Punk Rock + [122] => Drum Solo + [123] => Acapella + [124] => Euro-House + [125] => Dance Hall + [126] => Goa + [127] => Drum & Bass + [128] => Club-House + [129] => Hardcore + [130] => Terror + [131] => Indie + [132] => BritPop + [133] => Negerpunk + [134] => Polsk Punk + [135] => Beat + [136] => Christian Gangsta + [137] => Heavy Metal + [138] => Black Metal + [139] => Crossover + [140] => Contemporary C + [141] => Christian Rock + [142] => Merengue + [143] => Salsa + [144] => Thrash Metal + [145] => Anime + [146] => JPop + [147] => SynthPop +) +]]> + + + + + See also id3_get_genre_name and id3_get_genre_id. + + + + + diff --git a/reference/id3/functions/id3_get_genre_name.xml b/reference/id3/functions/id3_get_genre_name.xml new file mode 100644 index 0000000000..d9275843ca --- /dev/null +++ b/reference/id3/functions/id3_get_genre_name.xml @@ -0,0 +1,70 @@ + + + + + id3_get_genre_name + Get the name for a genre id. + + + Description + + stringid3_get_genre_name + intgenre_id + + + id3_get_genre_name returns the name for a genre id. + + + Instead of a filename you may also pass a valid stream resource. + + + In an ID3 tag, the genre is stored using a integer ranging from 0 to + 147. + + + + <function>id3_get_genre_name</function> example + + +]]> + + + This will output: + + + + + + + + See also id3_get_genre_list and id3_get_genre_id. + + + + + diff --git a/reference/id3/functions/id3_get_tag.xml b/reference/id3/functions/id3_get_tag.xml new file mode 100644 index 0000000000..c08bcfbf39 --- /dev/null +++ b/reference/id3/functions/id3_get_tag.xml @@ -0,0 +1,91 @@ + + + + + id3_get_tag + Get all information stored in an ID3 tag + + + Description + + arrayid3_get_tag + stringfilename + intversion + + + id3_get_tag is used to get all information stored + in the id3 tag of the specified file. + + + Instead of a filename you may also pass a valid stream resource. + + + The optional version parameter allows you to + specify the version of the tag as MP3 files may contain both, version 1.x and + version 2.x tags. + + + + <function>id3_get_tag</function> example + + +]]> + + + This will output something like: + + + DN-38416 + [artist] => Re:\Legion + [album] => Reflections + [year] => 2004 + [genre] => 19 +) +]]> + + + + + + Currently id3_get_tag only supports + version 1.0 and 1.1. + + + + The key genre will contain an integer between 0 and 147. You may + use id3_get_genre_name to convert it to a human readable string. + + + See also id3_set_tag, + id3_remove_tag and id3_get_version. + + + + + diff --git a/reference/id3/functions/id3_get_version.xml b/reference/id3/functions/id3_get_version.xml new file mode 100644 index 0000000000..5122be638b --- /dev/null +++ b/reference/id3/functions/id3_get_version.xml @@ -0,0 +1,83 @@ + + + + + id3_get_version + Get version of an ID3 tag + + + Description + + intid3_get_version + stringfilename + + + id3_get_version retrieves the version(s) of the ID3 tag(s) in + the MP3 file. As a tag can contain ID3 v1.x and v2.x tags, the return value of this + function should be bitwise compared with the predefined constants ID3_V1_0, + ID3_V1_1 and ID3_V2. + + + Instead of a filename you may also pass a valid stream resource. + + + + <function>id3_get_version</function> example + + +]]> + + + This will output something like: + + + + + + + + If a file contains an ID3 v1.1 tag, it always contains + a 1.0 tag, as version 1.1 is just an extension of 1.0. + + + See also id3_get_tag, id3_set_tag and + id3_remove_tag. + + + + + diff --git a/reference/id3/functions/id3_remove_tag.xml b/reference/id3/functions/id3_remove_tag.xml new file mode 100644 index 0000000000..cb6ff3acbf --- /dev/null +++ b/reference/id3/functions/id3_remove_tag.xml @@ -0,0 +1,85 @@ + + + + + id3_remove_tag + Remove an existing ID3 tag + + + Description + + boolid3_remove_tag + stringfilename + intversion + + + id3_remove_tag is used to remove the information stored + of an ID3 tag. If no tag has been present, it will return false and leave the file + as it was. + + + Instead of a filename you may also pass a valid stream resource. + + + The optional version parameter allows you to + specify the version of the tag as MP3 files may contain both, version 1.x and + version 2.x tags. + + + + <function>id3_remove_tag</function> example + + +]]> + + + If the file is writeable and contained a 1.0 tag, this will output: + + + + + + + + + Currently id3_remove_tag only supports + version 1.0 and 1.1. If you choose to remove a 1.0 tag and the file + contains a 1.1 tag, this tag will be removed, as v1.1 is only an + extension of 1.0. + + + + See also id3_get_tag, + id3_set_tag and id3_get_version. + + + + + diff --git a/reference/id3/functions/id3_set_tag.xml b/reference/id3/functions/id3_set_tag.xml new file mode 100644 index 0000000000..47f8aaf090 --- /dev/null +++ b/reference/id3/functions/id3_set_tag.xml @@ -0,0 +1,142 @@ + + + + + id3_set_tag + Update information stored in an ID3 tag + + + Description + + boolid3_set_tag + stringfilename + arraytag + intversion + + + id3_set_tag is used to change the information stored + of an ID3 tag. If no tag has been present, it will be added to the file. + + + Instead of a filename you may also pass a valid stream resource. + + + The optional version parameter allows you to + specify the version of the tag as MP3 files may contain both, version 1.x and + version 2.x tags. + + + + <function>id3_set_tag</function> example + + "Re:Start", + "artist" => "Re:\Legion", + "comment" => "A nice track" + ); +$result = id3_set_tag( "path/to/example.mp3", $data, ID3_V1_0 ); +if ($result === true) { + echo "Tag succesfully updated\n"; +} +?> +]]> + + + If the file is writeable, this will output: + + + + + + + + + Currently id3_set_tag only supports + version 1.0 and 1.1. + + + + The following keys may be used in the associative array: + + + + Keys in the associative array + + + + key + possible value + available in version + + + + + title + string with maximum of 30 characters + v1.0, v1.1 + + + artist + string with maximum of 30 characters + v1.0, v1.1 + + + album + string with maximum of 30 characters + v1.0, v1.1 + + + year + 4 digits + v1.0, v1.1 + + + genre + integer value between 0 and 147 + v1.0, v1.1 + + + comment + string with maximum of 30 characters (28 in v1.1) + v1.0, v1.1 + + + track + integer between 0 and 255 + v1.1 + + + +
+ + + See also id3_get_tag, + id3_remove_tag and id3_get_version. + + + + + diff --git a/reference/id3/reference.xml b/reference/id3/reference.xml new file mode 100644 index 0000000000..9c54eb9108 --- /dev/null +++ b/reference/id3/reference.xml @@ -0,0 +1,68 @@ + + + + ID3 Functions + id3 + + +
+ &reftitle.intro; + + These functions let you read and manipulate ID3 tags. + ID3 tags are used in MP3 files to store title of the song, as well + as information about the artist, album, genre, year and track + number. + +
+ +
+ &reftitle.required; + &no.requirement; +
+ +
+ &reftitle.install; + + id3 is part of PECL and can be installed using the PEAR installer. + To compile PHP with id3 support, downloadthe sourcecode, put it in + php-src/ext/id3 and compile PHP using --enable-id3. + +
+ +
+ &reftitle.runtime; + &no.config; +
+ +
+ &reftitle.resources; + &no.resource; +
+ + &reference.id3.constants; + + +&reference.id3.functions; + + + +