Class: TagLib::ID3v2::Tag

Inherits:
Tag
  • Object
show all
Defined in:
docs/taglib/id3v2.rb

Overview

An ID3v2 tag. A tag consists of a list of frames, identified by IDs.

Encoding

By default, taglib stores ID3v2 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 frame API directly:

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

Examples:

Read ID3v2 frames from a file

TagLib::MPEG::File.open("wake_up.mp3") do |file|
  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..."
end

Add frames and save file

TagLib::MPEG::File.open("joga.mp3") do |file|
  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
end

Instance Attribute Summary

Attributes inherited from Tag

#album, #artist, #comment, #genre, #title, #track, #year

Instance Method Summary collapse

Methods inherited from Tag

#empty?

Instance Method Details

#add_frame(frame) ⇒ void

This method returns an undefined value.

Add a frame to the tag.

Parameters:



90
91
 
# File 'docs/taglib/id3v2.rb', line 90

def add_frame(frame)
end

#frame_list ⇒ Array<TagLib::ID3v2::Frame> #frame_list(frame_id) ⇒ Array<TagLib::ID3v2::Frame>

Get a list of frames.

Note that the frames returned are subclasses of Frame, depending on the frame ID. But it's also possible that a UnknownFrame is returned (e.g. when TagLib discards a deprecated frame). So to make sure your code can handle all the cases, it should include a check for the returned class of the frame.

Overloads:

  • #frame_list ⇒ Array<TagLib::ID3v2::Frame>

    Returns all frames.

  • #frame_list(frame_id) ⇒ Array<TagLib::ID3v2::Frame>

    Returns frames matching ID.

    Parameters:

    • frame_id (String) —

      Specify this parameter to get only the frames matching a frame ID (e.g. "TIT2").

Returns:



83
84
 
# File 'docs/taglib/id3v2.rb', line 83

def frame_list
end

#remove_frame(frame) ⇒ void

This method returns an undefined value.

Remove the passed frame from the tag.

Note: You can and shall not call any methods on the frame object after you have passed it to this method, because the underlying C++ object has been deleted.

Parameters:

  • frame (Frame) —

    to remove



101
102
 
# File 'docs/taglib/id3v2.rb', line 101

def remove_frame(frame)
end

#remove_frames(id) ⇒ void

This method returns an undefined value.

Remove all frames with the specified ID from the tag.

Note: If you have obtained any frame objects with the same ID from the tag before calling this method, you should not touch them anymore. The reason is that the C++ objects may have been deleted.

Parameters:

  • id (String) 


112
113
 
# File 'docs/taglib/id3v2.rb', line 112

def remove_frames(id)
end