Class: ID3v2

Inherits:
Hash
  • Object
show all
Includes:
Mp3Info::HashKeys
Defined in:
lib/mp3info/id3v2.rb

Overview

This class is not intended to be used directly

Constant Summary collapse

WRITE_VERSION =

Major version used when writing tags

3
TAGS = 
{
  "AENC" => "Audio encryption",
  "APIC" => "Attached picture",
  "COMM" => "Comments",
  "COMR" => "Commercial frame",
  "ENCR" => "Encryption method registration",
  "EQUA" => "Equalization",
  "ETCO" => "Event timing codes",
  "GEOB" => "General encapsulated object",
  "GRID" => "Group identification registration",
  "IPLS" => "Involved people list",
  "LINK" => "Linked information",
  "MCDI" => "Music CD identifier",
  "MLLT" => "MPEG location lookup table",
  "OWNE" => "Ownership frame",
  "PRIV" => "Private frame",
  "PCNT" => "Play counter",
  "POPM" => "Popularimeter",
  "POSS" => "Position synchronisation frame",
  "RBUF" => "Recommended buffer size",
  "RVAD" => "Relative volume adjustment",
  "RVRB" => "Reverb",
  "SYLT" => "Synchronized lyric/text",
  "SYTC" => "Synchronized tempo codes",
  "TALB" => "Album/Movie/Show title",
  "TBPM" => "BPM (beats per minute)",
  "TCOM" => "Composer",
  "TCON" => "Content type",
  "TCOP" => "Copyright message",
  "TDAT" => "Date",
  "TDLY" => "Playlist delay",
  "TENC" => "Encoded by",
  "TEXT" => "Lyricist/Text writer",
  "TFLT" => "File type",
  "TIME" => "Time",
  "TIT1" => "Content group description",
  "TIT2" => "Title/songname/content description",
  "TIT3" => "Subtitle/Description refinement",
  "TKEY" => "Initial key",
  "TLAN" => "Language(s)",
  "TLEN" => "Length",
  "TMED" => "Media type",
  "TOAL" => "Original album/movie/show title",
  "TOFN" => "Original filename",
  "TOLY" => "Original lyricist(s)/text writer(s)",
  "TOPE" => "Original artist(s)/performer(s)",
  "TORY" => "Original release year",
  "TOWN" => "File owner/licensee",
  "TPE1" => "Lead performer(s)/Soloist(s)",
  "TPE2" => "Band/orchestra/accompaniment",
  "TPE3" => "Conductor/performer refinement",
  "TPE4" => "Interpreted, remixed, or otherwise modified by",
  "TPOS" => "Part of a set",
  "TPUB" => "Publisher",
  "TRCK" => "Track number/Position in set",
  "TRDA" => "Recording dates",
  "TRSN" => "Internet radio station name",
  "TRSO" => "Internet radio station owner",
  "TSIZ" => "Size",
  "TSRC" => "ISRC (international standard recording code)",
  "TSSE" => "Software/Hardware and settings used for encoding",
  "TYER" => "Year",
  "TXXX" => "User defined text information frame",
  "UFID" => "Unique file identifier",
  "USER" => "Terms of use",
  "USLT" => "Unsychronized lyric/text transcription",
  "WCOM" => "Commercial information",
  "WCOP" => "Copyright/Legal information",
  "WOAF" => "Official audio file webpage",
  "WOAR" => "Official artist/performer webpage",
  "WOAS" => "Official audio source webpage",
  "WORS" => "Official internet radio station homepage",
  "WPAY" => "Payment",
  "WPUB" => "Publishers official webpage",
  "WXXX" => "User defined URL link frame"
}
TEXT_ENCODINGS =

See id3v2.4.0-structure document, at section 4.

["iso-8859-1", "utf-16", "utf-16be", "utf-8"]

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Mp3Info::HashKeys

#method_missing

Constructor Details

#initialize(options = {}) ⇒ ID3v2

possible options are described above (‘options’ attribute) you can access this object like an hash, with [] and []= methods special cases are [“disc_number”] and [“disc_total”] mirroring TPOS attribute



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/mp3info/id3v2.rb', line 109

def initialize(options = {})
  @options = { 
    :lang => "ENG",
    :encoding => "iso-8859-1"
  }

  @options.update(options)
  @text_encoding_index = TEXT_ENCODINGS.index(@options[:encoding])
  
  unless @text_encoding_index
    raise(ArgumentError, "bad id3v2 text encoding specified")
  end

  @hash = {}
  #TAGS.keys.each { |k| @hash[k] = nil }
  @hash_orig = {}
  super(@hash)
  @parsed = false
  @version_maj = @version_min = nil
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Mp3Info::HashKeys

Instance Attribute Details

#io_position ⇒ Object (readonly)

this is the position in the file where the tag really ends



97
98
99
 
# File 'lib/mp3info/id3v2.rb', line 97

def io_position
  @io_position
end

#options ⇒ Object (readonly)

:lang: for writing comments

:encoding: one of the string of TEXT_ENCODINGS, used as a source and destination encoding respectively for read and write tag2 values.



104
105
106
 
# File 'lib/mp3info/id3v2.rb', line 104

def options
  @options
end

Instance Method Details

#changed? ⇒ Boolean

does this tag has been changed ?

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/mp3info/id3v2.rb', line 136

def changed?
  @hash_orig != @hash
end

#from_io(io) ⇒ Object

gets id3v2 tag information from io object (must support #seek() method)

Raises:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/mp3info/id3v2.rb', line 151

def from_io(io)
  @io = io
  original_pos = @io.pos
  @io.extend(Mp3Info::Mp3FileMethods)
  version_maj, version_min, flags = @io.read(3).unpack("CCB4")
  @unsync, ext_header, experimental, footer = (0..3).collect { |i| flags[i].chr == '1' }
  raise(ID3v2Error, "can't find version_maj ('#{version_maj}')") unless [2, 3, 4].include?(version_maj)
  @version_maj, @version_min = version_maj, version_min
  @tag_length = @io.get_syncsafe
  @io_position = original_pos + @tag_length
  
  @parsed = true
  begin
    case @version_maj
      when 2
        read_id3v2_2_frames
      when 3, 4
        # seek past extended header if present
        @io.seek(@io.get_syncsafe - 4, IO::SEEK_CUR) if ext_header
        read_id3v2_3_frames
    end
  rescue ID3v2Error => e
    warn("warning: id3v2 tag not fully parsed: #{e.message}")
  end

  @hash_orig = @hash.dup
  #no more reading
  @io = nil
end

#parsed? ⇒ Boolean

does this tag has been correctly read ?

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/mp3info/id3v2.rb', line 131

def parsed?
  @parsed
end

#to_bin ⇒ Object

dump tag for writing. Version is always 2.#WRITE_VERSION.0.



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/mp3info/id3v2.rb', line 182

def to_bin
  #TODO handle of @tag2[TLEN"]
  #TODO add of crc
  #TODO add restrictions tag

  tag = ""
  @hash.each do |k, v|
    next unless v
    next if v.respond_to?("empty?") and v.empty?
    # doesn't encode id3v2.2 tags, which have 3 characters
    next if k.size != 4 
    data = encode_tag(k, v.to_s, WRITE_VERSION)
    #data << "\x00"*2 #End of tag

    tag << k[0,4]   #4 characte max for a tag's key
    #tag << to_syncsafe(data.size) #+1 because of the language encoding byte
    size = data.size
    if RUBY_VERSION >= "1.9.0"
      size = data.dup.force_encoding("binary").size
    end
    tag << [size].pack("N") #+1 because of the language encoding byte
    tag << "\x00"*2 #flags
    tag << data
  end

  tag_str = "ID3"
  #version_maj, version_min, unsync, ext_header, experimental, footer 
  tag_str << [ WRITE_VERSION, 0, "0000" ].pack("CCB4")
  tag_str << [to_syncsafe(tag.size)].pack("N")
  tag_str << tag
  puts "tag in binary format: #{tag_str.inspect}" if $DEBUG
  tag_str
end

#version ⇒ Object

full version of this tag (like “2.3.0”) or nil if tag was not correctly read



142
143
144
145
146
147
148
 
# File 'lib/mp3info/id3v2.rb', line 142

def version
  if @version_maj && @version_min
    "2.#{@version_maj}.#{@version_min}"
  else
    nil
  end
end