taglib-ruby

Ruby interface for the TagLib C++ library.

In contrast to other libraries, 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 is work in progress, but the following is already available:

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 audio properties (e.g. bitrate) of the above formats

Some things are still left to do (contributors very welcome):

Pre-compiled Gem for Windows:
- Unicode filename support
More coverage of the library

Installation

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

Debian/Ubuntu: sudo apt-get install libtag1-dev
Fedora/RHEL: sudo yum install taglib-devel
Brew: brew install taglib
MacPorts: sudo port install taglib

Then do:

gem install taglib-ruby

Usage

Complete API documentation can be found here:

http://rubydoc.info/gems/taglib-ruby/frames

What follows are some examples of how to use taglib-ruby. Here's how to read an ID3v2 tag:

require 'taglib'

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

# Read basic attributes
tag.title  #=> "Wake Up"
tag.artist  #=> "Arcade Fire"
tag.track  #=> 7

# 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..."

# Close file to release resources
file.close

And here's an example for writing one:

file = TagLib::MPEG::File.new("joga.mp3")
tag = file.id3v2_tag

# Write basic attributes
tag.artist = "Björk"
tag.title = "Jóga"

# Add attached picture frame
apic = TagLib::ID3v2::AttachedPictureFrame.new
apic.mime_type = "image/jpeg"
apic.description = "Cover"
apic.type = TagLib::ID3v2::AttachedPictureFrame::FrontCover
apic.picture = File.open("cover.jpg", 'rb'){ |f| f.read }

tag.add_frame(apic)

file.save
file.close

Encoding

By default, taglib stores text frames as ISO-8859-1 (Latin-1), if the text contains only characters that are available in that encoding. If not (e.g. with Cyrillic, Chinese, Japanese), it prints a warning and stores the text as UTF-8.

When you already know that you want to store the text as UTF-8, you can change the default text encoding:

frame_factory = TagLib::ID3v2::FrameFactory.instance
frame_factory.default_text_encoding = TagLib::String::UTF8

Another option is using the advanced API:

title = tag.frame_list('TIT2').first
title.text = "Jóga"
title.text_encoding = TagLib::String::UTF8

Release Notes

See CHANGES.

Contributing

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.

License

taglib-ruby is distributed under the MIT License, see LICENSE.txt for details.