Native Ruby mp3 tag reader library that aims for 100% covarage of ID3v2.x and ID3v1.x standards
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib returning to 100% code coverage Mar 16, 2016
spec Migration to latest RSpec Mar 16, 2016
standard_documents
.document Initial commit to id3tag. Dec 25, 2012
.gitignore gitignore updated Mar 16, 2016
.rspec Initial commit to id3tag. Dec 25, 2012
.travis.yml More specific versions for travis Mar 16, 2016
Gemfile
LICENSE.txt Initial commit to id3tag. Dec 25, 2012
README.md
Rakefile fixes for CI Jan 1, 2014
id3tag.gemspec Remove version constraint from bundler May 17, 2016

README.md

ID3Tag

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

Install

Make sure you are using ruby 1.9.2 or greater

Install ID3Tag at the command prompt:

gem install id3tag

Or add the gem to your Gemfile:

gem '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

It is also possible to provide configuration and overwrite default behaviour. Currently only for String#encode which is used in TextFrames.

This way you can avoid Encoding::InvalidByteSequenceError when tag contains invalid data.

ID3Tag.configuration do |c|
  c.string_encode_options = { :invalid => :replace, :undef => :replace }
end

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.

Code Status

Code Climate Build Status Coverage Status Gem Version

Copyright

Copyright (c) 2013 Krists Ozols. See LICENSE.txt for further details.