1 getID3() by James Heinrich (<info@getid3.org>)
3 **Available at <http://getid3.sourceforge.net> or <http://www.getid3.org>**
5 getID3() is released under multiple licenses. You may choose from the following licenses, and use getID3 according to the terms of the license most suitable to your project.
9 * [v3](https://gnu.org/licenses/gpl.html)
11 * [v2](https://gnu.org/licenses/old-licenses/gpl-2.0.html)
13 * [v1](https://gnu.org/licenses/old-licenses/gpl-1.0.html)
17 * [v3](https://gnu.org/licenses/lgpl.html)
21 * [v2](http://www.mozilla.org/MPL/2.0/)
23 **getID3 Commercial License:**
25 * [gCL](http://getid3.org/#gCL) (payment required)
28 Copies of each of the above licenses are included in the `licenses/`
29 directory of the getID3 distribution.
31 If you want to donate, there is a link on <http://www.getid3.org> for PayPal donations.
38 **Q:** How can I check that getID3() works on my server/files?
40 **A:** Unzip getID3() to a directory, then access `/demos/demo.browse.php`
47 **Q:** I have a question, or I found a bug. What do I do?
49 **A:** The preferred method of support requests and/or bug reports is the forum at <http://support.getid3.org/>
53 Sourceforge Notification
56 It's highly recommended that you sign up for notification from
57 Sourceforge for when new versions are released. Please visit:
58 <http://sourceforge.net/project/showfiles.php?group_id=55859>
59 and click the little "monitor package" icon/link. If you're
60 previously signed up for the mailing list, be aware that it has
61 been discontinued, only the automated Sourceforge notification
62 will be used from now on.
66 What does getID3() do?
69 Reads & parses (to varying degrees):
74 * ID3v2 (v2.4, v2.3, v2.2)
80 * Ogg (Vorbis, OggFLAC, Speex, Opus)
109 * ASF: ASF, Windows Media Audio (WMA), Windows Media Video (WMV)
114 * NSV (Nullsoft Streaming Video)
115 * Quicktime (including MP4)
128 * ISO-9660 CD-ROM image (directory structure)
129 * SZIP (limited support)
130 * ZIP (directory structure)
137 * ID3v2 (v2.3 & v2.4)
138 * VorbisComment on OggVorbis
139 * VorbisComment on FLAC (not OggFLAC)
141 * Lyrics3 (delete only)
148 * PHP 4.2.0 up to 5.2.x for getID3() 1.7.x (and earlier)
149 * PHP 5.0.5 (or higher) for getID3() 1.8.x (and up)
150 * PHP 5.0.5 (or higher) for getID3() 2.0.x (and up)
151 * at least 4MB memory for PHP. 8MB or more is highly recommended.
152 12MB is required with all modules loaded.
159 See /demos/demo.basic.php for a very basic use of getID3() with no
160 fancy output, just scanning one file.
162 See structure.txt for the returned data structure.
164 **For an example of a complete directory-browsing, file-scanning implementation of getID3(), please run /demos/demo.browse.php**
166 See /demos/demo.mysql.php for a sample recursive scanning code that
167 scans every file in a given directory, and all sub-directories, stores
168 the results in a database and allows various analysis / maintenance
171 To analyze remote files over HTTP or FTP you need to copy the file
172 locally first before running getID3(). Your code would look something
178 // Copy remote file locally to scan with getID3()
179 $remotefilename = 'http://www.example.com/filename.mp3';
180 if ($fp_remote = fopen($remotefilename, 'rb')) {
181 $localtempfilename = tempnam('/tmp', 'getID3');
182 if ($fp_local = fopen($localtempfilename, 'wb')) {
183 while ($buffer = fread($fp_remote, 8192)) {
184 fwrite($fp_local, $buffer);
187 // Initialize getID3 engine
188 $getID3 = new getID3;
189 $ThisFileInfo = $getID3->analyze($localtempfilename);
190 // Delete temporary file
191 unlink($localtempfilename);
199 **See /demos/demo.write.php for how to write tags.**
201 What does the returned data structure look like?
206 It is recommended that you look at the output of
207 /demos/demo.browse.php scanning the file(s) you're interested in to
208 confirm what data is actually returned for any particular filetype in
209 general, and your files in particular, as the actual data returned
210 may vary considerably depending on what information is available in
220 If the format parser encounters a critical problem, it will return
221 something in `$fileinfo['error']`, describing the encountered error. If
222 a less critical error or notice is generated it will appear in
223 `$fileinfo['warning']`. Both keys may contain more than one warning or
224 error. If something is returned in ['error'] then the file was not
225 correctly parsed and returned data may or may not be correct and/or
226 complete. If something is returned in `['warning']` (and not `['error']`)
227 then the data that is returned is OK - usually getID3() is reporting
228 errors in the file that have been worked around due to known bugs in
229 other programs. Some warnings may indicate that the data that is
230 returned is OK but that some data could not be extracted due to
235 See above except errors are thrown (so you will only get one error).
240 getID3() has been tested on many systems, on many types of files,
241 under many operating systems, and is generally believe to be stable
242 and safe. That being said, there is still the chance there is an
243 undiscovered and/or unfixed bug that may potentially corrupt your
244 file, especially within the writing functions. By using getID3() you
245 agree that it's not my fault if any of your files are corrupted.
246 In fact, I'm not liable for anything :)
251 GNU General Public License - see license.txt
253 This program is free software; you can redistribute it and/or
254 modify it under the terms of the GNU General Public License
255 as published by the Free Software Foundation; either version 2
256 of the License, or (at your option) any later version.
258 This program is distributed in the hope that it will be useful,
259 but WITHOUT ANY WARRANTY; without even the implied warranty of
260 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
261 GNU General Public License for more details.
263 You should have received a copy of the GNU General Public License
264 along with this program; if not, write to:
265 Free Software Foundation, Inc.
266 59 Temple Place - Suite 330
267 Boston, MA 02111-1307, USA.
271 **Q:** Can I use getID3() in my program? Do I need a commercial license?
273 **A:** You're generally free to use getID3 however you see fit. The only
274 case in which you would require a commercial license is if you're
275 selling your closed-source program that integrates getID3. If you
276 sell your program including a copy of getID3, that's fine as long
277 as you include a copy of the sourcecode when you sell it. Or you
278 can distribute your code without getID3 and say "download it from
279 getid3.sourceforge.net"
283 Why is it called "getID3()" if it does so much more than just that?
286 v0.1 did in fact just do that. I don't have a copy of code that old, but I
287 could essentially write it today with a one-line function:
290 function getID3($filename) { return unpack('a3TAG/a30title/a30artist/a30album/a4year/a28comment/c1track/c1genreid', substr(file_get_contents($filename), -128)); }
297 <http://www.getid3.org/phpBB3/viewforum.php?f=7>
299 * Better support for MP4 container format
300 * Scan for appended ID3v2 tag at end of file per ID3v2.4 specs (Section 5.0)
301 * Support for JPEG-2000 (http://www.morgan-multimedia.com/jpeg2000_overview.htm)
302 * Support for MOD (mod/stm/s3m/it/xm/mtm/ult/669)
303 * Support for ACE (thanks Vince)
304 * Support for Ogg other than Vorbis, Speex and OggFlac (ie. Ogg+Xvid)
305 * Ability to create Xing/LAME VBR header for VBR MP3s that are missing VBR header
306 * Ability to "clean" ID3v2 padding (replace invalid padding with valid padding)
307 * Warn if MP3s change version mid-stream (in full-scan mode)
308 * check for corrupt/broken mid-file MP3 streams in histogram scan
309 * Support for lossless-compression formats
310 (http://www.firstpr.com.au/audiocomp/lossless/#Links)
311 (http://compression.ca/act-sound.html)
312 (http://web.inter.nl.net/users/hvdh/lossless/lossless.htm)
313 * Support for RIFF-INFO chunks
314 * http://lotto.st-andrews.ac.uk/~njh/tag_interchange.html
315 (thanks Nick Humfrey <njhØsurgeradio*co*uk>)
316 * http://abcavi.narod.ru/sof/abcavi/infotags.htm
318 * Better support for Bink video
319 * http://www.hr/josip/DSP/AudioFile2.html
320 * http://www.pcisys.net/~melanson/codecs/
330 * Support for EXE (comments, author, etc) (thanks p*quaedackersØplanet*nl)
331 * Support for DVD-IFO (region, subtitles, aspect ratio, etc)
332 (thanks p*quaedackersØplanet*nl)
333 * More complete support for SWF - parsing encapsulated MP3 and/or JPEG content
334 (thanks n8n8Øyahoo*com)
336 * Optional scan-through-frames for AVI verification
337 (thanks rockcohenØmassive-interactive*nl)
338 * Support for TTF (thanks infoØbutterflyx*com)
339 * Support for DSS (http://www.getid3.org/phpBB3/viewtopic.php?t=171)
340 * Support for SMAF (http://smaf-yamaha.com/what/demo.html)
341 http://www.getid3.org/phpBB3/viewtopic.php?t=182
342 * Support for AMR (http://www.getid3.org/phpBB3/viewtopic.php?t=195)
343 * Support for 3gpp (http://www.getid3.org/phpBB3/viewtopic.php?t=195)
344 * Support for ID4 (http://www.wackysoft.cjb.net grizlyY2KØhotmail*com)
345 * Parse XML data returned in Ogg comments
346 * Parse XML data from Quicktime SMIL metafiles (klausrathØmac*com)
347 * ID3v2 genre string creator function
348 * More complete parsing of JPG
349 * Support for all old-style ASF packets
350 * ASF/WMA/WMV tag writing
351 * Parse declared T??? ID3v2 text information frames, where appropriate
352 (thanks Christian Fritz for the idea)
354 http://www.guerillasoft.com/EncSpot2/index.html
355 http://ff123.net/identify.html
356 http://www.hydrogenaudio.org/?act=ST&f=16&t=9414
357 http://www.hydrogenaudio.org/?showtopic=11785
358 * Support for other OS/2 bitmap structures: Bitmap Array('BA'),
359 Color Icon('CI'), Color Pointer('CP'), Icon('IC'), Pointer ('PT')
360 http://netghost.narod.ru/gff/graphics/summary/os2bmp.htm
361 * Support for WavPack RAW mode
362 * ASF/WMA/WMV data packet parsing
363 * ID3v2FrameFlagsLookupTagAlter()
364 * ID3v2FrameFlagsLookupFileAlter()
365 * obey ID3v2 tag alter/preserve/discard rules
366 * http://www.geocities.com/SiliconValley/Sector/9654/Softdoc/Illyrium/Aolyr.htm
367 * proper checking for LINK/LNK frame validity in ID3v2 writing
368 * proper checking for ASPI-TLEN frame validity in ID3v2 writing
369 * proper checking for COMR frame validity in ID3v2 writing
370 * http://www.geocities.co.jp/SiliconValley-Oakland/3664/index.html
371 * decode GEOB ID3v2 structure as encoded by RealJukebox,
372 decode NCON ID3v2 structure as encoded by MusicMatch
373 (probably won't happen - the formats are proprietary)
377 Known Bugs/Issues in getID3() that may be fixed eventually
379 <http://www.getid3.org/phpBB3/viewtopic.php?t=25>
381 * Cannot determine bitrate for MPEG video with VBR video data
383 * Interlace/progressive cannot be determined for MPEG video
385 * MIDI playtime is sometimes inaccurate
386 * AAC-RAW mode files cannot be identified
387 * WavPack-RAW mode files cannot be identified
388 * mp4 files report lots of "Unknown QuickTime atom type"
390 * Encrypted ASF/WMA/WMV files warn about "unhandled GUID
391 ASF_Content_Encryption_Object"
392 * Bitrate split between audio and video cannot be calculated for
393 NSV, only the total bitrate. (need documentation)
394 * All Ogg formats (Vorbis, OggFLAC, Speex) are affected by the
395 problem of large VorbisComments spanning multiple Ogg pages, but
396 but only OggVorbis files can be processed with vorbiscomment.
397 * The version of "head" supplied with Mac OS 10.2.8 (maybe other
398 versions too) does only understands a single option (-n) and
399 therefore fails. getID3 ignores this and returns wrong md5_data.
403 Known Bugs/Issues in getID3() that cannot be fixed
405 <http://www.getid3.org/phpBB3/viewtopic.php?t=25>
407 * 32-bit PHP installations only:
408 Files larger than 2GB cannot always be parsed fully by getID3()
409 due to limitations in the 32-bit PHP filesystem functions.
410 NOTE: Since v1.7.8b3 there is partial support for larger-than-
411 2GB files, most of which will parse OK, as long as no critical
412 data is located beyond the 2GB offset.
414 * all file formats on 64-bit PHP
415 * ZIP (format doesn't support files >2GB)
416 * FLAC (current encoders don't support files >2GB)
418 * ID3v1 tags (always located at end-of-file)
419 * Lyrics3 tags (always located at end-of-file)
420 * APE tags (always located at end-of-file)
422 * Quicktime (will work if needed metadata is before 2GB offset,
423 that is if the file has been hinted/optimized for streaming)
424 * RIFF.WAV (should work fine, but gives warnings about not being
425 able to parse all chunks)
426 * RIFF.AVI (playtime will probably be wrong, is only based on
427 "movi" chunk that fits in the first 2GB, should issue error
428 to show that playtime is incorrect. Other data should be mostly
429 correct, assuming that data is constant throughout the file)
433 Known Bugs/Issues in other programs
435 <http://www.getid3.org/phpBB3/viewtopic.php?t=25>
437 * Windows Media Player (up to v11) and iTunes (up to v10+) do
438 not correctly handle ID3v2.3 tags with UTF-16BE+BOM
439 encoding (they assume the data is UTF-16LE+BOM and either
440 crash (WMP) or output Asian character set (iTunes)
441 * Winamp (up to v2.80 at least) does not support ID3v2.4 tags,
443 see: http://forums.winamp.com/showthread.php?postid=387524
444 * Some versions of Helium2 (www.helium2.com) do not write
445 ID3v2.4-compliant Frame Sizes, even though the tag is marked
446 as ID3v2.4) (detected by getID3())
447 * MP3ext V3.3.17 places a non-compliant padding string at the end
448 of the ID3v2 header. This is supposedly fixed in v3.4b21 but
449 only if you manually add a registry key. This fix is not yet
450 confirmed. (detected by getID3())
451 * CDex v1.40 (fixed by v1.50b7) writes non-compliant Ogg comment
452 strings, supposed to be in the format "NAME=value" but actually
453 written just "value" (detected by getID3())
454 * Oggenc 0.9-rc3 flags the encoded file as ABR whether it's
456 * iTunes (versions "X v2.0.3", "v3.0.1" are known-guilty, probably
457 other versions are too) writes ID3v2.3 comment tags using a
458 frame name 'COM ' which is not valid for ID3v2.3+ (it's an
459 ID3v2.2-style frame name) (detected by getID3())
460 * MP2enc does not encode mono CBR MP2 files properly (half speed
461 sound and double playtime)
462 * MP2enc does not encode mono VBR MP2 files properly (actually
464 * tooLAME does not encode mono VBR MP2 files properly (actually
466 * AACenc encodes files in VBR mode (actually ABR) even if CBR is
468 * AAC/ADIF - bitrate_mode = cbr for vbr files
469 * LAME 3.90-3.92 prepends one frame of null data (space for the
470 LAME/VBR header, but it never gets written) when encoding in CBR
472 * Ahead Nero encodes TwinVQF with a DSIZ value (which is supposed
473 to be the filesize in bytes) of "0" for TwinVQF v1.0 and "1" for
474 TwinVQF v2.0 (detected by getID3())
475 * Ahead Nero encodes TwinVQF files 1 second shorter than they
477 * AAC-ADTS files are always actually encoded VBR, even if CBR mode
478 is specified (the CBR-mode switches on the encoder enable ABR
479 mode, not CBR as such, but it's not possible to tell the
480 difference between such ABR files and true VBR)
481 * STREAMINFO.audio_signature in OggFLAC is always null. "The reason
482 it's like that is because there is no seeking support in
483 libOggFLAC yet, so it has no way to go back and write the
484 computed sum after encoding. Seeking support in Ogg FLAC is the
485 #1 item for the next release." - Josh Coalson (FLAC developer)
486 NOTE: getID3() will calculate md5_data in a method similar to
487 other file formats, but that value cannot be compared to the
488 md5_data value from FLAC data in a FLAC file format.
489 * STREAMINFO.audio_signature is not calculated in FLAC v0.3.0 &
490 v0.4.0 - getID3() will calculate md5_data in a method similar to
491 other file formats, but that value cannot be compared to the
492 md5_data value from FLAC v0.5.0+
493 * RioPort (various versions including 2.0 and 3.11) tags ID3v2 with
494 a WCOM frame that has no data portion
495 * Earlier versions of Coolplayer adds illegal ID3 tags to Ogg Vorbis
496 files, thus making them corrupt.
497 * Meracl ID3 Tag Writer v1.3.4 (and older) incorrectly truncates the
498 last byte of data from an MP3 file when appending a new ID3v1 tag.
499 (detected by getID3())
500 * Lossless-Audio files encoded with and without the -noseek switch
501 do actually differ internally and therefore cannot match md5_data
502 * iTunes has been known to append a new ID3v1 tag on the end of an
503 existing ID3v1 tag when ID3v2 tag is also present
504 (detected by getID3())
505 * MediaMonkey may write a blank RGAD ID3v2 frame but put actual
506 replay gain adjustments in a series of user-defined TXXX frames
507 (detected and handled by getID3() since v1.9.2)
515 [www.id3.org](http://www.id3.org) material now mirrored at <http://id3lib.sourceforge.net/id3/>
517 * http://www.id3.org/id3v2.4.0-structure.txt
518 * http://www.id3.org/id3v2.4.0-frames.txt
519 * http://www.id3.org/id3v2.4.0-changes.txt
520 * http://www.id3.org/id3v2.3.0.txt
521 * http://www.id3.org/id3v2-00.txt
522 * http://www.id3.org/mp3frame.html
523 * http://minnie.tuhs.org/pipermail/mp3encoder/2001-January/001800.html <mathewhendry@hotmail.com>
524 * http://www.dv.co.yu/mpgscript/mpeghdr.htm
525 * http://www.mp3-tech.org/programmer/frame_header.html
526 * http://users.belgacom.net/gc247244/extra/tag.html
527 * http://gabriel.mp3-tech.org/mp3infotag.html
528 * http://www.id3.org/iso4217.html
529 * http://www.unicode.org/Public/MAPPINGS/ISO8859/8859-1.TXT
530 * http://www.xiph.org/ogg/vorbis/doc/framing.html
531 * http://www.xiph.org/ogg/vorbis/doc/v-comment.html
532 * http://leknor.com/code/php/class.ogg.php.txt
533 * http://www.id3.org/iso639-2.html
534 * http://www.id3.org/lyrics3.html
535 * http://www.id3.org/lyrics3200.html
536 * http://www.psc.edu/general/software/packages/ieee/ieee.html
537 * http://www.scri.fsu.edu/~jac/MAD3401/Backgrnd/ieee-expl.html
538 * http://www.scri.fsu.edu/~jac/MAD3401/Backgrnd/binary.html
539 * http://www.jmcgowan.com/avi.html
540 * http://www.wotsit.org/
541 * http://www.herdsoft.com/ti/davincie/davp3xo2.htm
542 * http://www.mathdogs.com/vorbis-illuminated/bitstream-appendix.html
543 * "Standard MIDI File Format" by Dustin Caldwell (from www.wotsit.org)
544 * http://midistudio.com/Help/GMSpecs_Patches.htm
545 * http://www.xiph.org/archives/vorbis/200109/0459.html
546 * http://www.replaygain.org/
547 * http://www.lossless-audio.com/
548 * http://download.microsoft.com/download/winmediatech40/Doc/1.0/WIN98MeXP/EN-US/ASF_Specification_v.1.0.exe
549 * http://mediaxw.sourceforge.net/files/doc/Active%20Streaming%20Format%20(ASF)%201.0%20Specification.pdf
550 * http://www.uni-jena.de/~pfk/mpp/sv8/ (archived at http://www.hydrogenaudio.org/musepack/klemm/www.personal.uni-jena.de/~pfk/mpp/sv8/)
551 * http://jfaul.de/atl/
552 * http://www.uni-jena.de/~pfk/mpp/ (archived at http://www.hydrogenaudio.org/musepack/klemm/www.personal.uni-jena.de/~pfk/mpp/)
553 * http://www.libpng.org/pub/png/spec/png-1.2-pdg.html
554 * http://www.real.com/devzone/library/creating/rmsdk/doc/rmff.htm
555 * http://www.fastgraph.com/help/bmp_os2_header_format.html
556 * http://netghost.narod.ru/gff/graphics/summary/os2bmp.htm
557 * http://flac.sourceforge.net/format.html
558 * http://www.research.att.com/projects/mpegaudio/mpeg2.html
559 * http://www.audiocoding.com/wiki/index.php?page=AAC
560 * http://libmpeg.org/mpeg4/doc/w2203tfs.pdf
561 * http://www.geocities.com/xhelmboyx/quicktime/formats/qtm-layout.txt
562 * http://developer.apple.com/techpubs/quicktime/qtdevdocs/RM/frameset.htm
563 * http://www.nullsoft.com/nsv/
564 * http://www.wotsit.org/download.asp?f=iso9660
565 * http://sandbox.mc.edu/~bennet/cs110/tc/tctod.html
566 * http://www.cdroller.com/htm/readdata.html
567 * http://www.speex.org/manual/node10.html
568 * http://www.harmony-central.com/Computer/Programming/aiff-file-format.doc
569 * http://www.faqs.org/rfcs/rfc2361.html
570 * http://ghido.shelter.ro/
571 * http://www.ebu.ch/tech_t3285.pdf
572 * http://www.sr.se/utveckling/tu/bwf
573 * http://ftp.aessc.org/pub/aes46-2002.pdf
574 * http://cartchunk.org:8080/
575 * http://www.broadcastpapers.com/radio/cartchunk01.htm
576 * http://www.hr/josip/DSP/AudioFile2.html
577 * http://home.attbi.com/~chris.bagwell/AudioFormats-11.html
578 * http://www.pure-mac.com/extkey.html
579 * http://cesnet.dl.sourceforge.net/sourceforge/bonkenc/bonk-binary-format-0.9.txt
580 * http://www.headbands.com/gspot/
581 * http://www.openswf.org/spec/SWFfileformat.html
582 * http://j-faul.virtualave.net/
583 * http://www.btinternet.com/~AnthonyJ/Atari/programming/avr_format.html
584 * http://cui.unige.ch/OSG/info/AudioFormats/ap11.html
585 * http://sswf.sourceforge.net/SWFalexref.html
586 * http://www.geocities.com/xhelmboyx/quicktime/formats/qti-layout.txt
587 * http://www-lehre.informatik.uni-osnabrueck.de/~fbstark/diplom/docs/swf/Flash_Uncovered.htm
588 * http://developer.apple.com/quicktime/icefloe/dispatch012.html
589 * http://www.csdn.net/Dev/Format/graphics/PCD.htm
590 * http://tta.iszf.irk.ru/
591 * http://www.atsc.org/standards/a_52a.pdf
592 * http://www.alanwood.net/unicode/
593 * http://www.freelists.org/archives/matroska-devel/07-2003/msg00010.html
594 * http://www.its.msstate.edu/net/real/reports/config/tags.stats
595 * http://homepages.slingshot.co.nz/~helmboy/quicktime/formats/qtm-layout.txt
596 * http://brennan.young.net/Comp/LiveStage/things.html
597 * http://www.multiweb.cz/twoinches/MP3inside.htm
598 * http://www.geocities.co.jp/SiliconValley-Oakland/3664/alittle.html#GenreExtended
599 * http://www.mactech.com/articles/mactech/Vol.06/06.01/SANENormalized/
600 * http://www.unicode.org/unicode/faq/utf_bom.html
601 * http://tta.corecodec.org/?menu=format
602 * http://www.scvi.net/nsvformat.htm
603 * http://pda.etsi.org/pda/queryform.asp
604 * http://cpansearch.perl.org/src/RGIBSON/Audio-DSS-0.02/lib/Audio/DSS.pm
605 * http://trac.musepack.net/trac/wiki/SV8Specification
606 * http://wyday.com/cuesharp/specification.php
607 * http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/Nikon.html