source: extensions/charlies_content/getid3/readme.txt @ 3318

Revision 3318, 21.4 KB checked in by vdigital, 11 years ago (diff)

+ Add Charlies' content to depository

  • Property svn:eol-style set to LF
  • Property svn:keywords set to Author Date Id Revision
Line 
1// +----------------------------------------------------------------------+
2// | PHP version 5                                                        |
3// +----------------------------------------------------------------------+
4// | Copyright (c) 2002-2006 James Heinrich, Allan Hansen                 |
5// +----------------------------------------------------------------------+
6// | This source file is subject to version 2 of the GPL license,         |
7// | that is bundled with this package in the file license.txt and is     |
8// | available through the world-wide-web at the following url:           |
9// | http://www.gnu.org/copyleft/gpl.html                                 |
10// +----------------------------------------------------------------------+
11// | getID3() - http://getid3.sourceforge.net or http://www.getid3.org    |
12// +----------------------------------------------------------------------+
13// | Authors: James Heinrich <infoØgetid3*org>                            |
14// |          Allan Hansen <ahØartemis*dk>                                |
15// +----------------------------------------------------------------------+
16// | Dependencies                                                         |
17// +----------------------------------------------------------------------+
18//
19// $Id$
20
21        This code is released under the GNU GPL:
22          http://www.gnu.org/copyleft/gpl.html
23
24     +---------------------------------------------+
25     | If you do use this code somewhere, send me  |
26     | an email and tell me how/where you used it. |
27     |                                             |
28     | If you want to donate, there is a link on   |
29     | http://www.getid3.org for PayPal donations. |
30     +---------------------------------------------+
31
32
33
34Quick Start
35===========================================================================
36
37Q: How can I check that getID3() works on my server/files?
38A: Unzip getID3() to a directory, then access /demos/demo.browse.php
39
40
41
42Sourceforge Notification
43===========================================================================
44
45It's highly recommended that you sign up for notification from
46Sourceforge for when new versions are released. Please visit:
47http://sourceforge.net/project/showfiles.php?group_id=55859
48and click the little "monitor package" icon/link.  If you're
49previously signed up for the mailing list, be aware that it has
50been discontinued, only the automated Sourceforge notification
51will be used from now on.
52
53
54
55What does getID3() do?
56===========================================================================
57
58Reads & parses (to varying degrees):
59 ¤ tags:
60  * APE (v1 and v2)
61  * ID3v1 (& ID3v1.1)
62  * ID3v2 (v2.4, v2.3, v2.2)
63  * Lyrics3 (v1 & v2)
64
65 ¤ audio-lossy:
66  * MP3/MP2/MP1
67  * MPC / Musepack
68  * Ogg (Vorbis, OggFLAC, Speex)
69  * RealAudio
70  * Speex
71  * VQF
72
73 ¤ audio-lossless:
74  * AIFF
75  * AU
76  * Bonk
77  * CD-audio (*.cda)
78  * FLAC
79  * LA (Lossless Audio)
80  * LPAC
81  * MIDI
82  * Monkey's Audio
83  * OptimFROG
84  * RKAU
85  * VOC
86  * WAV (RIFF)
87  * WavPack
88
89 ¤ audio-video:
90  * ASF: ASF, Windows Media Audio (WMA), Windows Media Video (WMV)
91  * AVI (RIFF)
92  * Flash
93  * MPEG-1 / MPEG-2
94  * NSV (Nullsoft Streaming Video)
95  * Quicktime
96  * RealVideo
97
98 ¤ still image:
99  * BMP
100  * GIF
101  * JPEG
102  * PNG
103
104 ¤ data:
105  * ISO-9660 CD-ROM image (directory structure)
106  * SZIP (limited support)
107  * ZIP (directory structure)
108
109
110Writes:
111  * ID3v1 (& ID3v1.1)
112  * ID3v2 (v2.3 & v2.4)
113  * VorbisComment on OggVorbis
114  * VorbisComment on FLAC (not OggFLAC)
115  * APE v2
116  * Lyrics3 (delete only)
117
118
119
120Requirements
121===========================================================================
122
123* PHP 4.2.0 (or higher) for getID3() 1.7.8 (and up).
124* PHP 5.0.0 (or higher) for getID3() 2.0.0 (and up).
125* at least 4MB memory for PHP. 8MB is highly recommended.
126  12MB is required with all modules loaded.
127
128
129
130Usage
131===========================================================================
132
133See /demos/demo.basic.php for a very basic use of getID3() with no
134fancy output, just scanning one file.
135
136See structure.txt for the returned data structure.
137
138*>  For an example of a complete directory-browsing,       <*
139*>  file-scanning implementation of getID3(), please run   <*
140*>  /demos/demo.browse.php                                 <*
141
142See /demos/demo.mysql.php for a sample recursive scanning code that
143scans every file in a given directory, and all sub-directories, stores
144the results in a database and allows various analysis / maintenance
145operations
146
147To analyze remote files over HTTP or FTP you need to copy the file
148locally first before running getID3(). Your code would look something
149like this:
150
151// Copy remote file locally to scan with getID3()
152$remotefilename = 'http://www.example.com/filename.mp3';
153if ($fp_remote = fopen($remotefilename, 'rb')) {
154    $localtempfilename = tempnam('/tmp', 'getID3');
155    if ($fp_local = fopen($localtempfilename, 'wb')) {
156        while ($buffer = fread($fp_remote, 8192)) {
157            fwrite($fp_local, $buffer);
158        }
159        fclose($fp_local);
160
161                // Initialize getID3 engine
162                $getID3 = new getID3;
163
164                $ThisFileInfo = $getID3->analyze($filename);
165
166        // Delete temporary file
167        unlink($localtempfilename);
168    }
169    fclose($fp_remote);
170}
171
172
173See /demos/demo.write.php for how to write tags.
174
175
176
177What does the returned data structure look like?
178===========================================================================
179
180See structure.txt
181
182It is recommended that you look at the output of
183/demos/demo.browse.php scanning the file(s) you're interested in to
184confirm what data is actually returned for any particular filetype in
185general, and your files in particular, as the actual data returned
186may vary considerably depending on what information is available in
187the file itself.
188
189
190
191Notes
192===========================================================================
193
194getID3() 1.7:
195If the format parser encounters a critical problem, it will return
196something in $fileinfo['error'], describing the encountered error. If
197a less critical error or notice is generated it will appear in
198$fileinfo['warning']. Both keys may contain more than one warning or
199error. If something is returned in ['error'] then the file was not
200correctly parsed and returned data may or may not be correct and/or
201complete. If something is returned in ['warning'] (and not ['error'])
202then the data that is returned is OK - usually getID3() is reporting
203errors in the file that have been worked around due to known bugs in
204other programs. Some warnings may indicate that the data that is
205returned is OK but that some data could not be extracted due to
206errors in the file.
207
208getID3() 2.0:
209See above except errors are thrown (so you will only get one error).
210
211
212
213Disclaimer
214===========================================================================
215
216getID3() has been tested on many systems, on many types of files,
217under many operating systems, and is generally believe to be stable
218and safe. That being said, there is still the chance there is an
219undiscovered and/or unfixed bug that may potentially corrupt your
220file, especially within the writing functions. By using getID3() you
221agree that it's not my fault if any of your files are corrupted.
222In fact, I'm not liable for anything :)
223
224
225
226License
227===========================================================================
228
229GNU General Public License - see license.txt
230
231This program is free software; you can redistribute it and/or
232modify it under the terms of the GNU General Public License
233as published by the Free Software Foundation; either version 2
234of the License, or (at your option) any later version.
235
236This program is distributed in the hope that it will be useful,
237but WITHOUT ANY WARRANTY; without even the implied warranty of
238MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
239GNU General Public License for more details.
240
241You should have received a copy of the GNU General Public License
242along with this program; if not, write to:
243Free Software Foundation, Inc.
24459 Temple Place - Suite 330
245Boston, MA  02111-1307, USA.
246
247FAQ:
248Q: Can I use getID3() in my program? Do I need a commercial license?
249A: You're generally free to use getID3 however you see fit. The only
250   case in which you would require a commercial license is if you're
251   selling your closed-source program that integrates getID3. If you
252   sell your program including a copy of getID3, that's fine as long
253   as you include a copy of the sourcecode when you sell it.  Or you
254   can distribute your code without getID3 and say "download it from
255   getid3.sourceforge.net"
256
257
258
259Future Plans
260===========================================================================
261
262* Writing support for Real
263* Better support for MP4 container format
264* Support for Matroska (www.matroska.org)
265  http://corecodec.com/modules.php?op=modload&name=PNphpBB2&file=viewtopic&t=227
266* Scan for appended ID3v2 tag at end of file per ID3v2.4 specs (Section 5.0)
267* Support for JPEG-2000 (http://www.morgan-multimedia.com/jpeg2000_overview.htm)
268* Support for MOD (mod/stm/s3m/it/xm/mtm/ult/669)
269* Support for ACE (thanks Vince)
270* Support for Ogg other than Vorbis, Speex and OggFlac (ie. Ogg+Xvid)
271* Ability to create Xing/LAME VBR header for VBR MP3s that are missing VBR header
272* Ability to "clean" ID3v2 padding (replace invalid padding with valid padding)
273* Warn if MP3s change version mid-stream (in full-scan mode)
274* check for corrupt/broken mid-file MP3 streams in histogram scan
275* Support for lossless-compression formats
276  (http://www.firstpr.com.au/audiocomp/lossless/#Links)
277  (http://compression.ca/act-sound.html)
278  (http://web.inter.nl.net/users/hvdh/lossless/lossless.htm)
279* Support for RIFF-INFO chunks
280  * http://lotto.st-andrews.ac.uk/~njh/tag_interchange.html
281    (thanks Nick Humfrey <njhØsurgeradio*co*uk>)
282  * http://abcavi.narod.ru/sof/abcavi/infotags.htm
283    (thanks Kibi)
284* Better support for Bink video
285* http://www.hr/josip/DSP/AudioFile2.html
286* http://www.pcisys.net/~melanson/codecs/
287* Detect mp3PRO
288* Support for PSD
289* Support for JPC
290* Support for JP2
291* Support for JPX
292* Support for JB2
293* Support for IFF
294* Support for ICO
295* Support for ANI
296* Support for EXE (comments, author, etc) (thanks p*quaedackersØplanet*nl)
297* Support for DVD-IFO (region, subtitles, aspect ratio, etc)
298  (thanks p*quaedackersØplanet*nl)
299* More complete support for SWF - parsing encapsulated MP3 and/or JPEG content
300    (thanks n8n8Øyahoo*com)
301* Support for a2b
302* Optional scan-through-frames for AVI verification
303  (thanks rockcohenØmassive-interactive*nl)
304* Support for TTF (thanks infoØbutterflyx*com)
305* Support for DSS (http://www.getid3.org/phpBB2/viewtopic.php?t=171)
306* Support for SMAF (http://smaf-yamaha.com/what/demo.html)
307  http://www.getid3.org/phpBB2/viewtopic.php?t=182
308* Support for AMR (http://www.getid3.org/phpBB2/viewtopic.php?t=195)
309* Support for 3gpp (http://www.getid3.org/phpBB2/viewtopic.php?t=195)
310* Support for ID4 (http://www.wackysoft.cjb.net grizlyY2KØhotmail*com)
311* Parse XML data returned in Ogg comments
312* Parse XML data from Quicktime SMIL metafiles (klausrathØmac*com)
313* ID3v2 genre string creator function
314* More complete parsing of JPG
315* Support for all old-style ASF packets
316* ASF/WMA/WMV tag writing
317* Parse declared T??? ID3v2 text information frames, where appropriate
318    (thanks Christian Fritz for the idea)
319* Recognize encoder:
320  http://www.guerillasoft.com/EncSpot2/index.html
321  http://ff123.net/identify.html
322  http://www.hydrogenaudio.org/?act=ST&f=16&t=9414
323  http://www.hydrogenaudio.org/?showtopic=11785
324* Support for other OS/2 bitmap structures: Bitmap Array('BA'),
325  Color Icon('CI'), Color Pointer('CP'), Icon('IC'), Pointer ('PT')
326  http://netghost.narod.ru/gff/graphics/summary/os2bmp.htm
327* Support for WavPack RAW mode
328* ASF/WMA/WMV data packet parsing
329* ID3v2FrameFlagsLookupTagAlter()
330* ID3v2FrameFlagsLookupFileAlter()
331* obey ID3v2 tag alter/preserve/discard rules
332* http://www.geocities.com/SiliconValley/Sector/9654/Softdoc/Illyrium/Aolyr.htm
333* proper checking for LINK/LNK frame validity in ID3v2 writing
334* proper checking for ASPI-TLEN frame validity in ID3v2 writing
335* proper checking for COMR frame validity in ID3v2 writing
336* http://www.geocities.co.jp/SiliconValley-Oakland/3664/index.html
337* decode GEOB ID3v2 structure as encoded by RealJukebox,
338  decode NCON ID3v2 structure as encoded by MusicMatch
339  (probably won't happen - the formats are proprietary)
340
341
342
343Known Bugs/Issues in getID3() that may be fixed eventually
344===========================================================================
345
346* Cannot determine bitrate for MPEG video with VBR video data
347  (need documentation)
348* Interlace/progressive cannot be determined for MPEG video
349  (need documentation)
350* MIDI playtime is sometimes inaccurate
351* AAC-RAW mode files cannot be identified
352* WavPack-RAW mode files cannot be identified
353* mp4 files report lots of "Unknown QuickTime atom type"
354   (need documentation)
355* Encrypted ASF/WMA/WMV files warn about "unhandled GUID
356  ASF_Content_Encryption_Object"
357* Bitrate split between audio and video cannot be calculated for
358  NSV, only the total bitrate. (need documentation)
359* All Ogg formats (Vorbis, OggFLAC, Speex) are affected by the
360  problem of large VorbisComments spanning multiple Ogg pages, but
361  but only OggVorbis files can be processed with vorbiscomment.
362* The version of "head" supplied with Mac OS 10.2.8 (maybe other
363  versions too) does only understands a single option (-n) and
364  therefore fails. getID3 ignores this and returns wrong md5_data.
365
366
367
368Known Bugs/Issues in getID3() that cannot be fixed
369--------------------------------------------------
370
371* Files larger than 2GB (of any format) cannot be parsed by
372  getID3() due to limitations in the PHP filesystem functions
373
374
375
376Known Bugs/Issues in other programs
377-----------------------------------
378
379* Winamp (up to v2.80 at least) does not support ID3v2.4 tags,
380    only ID3v2.3
381    see: http://forums.winamp.com/showthread.php?postid=387524
382* Some versions of Helium2 (www.helium2.com) do not write
383    ID3v2.4-compliant Frame Sizes, even though the tag is marked
384    as ID3v2.4)  (detected by getID3())
385* MP3ext V3.3.17 places a non-compliant padding string at the end
386    of the ID3v2 header. This is supposedly fixed in v3.4b21 but
387    only if you manually add a registry key. This fix is not yet
388    confirmed.  (detected by getID3())
389* CDex v1.40 (fixed by v1.50b7) writes non-compliant Ogg comment
390    strings, supposed to be in the format "NAME=value" but actually
391    written just "value"  (detected by getID3())
392* Oggenc 0.9-rc3 flags the encoded file as ABR whether it's
393    actually ABR or VBR.
394* iTunes (versions "X v2.0.3", "v3.0.1" are known-guilty, probably
395    other versions are too) writes ID3v2.3 comment tags using a
396    frame name 'COM ' which is not valid for ID3v2.3+ (it's an
397    ID3v2.2-style frame name)  (detected by getID3())
398* MP2enc does not encode mono CBR MP2 files properly (half speed
399    sound and double playtime)
400* MP2enc does not encode mono VBR MP2 files properly (actually
401    encoded as stereo)
402* tooLAME does not encode mono VBR MP2 files properly (actually
403    encoded as stereo)
404* AACenc encodes files in VBR mode (actually ABR) even if CBR is
405   specified
406* AAC/ADIF - bitrate_mode = cbr for vbr files
407* LAME 3.90-3.92 prepends one frame of null data (space for the
408  LAME/VBR header, but it never gets written) when encoding in CBR
409  mode with the DLL
410* Ahead Nero encodes TwinVQF with a DSIZ value (which is supposed
411  to be the filesize in bytes) of "0" for TwinVQF v1.0 and "1" for
412  TwinVQF v2.0  (detected by getID3())
413* Ahead Nero encodes TwinVQF files 1 second shorter than they
414  should be
415* AAC-ADTS files are always actually encoded VBR, even if CBR mode
416  is specified (the CBR-mode switches on the encoder enable ABR
417  mode, not CBR as such, but it's not possible to tell the
418  difference between such ABR files and true VBR)
419* STREAMINFO.audio_signature in OggFLAC is always null. "The reason
420  it's like that is because there is no seeking support in
421  libOggFLAC yet, so it has no way to go back and write the
422  computed sum after encoding. Seeking support in Ogg FLAC is the
423  #1 item for the next release." - Josh Coalson (FLAC developer)
424  NOTE: getID3() will calculate md5_data in a method similar to
425  other file formats, but that value cannot be compared to the
426  md5_data value from FLAC data in a FLAC file format.
427* STREAMINFO.audio_signature is not calculated in FLAC v0.3.0 &
428  v0.4.0 - getID3() will calculate md5_data in a method similar to
429  other file formats, but that value cannot be compared to the
430  md5_data value from FLAC v0.5.0+
431* RioPort (various versions including 2.0 and 3.11) tags ID3v2 with
432  a WCOM frame that has no data portion
433* Earlier versions of Coolplayer adds illegal ID3 tags to Ogg Vorbis
434  files, thus making them corrupt.
435* Meracl ID3 Tag Writer v1.3.4 (and older) incorrectly truncates the
436  last byte of data from an MP3 file when appending a new ID3v1 tag.
437  (detected by getID3())
438* Lossless-Audio files encoded with and without the -noseek switch
439  do actually differ internally and therefore cannot match md5_data
440* iTunes has been known to append a new ID3v1 tag on the end of an
441  existing ID3v1 tag when ID3v2 tag is also present
442  (detected by getID3())
443
444
445
446
447Reference material:
448===========================================================================
449
450[www.id3.org material now mirrored at http://id3lib.sourceforge.net/id3/]
451* http://www.id3.org/id3v2.4.0-structure.txt
452* http://www.id3.org/id3v2.4.0-frames.txt
453* http://www.id3.org/id3v2.4.0-changes.txt
454* http://www.id3.org/id3v2.3.0.txt
455* http://www.id3.org/id3v2-00.txt
456* http://www.id3.org/mp3frame.html
457* http://minnie.tuhs.org/pipermail/mp3encoder/2001-January/001800.html <mathewhendry@hotmail.com>
458* http://www.dv.co.yu/mpgscript/mpeghdr.htm
459* http://www.mp3-tech.org/programmer/frame_header.html
460* http://users.belgacom.net/gc247244/extra/tag.html
461* http://gabriel.mp3-tech.org/mp3infotag.html
462* http://www.id3.org/iso4217.html
463* http://www.unicode.org/Public/MAPPINGS/ISO8859/8859-1.TXT
464* http://www.xiph.org/ogg/vorbis/doc/framing.html
465* http://www.xiph.org/ogg/vorbis/doc/v-comment.html
466* http://leknor.com/code/php/class.ogg.php.txt
467* http://www.id3.org/iso639-2.html
468* http://www.id3.org/lyrics3.html
469* http://www.id3.org/lyrics3200.html
470* http://www.psc.edu/general/software/packages/ieee/ieee.html
471* http://www.scri.fsu.edu/~jac/MAD3401/Backgrnd/ieee-expl.html
472* http://www.scri.fsu.edu/~jac/MAD3401/Backgrnd/binary.html
473* http://www.jmcgowan.com/avi.html
474* http://www.wotsit.org/
475* http://www.herdsoft.com/ti/davincie/davp3xo2.htm
476* http://www.mathdogs.com/vorbis-illuminated/bitstream-appendix.html
477* "Standard MIDI File Format" by Dustin Caldwell (from www.wotsit.org)
478* http://midistudio.com/Help/GMSpecs_Patches.htm
479* http://www.xiph.org/archives/vorbis/200109/0459.html
480* http://www.replaygain.org/
481* http://www.lossless-audio.com/
482* http://download.microsoft.com/download/winmediatech40/Doc/1.0/WIN98MeXP/EN-US/ASF_Specification_v.1.0.exe
483* http://mediaxw.sourceforge.net/files/doc/Active%20Streaming%20Format%20(ASF)%201.0%20Specification.pdf
484* http://www.uni-jena.de/~pfk/mpp/sv8/
485* http://jfaul.de/atl/
486* http://www.uni-jena.de/~pfk/mpp/
487* http://www.libpng.org/pub/png/spec/png-1.2-pdg.html
488* http://www.real.com/devzone/library/creating/rmsdk/doc/rmff.htm
489* http://www.fastgraph.com/help/bmp_os2_header_format.html
490* http://netghost.narod.ru/gff/graphics/summary/os2bmp.htm
491* http://flac.sourceforge.net/format.html
492* http://www.research.att.com/projects/mpegaudio/mpeg2.html
493* http://www.audiocoding.com/wiki/index.php?page=AAC
494* http://libmpeg.org/mpeg4/doc/w2203tfs.pdf
495* http://www.geocities.com/xhelmboyx/quicktime/formats/qtm-layout.txt
496* http://developer.apple.com/techpubs/quicktime/qtdevdocs/RM/frameset.htm
497* http://www.nullsoft.com/nsv/
498* http://www.wotsit.org/download.asp?f=iso9660
499* http://sandbox.mc.edu/~bennet/cs110/tc/tctod.html
500* http://www.cdroller.com/htm/readdata.html
501* http://www.speex.org/manual/node10.html
502* http://www.harmony-central.com/Computer/Programming/aiff-file-format.doc
503* http://www.faqs.org/rfcs/rfc2361.html
504* http://ghido.shelter.ro/
505* http://www.ebu.ch/tech_t3285.pdf
506* http://www.sr.se/utveckling/tu/bwf
507* http://ftp.aessc.org/pub/aes46-2002.pdf
508* http://cartchunk.org:8080/
509* http://www.broadcastpapers.com/radio/cartchunk01.htm
510* http://www.hr/josip/DSP/AudioFile2.html
511* http://home.attbi.com/~chris.bagwell/AudioFormats-11.html
512* http://www.pure-mac.com/extkey.html
513* http://cesnet.dl.sourceforge.net/sourceforge/bonkenc/bonk-binary-format-0.9.txt
514* http://www.headbands.com/gspot/
515* http://www.openswf.org/spec/SWFfileformat.html
516* http://j-faul.virtualave.net/
517* http://www.btinternet.com/~AnthonyJ/Atari/programming/avr_format.html
518* http://cui.unige.ch/OSG/info/AudioFormats/ap11.html
519* http://sswf.sourceforge.net/SWFalexref.html
520* http://www.geocities.com/xhelmboyx/quicktime/formats/qti-layout.txt
521* http://www-lehre.informatik.uni-osnabrueck.de/~fbstark/diplom/docs/swf/Flash_Uncovered.htm
522* http://developer.apple.com/quicktime/icefloe/dispatch012.html
523* http://www.csdn.net/Dev/Format/graphics/PCD.htm
524* http://tta.iszf.irk.ru/
525* http://www.atsc.org/standards/a_52a.pdf
526* http://www.alanwood.net/unicode/
527* http://www.freelists.org/archives/matroska-devel/07-2003/msg00010.html
528* http://www.its.msstate.edu/net/real/reports/config/tags.stats
529* http://homepages.slingshot.co.nz/~helmboy/quicktime/formats/qtm-layout.txt
530* http://brennan.young.net/Comp/LiveStage/things.html
531* http://www.multiweb.cz/twoinches/MP3inside.htm
532* http://www.geocities.co.jp/SiliconValley-Oakland/3664/alittle.html#GenreExtended
533* http://www.mactech.com/articles/mactech/Vol.06/06.01/SANENormalized/
534* http://www.unicode.org/unicode/faq/utf_bom.html
535* http://tta.corecodec.org/?menu=format
536* http://www.scvi.net/nsvformat.htm
537* http://pda.etsi.org/pda/queryform.asp
Note: See TracBrowser for help on using the repository browser.