taglib-ruby

Ruby library for reading and writing meta-data (tags) of many audio formats

It’s based on the excellent TagLib C++ library, which is fast, full-featured and mature.

In contrast to other bindings, this one wraps the full C++ API, not only the minimal C API. This means that all tag data can be accessed, e.g. cover art of ID3v2 or custom fields of Ogg Vorbis comments.

taglib-ruby currently supports the following:

  • Reading/writing common tag data of all formats that TagLib supports
  • Reading/writing ID3v1 and ID3v2 including ID3v2.4 and Unicode
  • Reading/writing Ogg Vorbis comments
  • Reading/writing MP4 tags (.m4a)
  • Reading audio properties (e.g. bitrate) of the above formats

Before you install the gem, make sure to have taglib installed with header files (and a C++ compiler of course):

Debian/Ubuntusudo apt-get install libtag1-dev
Fedora/RHELsudo yum install taglib-devel
Homebrewbrew install taglib
MacPortssudo port install taglib

Windows users on Ruby 1.9 don't need that, because there is a pre-compiled binary gem available which bundles taglib.

Then install taglib-ruby (or add it to your Gemfile):

gem install taglib-ruby

There’s a basic API and format-specific APIs.

Basic API

The basic API can read all formats that TagLib supports and is easy to use. On the other hand, it only exposes some basic meta-data that is the same across all formats. Here’s an example:

require 'taglib'

# Load a file
TagLib::FileRef.open("wake_up.flac") do |fileref|
  unless fileref.null?
    tag = fileref.tag
    tag.title   #=> "Wake Up"
    tag.artist  #=> "Arcade Fire"
    tag.album   #=> "Funeral"
    tag.year    #=> 2004
    tag.track   #=> 7
    tag.genre   #=> "Indie Rock"
    tag.comment #=> nil

    properties = fileref.audio_properties
    properties.length  #=> 335 (song length in seconds)
  end
end  # File is automatically closed at block end

Format-specific API

For each format, there’s also an advanced API. It enables doing format-specific things. In the example, we’re reading ID3v2 frames and extract the attached picture from an ID3v2 tag:

require 'taglib'

# Load an ID3v2 tag from a file
TagLib::MPEG::File.open("wake_up.mp3") do |file|
  tag = file.id3v2_tag

  # Access all frames
  tag.frame_list.size  #=> 13

  # Track frame
  track = tag.frame_list('TRCK').first
  track.to_s  #=> "7/10"

  # Attached picture frame
  cover = tag.frame_list('APIC').first
  cover.mime_type  #=> "image/jpeg"
  cover.picture  #=> "\xFF\xD8\xFF\xE0\x00\x10JFIF..."
end  # File is automatically closed at block end

For more information please have a look at the complete documentation.