ID3Tag

Native Ruby ID3 tag reader that aims for 100% coverage of ID3v2.x and ID3v1.x standards

Install

Make sure you are using ruby 2.2 or greater

Install ID3Tag at the command prompt:

gem install id3tag

Or add the gem to your Gemfile:

bundler add id3tag

How to use

Require the libary and read basic metadata:

require "id3tag"

mp3_file = File.open('/path/to/your/favorite_song.mp3', "rb")
tag = ID3Tag.read(mp3_file)
puts "#{tag.artist} - #{tag.title}"

ID3Tag::Tag class provides easy accessors to frames like artist, title, album, year, track_nr, genre, comments but you can read any frame by using get_frame(id) or get_frames(id) or browsing all frames by calling frames. When using easy accessors to frames like artist the reader will look for v.2.x tags artist frame first and if it can not find it artist frame from v1.x will be returned (if v1.x tag exists)

There can be more than one comments frame in the tag. They differ by language, too access specific comment frame an extra argument can be passed (Default is english). For example tag.comments(:lav) will look for comments in Latvian. Language codes can be seen here: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes

mp3s = Dir.entries("/some/dir").select { |filename| filename =~ /\.mp3/i }

mp3s.each do |file|
  ID3Tag.read(File.open(file, "rb")) do |tag|
    puts file
    puts tag.artist
    puts tag.title
    puts tag.album
    puts tag.year
    puts tag.track_nr
    puts tag.genre
    puts "---"
    puts tag.get_frame(:TIT2).content
    puts tag.get_frames(:COMM).first.content
    puts tag.get_frames(:COMM).last.language
  end
end

By default ID3Tag reads both v1.x and v2.x tags but it is possible to specify only one of them:

ID3Tag.read(file,:all) # default behaviour
ID3Tag.read(file,:v1) # Reads only v1.x tag
ID3Tag.read(file,:v2) # Reads only v2.x tag

You can inspect tag by calling frame_ids to see available frame ids or frames to return all frames

Configuration

# Configuration could be set using a block syntax.
ID3Tag.configuration do |c|

  # This way you can avoid Encoding::InvalidByteSequenceError when tag contains invalid data.
  # Currently only for String#encode which is used in TextFrames.
  # default: {}
  c.string_encode_options = { :invalid => :replace, :undef => :replace }

  # You might want to set v2.x tag read limit in bytes to avoid reading too much data into memory
  # v2 tags will be extracted until end of tag or limit is reached.
  # default: 0 (There are no limit)
  c.v2_tag_read_limit = 1048576 # 1 megabyte

  # In some situations, it's not possible to recognize what is the encoding of a
  # text frame. The default behavior is to raise UnsupportedTextEncoding, but
  # it's possible to set a fallback to avoid it.
  # default: nil
  c.source_encoding_fallback = Encoding::UTF_8

end

ID3Tag.configuration.v2_tag_read_limit # 1048576

ID3Tag.configuration.v2_tag_read_limit = 1024

ID3Tag.configuration.v2_tag_read_limit # 1024


# In case you would like to set configuration temporally you could use `local_configuration` method.
# Within this block you can read and modify configuration and it wont affect global or layers above.

ID3Tag.local_configuration do
  ID3Tag.configuration.v2_tag_read_limit # 1024
  ID3Tag.configuration.v2_tag_read_limit = 9999
  # ...
  ID3Tag.configuration.v2_tag_read_limit # 9999
end

ID3Tag.configuration.v2_tag_read_limit # 1024

ID3Tag.reset_configuration # Resets global configuration to defaults

ID3Tag.configuration.v2_tag_read_limit # 0

Features

Can read v1.x, v2.2.x, v2.3.x, v2.4.x tags
Supports UTF-8, UTF-16, UTF-16BE and ISO8859-1 encoding

Contributing to id3tag

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

krists/id3tag