ruby-mp3info

Use Mp3Info.open to access an MP3 file. When used with a block, the file is automatically closed at the end of the block, which triggers the writing of any modified tags.

require "mp3info"

Mp3Info.open("myfile.mp3") do |mp3info|
  puts mp3info
end

Install the library using the standard Ruby gem command:

gem install ruby-mp3info

Note: If you are using Ruby 1.8, you must have iconv installed.

The ID3v2 class is used to decode and manipulate ID3v2 tags from files (e.g., .mp3, .ape). It behaves like a Hash, where keys are 3 or 4-character uppercase strings representing tag names (e.g., TIT2 for title, TPE1 for lead performer) and values are the tag data.

Key behaviors:

• Version Support: It can read ID3v2.2, v2.3, and v2.4 tags, but always writes tags in version 2.3 format.
• Tag Mapping: It automatically translates ID3v2.2 tags to their ID3v2.3 equivalents (e.g., TAL becomes TALB).
• Special Keys: It provides convenience keys disc_number and disc_total which mirror the TPOS attribute.
• Encoding: It handles Unicode translation for text-based tags.

# Example of how ID3v2 behaves like a hash
# (Assuming an instance 'id3' has been initialized and parsed)

title = id3["TIT2"]
artist = id3["TPE1"]
disc_num = id3["disc_number"]

To read MP3 metadata and audio properties, use the Mp3Info.open method. This is the recommended way to instantiate the object as it ensures the file is properly closed after processing. You can pass a filename or an IO object (like StringIO).

By default, the library parses both the MP3 audio headers and the ID3 tags. You can disable these via options:

• :parse_mp3 => false: Disables audio property extraction (bitrate, samplerate, etc.).
• :parse_tags => false: Disables ID3 tag reading/writing.
• :parse_tags also accepts an options hash passed to the underlying ID3v2 parser.

require 'mp3info'

# Recommended: use the block version to ensure the file is closed
Mp3Info.open("path/to/song.mp3") do |info|
  puts "Bitrate: #{info.bitrate} kbps"
  puts "Length: #{info.length} seconds"
  puts "Artist: #{info.tag[:artist]}"
end

For specific ID3v2 frames, use the tag2 attribute. You can access four-letter v2 tags using method calls or string keys.

Key behaviors:

• Access via method: mp3.tag2.TIT2
• Access via string key: mp3.tag2["TIT2"]
• COMM (Comments): The COMM tag can be configured using the options hash. For example, to set a language: mp3.tag2.options[:lang] = "FRE"

Limitations:

• Only ID3v2 version 2.3 is supported for writing.
• ID3v2 tags are always written using UTF-16 encoding.

require "mp3info"

Mp3Info.open("myfile.mp3") do |mp3|
  # Access and set via method
  puts mp3.tag2.TIT2
  mp3.tag2.TIT2 = "new TIT2"

  # Access via string key
  puts mp3.tag2["TIT2"]

  # Handling COMM tags with language options
  mp3.tag2.options[:lang] = "FRE"
  mp3.tag2.COMM = "my comment in french, correctly handled when reading and writing"
end

The Mp3Info#tag attribute provides access to standard tags. When reading, ID3v2 tags take priority over ID3v1 tags. When writing, both tag versions are updated.

Commonly used attributes include:

• title
• artist
• album
• tracknum

Changes are persisted to the file when Mp3Info#close is called or when the Mp3Info.open block terminates.

require "mp3info"

Mp3Info.open("myfile.mp3") do |mp3|
  puts mp3.tag.title
  puts mp3.tag.artist
  puts mp3.tag.album
  puts mp3.tag.tracknum

  mp3.tag.title = "track title"
  mp3.tag.artist = "artist name"
end

The #each_frame method allows you to iterate over every MPEG frame in the file. This is useful for low-level audio analysis or building tools like frame counters or cutters.

Each yielded frame is a Hash containing:

• :layer
• :bitrate
• :samplerate
• :mpeg_version
• :padding (boolean)
• :size (size in bytes)

info = Mp3Info.new("song.mp3")
info.each_frame do |frame|
  puts "Frame size: #{frame[:size]} bytes"
end

To populate an ID3v2 instance with data from a file, use the from_io(io) method. The io object must support the #seek() method.

Note: This method sets the @io_position attribute, which indicates the position in the file where the tag ends.

File.open('song.mp3', 'rb') do |file|
  id3 = ID3v2.new
  id3.from_io(file)
  puts id3["TIT2"]
end

The Mp3Info class provides several reader methods to access the technical properties of the MPEG audio stream:

• mpeg_version: The MPEG version (1 or 2).
• layer: The MPEG layer (1, 2, or 3).
• bitrate: The bitrate in kbps.
• samplerate: The sample rate in Hz.
• channel_mode: The channel mode (e.g., "Stereo", "JStereo", "Dual Channel", "Single Channel").
• vbr: Boolean indicating if the file is Variable Bitrate.
• length: The duration of the audio in seconds (Float).
• header: A hash representing values in the MP3 frame header (e.g., :private, :copyright, :original, :padding, :error_protection, :mode_extension, :emphasis).
• error_protection: Boolean indicating if error protection is present.