id3 0.4.0

data/docs/ID3v2_frames_comparison.txt

@@ -0,0 +1,197 @@
+
+                       ===========================
+                       Comparison of ID3v2 Frames:
+                       ===========================
+
+This document contains a side-by-side comparison over the frames used 
+in the 3 different versions of the informal ID3v2 standard: 
+v2.2.0, v2.3.0 and v2.4.0
+
+This document is a compilation of information which is available in the 
+documents listed below. The original documents Copyright notices apply.
+
+    ID3 v1.0 :     http://www.id3.org/id3v1.html
+    ID3 v1.1 :     http://www.egr.uri.edu/~kovacsp/mp3/ID3-Tag.html
+
+
+    ID3v2 2.0:     http://www.id3.org/id3v2-00.txt
+    ID3v2 3.0:     http://www.id3.org/id3v2.3.0.txt
+    ID3v2 4.0:     http://www.id3.org/id3v2.4.0-changes.txt
+                   http://www.id3.org/id3v2.4.0-structure.txt
+                   http://www.id3.org/id3v2.4.0-frames.txt
+
+Please refer to the original documents listed above, for any information 
+regarding the ID3v2 standards.
+
+
+Author:            Tilo Sloboda, Thu, 17 Oct 2002 00:26:54 -0700
+
+
+References:
+    id3lib-3.8.0   id3lib-3.8.0/include/id3/globals.h
+    
+    NOTE:          the symbolic names used in the leftmost column are derived
+                   from the names used in id3lib-3.8.0
+                   The symbolic name CRYPTEDMETA is not part of id3lib-3.8.0
+                   
+Legend:
+
+  -- : depreciated frame
+ 
+  -> : replaced by  (all frames listed before this one are replaced)
+  
+
+
+================================================================================
+                           ID3v2 version
+symbolic names          2.0     3.0     4.0     comments
+================================================================================
+
+CONTENTGROUP            TT1     TIT1    TIT1    content group description
+TITLE                   TT2     TIT2    TIT2    title/songname/content description
+SUBTITLE                TT3     TIT3    TIT3    subtitle/description refinement
+                        
+LEADARTIST              TP1     TPE1    TPE1    lead performer(s)/soloist(s)
+BAND                    TP2     TPE2    TPE2    band/orchestra/accompaniment
+CONDUCTOR               TP3     TPE3    TPE3    conductor/performer refinement
+MIXARTIST               TP4     TPE4    TPE4    interpreted, remixed, modified by
+                        
+COMPOSER                TCM     TCOM    TCOM    composer
+LYRICIST                TXT`    TEXT    TEXT    lyricist/text writer
+                        
+LANGUAGE                TLA     TLAN    TLAN    language(s)
+CONTENTTYPE             TCO     TCON    TCON    content type
+                        
+ALBUM                   TAL     TALB    TALB    album/movie/show title
+                        
+TRACKNUM                TRK     TRCK    TRCK    track number/position in set
+PARTINSET               TPA     TPOS    TPOS    part of set
+        
+ISRC                    TRC     TSRC    TSRC    international standard recording code
+                
+--------------------------------------------------------------------------------
+DATE                    TDA     TDAT            date
+YEAR                    TYE     TYER            year
+TIME                    TIM     TIME            time
+RECORDINGDATES          TRD     TRDA            recording dates
+RECORDINGTIME                        -> TDRC    recording time
+--------------------------------------------------------------------------------
+ORIGYEAR                TOR     TORY            original release year
+ORIGRELEASETIME                      -> TDOR    original release time
+--------------------------------------------------------------------------------
+        
+BPM                     TBP     TBPM    TBPM    beats per minute
+                        
+MEDIATYPE               TMT     TMED    TMED    media type
+FILETYPE                TFT     TFLT    TFLT    file type
+COPYRIGHT               TCR     TCOP    TCOP    copyright message
+                        
+PUBLISHER               TPB     TPUB    TPUB    pblisher
+ENCODEDBY               TEN     TENC    TENC    encoded by
+ENCODERSETTINGS         TSS     TSSE    TSSE    software/hardware + settings for encoding
+                        
+SONGLEN                 TLE     TLEN    TLEN    length (ms)
+--------------------------------------------------------------------------------
+SIZE                    TSI     TSIZ     --     size (bytes)
+--------------------------------------------------------------------------------
+                        
+PLAYLISTDELAY           TDY     TDLY    TDLY    playlist delay
+INITIALKEY              TKE     TKEY    TKEY    initial key
+                        
+ORIGALBUM               TOT     TOAL    TOAL    original album/movie/show title
+ORIGFILENAME            TOF     TOFN    TOFN    original filename
+ORIGARTIST              TOA     TOPE    TOPE    original artist(s)/performer(s)
+ORIGLYRICIST            TOL     TOLY    TOLY    original lyricist(s)/text writer(s)
+        
+FILEOWNER                       TOWN    TOWN    file owner/licensee
+NETRADIOSTATION                 TRSN    TRSN    internet radio station name
+NETRADIOOWNER                   TRSO    TRSO    internet radio station owner
+                                
+SETSUBTITLE                             TSST    set subtitle
+MOOD                                    TMOO    mood
+PRODUCEDNOTICE                          TPRO    produced notice
+ENCODINGTIME                            TDEN    encoding time
+RELEASETIME                             TDRL    release time
+TAGGINGTIME                             TDTG    tagging time
+                                        
+ALBUMSORTORDER                          TSOA    album sort order
+PERFORMERSORTORDER                      TSOP    performer sort order
+TITLESORTORDER                          TSOT    title sort order
+                                        
+USERTEXT                TXX     TXXX    TXXX    user defined text information frame
+                        
+                        
+WWWAUDIOFILE            WAF     WOAF    WOAF    official audio file webpage
+WWWARTIST               WAR     WOAR    WOAR    official artist/performer webpage
+WWWAUDIOSOURCE          WAS     WOAS    WOAS    official audion source webpage
+WWWCOMMERCIALINFO       WCM     WCOM    WCOM    commercial information
+WWWCOPYRIGHT            WCP     WCOP    WCOP    copyright/legal information
+WWWPUBLISHER            WPB     WPUB    WPUB    publishers official webpage
+                        
+WWWRADIOPAGE                    WORS    WORS    official internet radio station homepage
+WWWPAYMENT                      WPAY    WPAY    payment
+                                
+WWWUSER                 WXX     WXXX    WXXX    user defined URL link frame
+                        
+--------------------------------------------------------------------------------
+INVOLVEDPEOPLE          IPL     IPLS            involved people list
+MUSICIANCREDITLIST                   -> TMCL    musician credits list
+INVOLVEDPEOPLE2                      -> TIPL    involved people list
+--------------------------------------------------------------------------------
+        
+UNSYNCEDLYRICS          ULT     USLT    USLT    unsynchronised lyrics/text transcription
+COMMENT                 COM     COMM    COMM    comments
+        
+TERMSOFUSE                      USER    USER    terms of use
+                        
+        
+================================================================================
+                           ID3v2 version
+symbolic names          2.0     3.0     4.0     comments
+================================================================================
+               
+CDID                    MCI     MCDI    MCDI    music CD identifier
+EVENTTIMING             ETC     ETCO    ETCO    event timing codes
+MPEGLOOKUP              MLL     MLLT    MLLT    MPEG location lookup table
+        
+SYNCEDTEMPO             STC     SYTC    SYTC    synchronised tempo codes
+SYNCEDLYRICS            SLT     SYLT    SYLT    synchronised lyrics/text
+
+--------------------------------------------------------------------------------
+VOLUMEADJ               RVA     RVAD            relative volume adjustment
+VOLUMEADJ2                           -> RVA2    relative volume adjustment (2)
+--------------------------------------------------------------------------------
+EQUALIZATION            EQU     EQUA            equalization
+EQUALIZATION2                        -> EQU2    equalization (2)
+--------------------------------------------------------------------------------
+        
+REVERB                  REV     RVRB    RVRB    reverb
+PICTURE                 PIC     APIC    APIC    attached picture
+GENERALOBJECT           GEO     GEOB    GEOB    general encapsulated object
+                        
+PLAYCOUNTER             CNT     PCNT    PCNT    play counter
+POPULARIMETER           POP     POPM    POPM    popularimeter
+        
+BUFFERSIZE              BUF     RBUF    RBUF    recommended buffer size
+                        
+CRYPTEDMETA             CRM                     encrypted meta frame
+AUDIOCRYPTO             CRA     AENC    AENC    audio encryption
+                                        
+LINKEDINFO              LNK     LINK    LINK    linked information
+                        
+POSITIONSYNC                    POSS    POSS    position synchronisation frame
+                                
+COMMERCIAL                      COMR    COMR    commercial frame
+CRYPTOREG                       ENCR    ENCR    encryption method registration
+GROUPINGREG                     GRID    GRID    group indentification registration
+PRIVATE                         PRIV    PRIV    private frame
+                                
+OWNERSHIP                               OWNE    ownership frame
+SIGNATURE                               SIGN    signature frame
+SEEKFRAME                               SEEK    seek frame
+AUDIOSEEKPOINT                          ASPI    audio seek point index
+        
+================================================================================
+                           ID3v2 version
+symbolic names          2.0     3.0     4.0     comments
+================================================================================

data/docs/ID3v2_frames_overview.txt

@@ -0,0 +1,60 @@
+                       ===========================
+                        Overview of ID3v2 Frames:
+                       ===========================
+
+
+This document contains a comparison over the frames used in the 3 different 
+versions of the informal ID3v2 standard: v2.2.0, v2.3.0 and v2.4.0
+
+This document is a compilation of information which is available in the 
+documents listed below, and therefore does not have a Copyright by itself.
+The original documents Copyright notices apply.
+
+Content: Copyright (C) Martin Nilsson 1998, 2000
+
+Please refer to the original documents listed below, for any information 
+regarding the ID3v2 standards.
+
+
+
+Compiled by: Tilo Sloboda, Thu, 17 Oct 2002 00:26:54 -0700
+
+
+Sources:
+    ID3v2 2.0:     http://www.id3.org/id3v2-00.txt
+    ID3v2 3.0:     http://www.id3.org/id3v2.3.0.txt
+    ID3v2 4.0:     http://www.id3.org/id3v2.4.0-changes.txt
+                   http://www.id3.org/id3v2.4.0-structure.txt
+                   http://www.id3.org/id3v2.4.0-frames.txt
+
+
+================================================================================
+ID3V22_HEADER:          "ID3" $02 $00 $C0 $7F $7F $7F $7F
+                
+ID3V22_FRAME_HEADER:    "XXX" $SS $SS $SS
+
+ID3V22_TEXT_FRAME1:      $01 <textstring> ($00 (00))
+
+ID3V22_TEXT_FRAME2:      <textstring> ($00 (00)) 
+
+ID3V22_TEXT_FRAME3:      $01 <textstring> ($00 (00))
+                             <textstring> ($00 (00))
+
+ID3V22_BINARY_FRAME1:    <binary data>
+
+
+================================================================================
+ID3V23_HEADER:          "ID3" $03 $00 $C0 $7F $7F $7F $7F
+
+ID3V23_FRAME_HEADER:    "XXXX" $SS $SS $SS $SS $FF $FF
+
+
+================================================================================
+ID3V24_HEADER:          "ID3" $04 $00 $F0 $7F $7F $7F $7F
+
+ID3V24_FRAME_HEADER:    "XXXX" $7F $7F $7F $7F $FF $FF
+
+
+================================================================================
+
+                

data/docs/Module_ID3.html

@@ -0,0 +1,146 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+  
+  
+  
+  
+  
+  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+  <title>Module ID3</title>
+
+  </head>
+<body><br>
+
+
+
+
+
+
+<br>
+
+
+
+
+
+
+<br>
+
+
+
+
+
+
+<h3>Module ID3</h3>
+
+
+This module models provides methods, constants and classes to handle
+ID3 version 1.x and version 2.x tags for audio files.
+<P>
+
+
+
+
+
+
+<br>
+
+
+
+
+
+<h4>
+Provided Functionality:
+</h4>
+
+
+
+
+
+<ul>
+
+
+
+
+
+
+  <li>Reads and parses audio files for ID3-tags</li>
+  <li>Writes audio files and attaches ID3-tags to them&nbsp;&nbsp;&nbsp; # not yet implemented<br>
+</li>
+
+
+  <li>Provides both high-level and low-level classes for handling files with ID3-tags<br>
+</li>
+</ul>
+
+
+
+
+
+<h4><br>
+</h4>
+<h4>Module Constants:</h4>
+
+<ul>
+
+<li>
+ID3::SUPPORTED_SYMBOLS[version]</li>
+</ul>
+
+
+<h4>Module Methods:</h4>
+
+<ul>
+
+  <li>ID3.hasID3v1tag?(filename)</li>
+  <li>ID3.hasID3v2tag?(filename)</li>
+  <li>ID3.hasID3tag?(filename)</li>
+  <li>ID3.removeID3v1tag(filename)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+# ID3v1 tags aren't really very useful - that's why there is a special
+method to remove them<br>
+  </li>
+</ul>
+
+
+
+
+<h4>Classes:</h4>
+
+
+
+
+
+
+<ul>
+
+
+
+
+
+  
+  
+  <li><a href="Class_AudioFile.html">ID3::AudioFile</a><br>
+</li><li><a href="Class_Tag1.html">ID3::Tag1</a></li><li><a href="Class_Tag2.html">ID3::Tag2</a></li>
+  <li><a href="Class_Frame.html">ID3::Frame</a><br>
+  </li>
+
+
+</ul>
+
+<br>
+
+
+
+
+<h4>Examples:</h4>
+
+
+
+
+<pre>	&gt; require 'id3'<br>	=&gt; true<br><br>	&gt; ID3.hasID3tag?("mp3/a.mp3")<br>	=&gt; "1.0 2.3.0"<br><br>	&gt; ID3.hasID3tag?("mp3/b.mp3")<br>	=&gt; "2.2.0"<br><br>	&gt; ID3.hasID3tag?("mp3/c.mp3")<br>	=&gt; "1.1"<br><br>	&gt; ID3.hasID3tag?("mp3/d.mp3")<br>	=&gt; "1.1 2.3.0"<br><br>	&gt; `cp mp3/d.mp3 mp3/delete.mp3`<br>	=&gt; true<br><br>	&gt;  ID3.hasID3tag?("mp3/delete.mp3")<br>	=&gt; "1.1 2.3.0"<br>	&gt;  ID3.removeID3v1tag("mp3/delete.mp3")<br>	=&gt; true<br>	&gt;   ID3.hasID3tag?("mp3/delete.mp3")<br>	=&gt; "2.3.0"<br><br>	&gt; version = ID3.hasID3v2tag?("mp3/b.mp3")<br>	=&gt; "2.3.0"<br><br>	&gt; ID3::SUPPORTED_SYMBOLS[version].keys<br>	=&gt; ["PICTURE", "FILEOWNER", "CONDUCTOR", "EVENTTIMING", "DATE", "CRYPTOREG", "COMMENT", "POPULARIMETER", "GROUPINGREG", "PUBLISHER", "COPYRIGHT", "EQUALIZATION", "NETRADIOSTATION", "ORIGFILENAME", "WWWPUBLISHER", "BUFFERSIZE", "PLAYCOUNTER", "ISRC", "LYRICIST", "RECORDINGDATES", "SIZE", "INVOLVEDPEOPLE", "POSITIONSYNC", "WWWCOMMERCIALINFO", "PLAYLISTDELAY", "ORIGLYRICIST", "ALBUM", "SYNCEDLYRICS", "CONTENTTYPE", "SONGLEN", "MEDIATYPE", "WWWPAYMENT", "REVERB", "COMPOSER", "LINKEDINFO", "CONTENTGROUP", "BPM", "ORIGYEAR", "ORIGARTIST", "UNIQUEFILEID", "USERTEXT", "FILETYPE", "TIME", "PRIVATE", "SUBTITLE", "TERMSOFUSE", "BAND", "WWWCOPYRIGHT", "YEAR", "INITIALKEY", "SYNCEDTEMPO", "PARTINSET", "WWWUSER", "AUDIOCRYPTO", "MPEGLOOKUP", "VOLUMEADJ", "ORIGALBUM", "CDID", "ENCODEDBY", "WWWAUDIOFILE", "COMMERCIAL", "TITLE", "MIXARTIST", "NETRADIOOWNER", "TRACKNUM", "WWWAUDIOSOURCE", "GENERALOBJECT", "WWWRADIOPAGE", "LANGUAGE", "ENCODERSETTINGS", "WWWARTIST", "ARTIST", "UNSYNCEDLYRICS"]<br><br><br><br></pre>
+
+
+
+
+
+
+</body></html>

data/docs/id3.html

@@ -0,0 +1,245 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+  <title>id3.rb - ID3 Library for Ruby</title>
+
+  
+
+</head>
+<body><br>
+
+
+
+
+
+
+
+<center>
+<h1><font color="#ff0000">Pre-Beta Release</font><br>
+</h1>
+<h1>id3.rb - ID3 Library for Ruby<br><font size="-3">by Tilo Sloboda &lt;tools-NOSPAM@unixgods.org&gt;<br>
+</font></h1>
+
+</center>
+
+
+
+
+
+<h3><font color="#ff0000">Feedback Needed</font></h3>
+
+
+
+Currently I would like to get feedback on the interface, classes, methods provided by the ID3-library.
+<p>
+Please send me <a href="mailto:tools-NOSPAM@unixgods.org">email</a> and let me know what you think..<br>
+</p>
+
+<p><br>
+<br>
+</p>
+
+<h3>Introduction</h3>
+
+
+
+
+
+
+The aim of this ID3 library for Ruby is to do a full <b>native Ruby
+implementation </b>of ID3 version 1.x and version 2.x , without any use of
+binary libraries, which other implementations need to have installed
+separately.&nbsp;&nbsp;&nbsp; e.g. other implementations just act as a
+wrapper around a binary library - I beleive that this is not as
+portable as a Ruby library should be.<br>
+
+
+
+
+
+Another aim of this implementation is to provide the user with a
+uniform API, which tries to hide the details of the different ID3 standards,
+therefore making it (hopefully) easier to use.<br>
+
+&nbsp;<br>
+
+
+<h3>Supported Versions</h3>
+
+
+ID3 v1.0 , v1.1 , v2.2.x , v2.3.x and v2.4.x<br>
+
+
+<br>
+
+
+
+
+
+<h3>ID3 Library Overview</h3>
+
+
+
+
+
+The library provides  the <a href="Module_ID3.html">Module ID3</a> , which provides some module methods, as well as three simple classes to the user:&nbsp;&nbsp;
+<a href="Class_AudioFile.html">AudioFile</a>, <a href="Class_Tag1.html">Tag1</a> and <a href="Class_Tag2.html">Tag2</a>, to handle files which contain ID3-tags.<br>
+
+
+
+<br>
+
+
+
+The ID3-standards are overloaded with specially coded frames, which are different for each of the binary frames<font color="#ff0000"><sup>1</sup></font>.This
+library does not attempt to fully decode each and every frame type, but
+rather deals with the main frame types, such as text and web-frames,
+and in case of the binary frames hands the contents of the frames to
+the user verbatim.&nbsp; If the user chooses to modify or write any of
+those binary frames, the user is expected to know what s/he is doing,
+and how to code/de-code the binary contents, otherwise expect:&nbsp;
+"garbage in --&gt; crash!"&nbsp; of the application which tries to make
+sense of such frames later..&nbsp; However, if an ID3-tag contains
+binary frames, the user can expect that those are handed verbatim to
+the user and that it is safe to write them back 'as is' to a
+new/modified ID3-tag of the same audio file. In some cases the user may
+choose to delete some of the binary frames, that should be possible
+without problems.&nbsp;&nbsp; <br>
+
+
+
+
+
+<br>
+
+
+
+
+<h3>Download</h3>
+
+
+<br>
+
+
+<br>
+
+
+<h3>Known Problems</h3>
+
+
+Some ID3v2 frames may appear more than once in an ID3-tag!&nbsp; e.g.
+TXXX and WXXX. I haven't come across any actual examples for this,
+therefore didn't see the necessity to implement this.&nbsp;&nbsp;
+Currently there is no support for this.&nbsp; If you come across such
+cases, please let me know.. <br>
+
+
+<br>
+
+
+
+
+
+
+<h3>
+
+
+Documentation</h3>
+
+The main id3.rb documentation is here.<br>
+
+
+<br>
+
+
+I complied a comparison between the different <a href="http://www.unixgods.org/%7Etilo/ID3/docs/ID3_comparison.html">ID3-versions</a>, I hope it's helpful.<br>
+
+
+<br>
+
+
+<h3>Disclaimer / Author's Rant</h3>
+
+
+Please feel free to send me "constructive feedback"&nbsp;
+anytime.&nbsp;&nbsp; If you're missing functionality, or you think
+something should be done different, please let me know! I'm always open
+for suggestions. Thank you!<br>
+
+
+<br>
+
+
+IMHO the ID3 version2.x standards are pretty pretty messy... they are
+bloated and&nbsp; overloaded with useless frame-types and
+side-effects...&nbsp;&nbsp; The worst is ID3 v2.4.0!&nbsp; I haven't
+seen any actual v2.4.x tags yet, if you have examples, please send them
+to me. I suspect that the reason why I didn't find any v2.4.x tags
+anywhere is because the "2.4.x standard" is just too complicated, so
+nobody is using it..&nbsp; proove me wrong and email examples to me ;-)<br>
+
+
+<br>
+
+
+Last not least: Please don't complain about the "quality" of the
+ID3-standard to me.. I'm certainly most sympathetic with your pain, but
+not the right person to complain to.. ;-)<br>
+
+
+
+
+<br>
+
+
+
+
+<h3>License</h3>
+
+
+
+
+Freely available under the terms of the OpenSource "Artistic License" in combination with the Addendum A (below)<br>
+
+
+
+
+In case you did not get a copy of the license along with the software,
+it is also available at:&nbsp;&nbsp;
+http://www.unixgods.org/~tilo/artistic-license.html<br>
+
+
+
+
+<p>
+<font color="red">
+
+Addendum A. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 
+</font></p>
+
+
+
+<p>
+<font color="red">IN NO EVENT WILL THE COPYRIGHT HOLDERS BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
+LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR USELESS OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDERS OR OTHER PARTY HAS BEEN ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGES.<br>
+</font></p>
+
+
+
+<p>_________<br><font color="#ff0000">
+1</font>:&nbsp; who came up with all those special frame types? Cheez! KISS!&nbsp; (Keep It Simple, Stupid!)<br>
+ 
+</p>
+
+
+
+<p>
+
+</p>
+
+
+
+</body></html>