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 reading and writing of:

  • Basic tag data of all formats that TagLib supports
  • ID3v1 and ID3v2 including v2.4, Unicode and attached pictures
  • Ogg Vorbis comments, MP4, WAV and AIFF tags

It also supports reading audio properties (e.g. bitrate) of the above formats.

Installation

Dependencies

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

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.

Gem

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

gem install taglib-ruby

Usage

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.