id3lib-ruby 0.1.0

data/lib/id3lib.rb

@@ -0,0 +1,349 @@
+
+require 'id3lib_api'
+require 'id3lib/info'
+require 'id3lib/accessors'
+
+
+#
+# This module includes all the classes and constants of id3lib-ruby.
+# Have a look at ID3Lib::Tag for an introduction on how to use this library.
+#
+module ID3Lib
+
+  # ID3 version 1. All V constants can be used with the methods
+  # new, update! or strip! of ID3Lib::Tag. 
+  V1     = 1
+  # ID3 version 2
+  V2     = 2
+  # No tag type
+  V_NONE = 0
+  # All tag types
+  V_ALL  = -1
+  # Both ID3 versions
+  V_BOTH = V1 | V2
+
+  NUM     = 0
+  ID      = 1
+  DESC    = 2
+  FIELDS  = 3  
+
+  #
+  # This class is the main frontend of the library.
+  # Use it to read and write ID3 tag data of files.
+  #
+  # === Example of use
+  #
+  #    tag = ID3Lib::Tag.read('shy_boy.mp3')
+  #
+  #    # Remove comments
+  #    tag.delete_if{ |frame| frame[:id] == :COMM }
+  #
+  #    # Set year
+  #    tag.year   #=> 2000
+  #    tag.year = 2005
+  #
+  #    # Apply changes
+  #    tag.update!
+  #
+  # === Working with tags
+  #
+  # You can use a ID3Lib::Tag object like an array. In fact, it is a subclass
+  # of Array. An ID3Lib::Tag contains frames which are stored as hashes,
+  # with field IDs as keys and field values as values. The frame IDs like TIT2
+  # are the ones specified by the ID3 standard. If you don't know these IDs,
+  # you probably want to use the accessor methods described afterwards, which
+  # have a more natural naming.
+  #
+  #    tag.each do |frame|
+  #      p frame
+  #    end
+  #    #=> {:id => :TIT2, :text => "Shy Boy", :textenc => 0}
+  #    #=> {:id => :TPE1, :text => "Katie Melua", :textenc => 0}
+  #    #=> {:id => :TALB, :text => "Piece By Piece", :textenc => 0}
+  #    #=> {:id => :TRCK, :text => "1/12", :textenc => 0}
+  #    #=> {:id => :TYER, :text => "2005", :textenc => 0}
+  #    #=> {:id => :TCON, :text => "Jazz/Blues", :textenc => 0}
+  #
+  # === Get and set frames
+  #
+  # There are a number of accessors for text frames like
+  # title, performer, album, track, year, comment and genre. Have a look
+  # at ID3Lib::Accessors for a complete list.
+  #
+  #    tag.title    #=> "Shy Boi"
+  #
+  #    tag.title = 'Shy Boy'
+  #    tag.title    #=> "Shy Boy"
+  #
+  #    tag.track    #=> [1,12]
+  #    tag.year     #=> 2005
+  #
+  # You can always read and write the raw text if you want. You just have
+  # to use the "manual access". It is generally encouraged to use the
+  # #frame_text method where possible, because the other two result in
+  # an exception when the frame isn't found.
+  #
+  #    tag.frame_text(:TRCK)                  #=> "1/12"
+  #    tag.frame_text(:TLAN)                  #=> nil
+  #
+  #    tag.frame(:TRCK)[:text]                #=> "1/12"
+  #    # Raises an exception, because nil[:text] isn't possible:
+  #    tag.frame(:TLAN)[:text]
+  #
+  #    tag.find{ |f| f[:id] == :TRCK }[:text] #=> "1/12"
+  #    # Also raises an exception:
+  #    tag.find{ |f| f[:id] == :TLAN }[:text]
+  #
+  # Because only text frames can be set with accessors, you have to add
+  # special frames by hand.
+  #
+  #    # Add two comments
+  #    tag << {:id => :COMM, :text => 'chunky bacon'}
+  #    tag << {:id => :COMM, :text => 'really.'}
+  #
+  #    # Add an attached picture
+  #    cover = {
+  #      :id          => :APIC,
+  #      :mimetype    => 'image/jpeg',
+  #      :picturetype => 3,
+  #      :description => 'A pretty picture',
+  #      :textenc     => 0,
+  #      :data        => File.read('cover.jpg')
+  #    }
+  #    tag << cover
+  #
+  # === Get information about frames
+  #
+  # In the last example we added an APIC frame. How can we know what data
+  # we have to store in the APIC hash?
+  #
+  #    ID3Lib::Info.frame(:APIC)[3]
+  #    #=> [:textenc, :mimetype, :picturetype, :description, :data]
+  #
+  # We see, the last element of the info array obtained through
+  # ID3Lib::Info.frame is an array of field IDs needed by APIC.
+  #
+  # Have a look at the ID3Lib::Info module for detailed information.
+  #
+  # === Write changes to file
+  #
+  # When you've finished modifying a tag, don't forget to call #update! to
+  # write the modifications back to the file. You have to check the return
+  # value of update!, it returns nil on failure. This probably means that
+  # the file is not writeable or cannot be created.
+  #
+  #    tag.update!
+  #
+  # === Getting rid of a tag
+  #
+  # Use the #strip! method to completely remove a tag from a file.
+  #
+  #    tag.strip!
+  #
+  class Tag < Array
+
+    include Accessors
+
+    attr_accessor :padding
+
+    #
+    # Create a new Tag. When a _filename_ is supplied, the tag of the file
+    # is read. _tagtype_ specifies the tag type to read and defaults to
+    # V_ALL.
+    # Use one of ID3Lib::V1, ID3Lib::V2, ID3Lib::V_BOTH or ID3Lib::V_ALL.
+    #
+    #    tag = ID3Lib::Tag.new('shy_boy.mp3')
+    # 
+    # Only read ID3v1 tag:
+    #
+    #    id3v1_tag = ID3Lib::Tag.new('piece_by_piece.mp3', ID3Lib::V1)
+    #
+    def initialize(filename, readtype=V_ALL)
+      @filename = filename
+      @readtype = readtype
+      @padding = true
+
+      @tag = API::Tag.new
+      @tag.link(@filename, @readtype)
+      read_frames
+    end
+
+    #
+    # Returns an estimate of the number of bytes required to store the tag
+    # data.
+    #
+    def size
+      @tag.size
+    end
+
+    #
+    # Simple shortcut for getting a frame by its _id_.
+    #
+    #    tag.frame(:TIT2)
+    #    #=> {:id => :TIT2, :text => "Shy Boy", :textenc => 0}
+    #
+    # is the same as:
+    #
+    #    tag.find{ |f| f[:id] == :TIT2 }
+    #
+    def frame(id)
+      find{ |f| f[:id] == id }
+    end
+
+    #
+    # Get the text of a frame specified by _id_. Returns nil if the
+    # frame can't be found.
+    #
+    #    tag.find{ |f| f[:id] == :TIT2 }[:text]  #=> "Shy Boy"
+    #    tag.frame_text(:TIT2)                   #=> "Shy Boy"
+    #
+    #    tag.find{ |f| f[:id] == :TLAN }         #=> nil
+    #    tag.frame_text(:TLAN)                   #=> nil
+    #
+    def frame_text(id)
+      f = frame(id)
+      f ? f[:text] : nil
+    end
+
+    #
+    # Set the text of a frame. First, all frames with the specified _id_ are
+    # deleted and then a new frame with _text_ is appended.
+    #
+    #    tag.set_frame_text(:TLAN, 'eng')
+    #
+    def set_frame_text(id, text)
+      remove_frame(id)
+      self << { :id => id, :text => text }
+    end
+
+    #
+    # Remove all frames with the specified _id_.
+    #
+    def remove_frame(id)
+      delete_if{ |f| f[:id] == id }
+    end
+
+    #
+    # Updates the tag. This change can't be undone. _writetype_ specifies
+    # which tag type to write and defaults to _readtype_ (see #new).
+    #
+    # Returns a number corresponding to the written tag type(s) or nil if
+    # the update failed.
+    #
+    #    tag.update!
+    #    id3v1_tag.update!(ID3Lib::V1)
+    #
+    def update!(writetype=@readtype)
+      @tag.strip(writetype)
+      # The following two lines are necessary because of the weird
+      # behaviour of id3lib.
+      @tag.clear
+      @tag.link(@filename, writetype)
+
+      delete_if do |frame|
+        frame_info = Info.frame(frame[:id])
+        next true if not frame_info
+        libframe = API::Frame.new(frame_info[NUM])
+        Frame.write(frame, libframe)
+        @tag.add_frame(libframe)
+        false
+      end
+
+      @tag.set_padding(@padding)
+      tags = @tag.update(writetype)
+      return tags == 0 ? nil : tags
+    end
+
+    #
+    # Strip tag from file. This is dangerous because you lose all tag
+    # information. Specify _striptag_ to only strip a certain tag type.
+    # You don't have to call #update! after #strip!.
+    #
+    #    tag.strip!
+    #    another_tag.strip!(ID3Lib::V1)
+    #
+    def strip!(striptype=V_ALL)
+      clear
+      tags = @tag.strip(striptype)
+      @tag.clear
+      @tag.link(@filename, @readtype)
+      tags
+    end
+
+    #
+    # Check if there is a tag of type _type_.
+    # 
+    def has_tag?(type=V2)
+      @tag.link(@filename, V_ALL)
+      @tag.has_tag_type(type)
+    end
+
+    private
+
+    def read_frames
+      iterator = @tag.iterator_new
+      while libframe = @tag.iterator_next_frame(iterator)
+        self << Frame.read(libframe)
+      end
+    end
+
+  end
+
+
+  module Frame #:nodoc:
+
+    def self.read(libframe)
+      frame = {}
+      info = Info.frame(libframe.num)
+      frame[:id] = info[ID]
+      if info[FIELDS].include?(:textenc)
+        textenc = field(libframe, :textenc).integer
+        frame[:textenc] = textenc
+      end
+      info[FIELDS].each do |field_id|
+        next if field_id == :textenc
+        libfield = field(libframe, field_id)
+        frame[field_id] = if textenc and textenc > 0
+          libfield.unicode
+        else
+          case Info::FieldType[libfield.type]
+          when :integer : libfield.integer
+          when :binary  : libfield.binary
+          when :text    : libfield.ascii
+          end
+        end
+      end
+      frame
+    end
+
+    def self.write(frame, libframe)
+      textenc = frame[:textenc]
+      field(libframe, :textenc).set_integer(textenc) if textenc
+      frame.each do |field_id, value|
+        unless Info.frame(frame[:id])[FIELDS].include?(field_id)
+          # TODO: Add method to check if frames are valid.
+          next
+        end
+        next if field_id == :textenc
+        libfield = field(libframe, field_id)
+        if textenc and textenc > 0
+          libfield.set_encoding(textenc)
+          libfield.set_unicode(value)
+        else
+          case Info::FieldType[libfield.type]
+          when :integer : libfield.set_integer(value)
+          when :binary  : libfield.set_binary(value)
+          when :text    : libfield.set_ascii(value)
+          end
+        end
+      end
+    end
+
+    def self.field(libframe, id)
+      libframe.field(Info.field(id)[NUM])
+    end
+            
+  end
+
+
+end

data/lib/id3lib/accessors.rb

@@ -0,0 +1,260 @@
+
+module ID3Lib
+
+  #
+  # The Accessors module defines accessor methods for ID3 text frames.
+  #
+  # Have a look at the source code to see the ID3 frame ID behind an accessor.
+  #
+  # === Most used accessors
+  #
+  # Here's a list of the probably most used accessors:
+  #
+  # * #title
+  # * #performer or #artist
+  # * #album
+  # * #genre
+  # * #year
+  # * #track
+  # * #part_of_set or #disc
+  # * #comment or #comment_frames
+  # * #composer
+  # * #bpm
+  #
+  # === Automatic conversion
+  #
+  # Some accessors automatically convert the raw text to a more
+  # suitable type (when reading) and back (when writing). For example,
+  # the track information is converted to an array of one or two items.
+  #
+  #    tag.track    #=> [1,12]
+  #
+  # and the year is an integer.
+  #
+  #    tag.year     #=> 2005
+  #
+  # Use the Tag#frame_text method to get the raw text.
+  #
+  #    tag.frame_text(:TRCK)  #=> "1/12"
+  #
+  module Accessors
+
+    def title()       frame_text(:TIT2) end
+    def title=(v) set_frame_text(:TIT2, v) end
+
+    def performer()       frame_text(:TPE1) end
+    def performer=(v) set_frame_text(:TPE1, v) end
+    alias_method :artist, :performer
+    alias_method :artist=, :performer=
+
+    def album()       frame_text(:TALB) end
+    def album=(v) set_frame_text(:TALB, v) end
+
+    def comment()       frame_text(:COMM) end
+    def comment=(v) set_frame_text(:COMM, v) end
+
+    def genre()       frame_text(:TCON) end
+    def genre=(v) set_frame_text(:TCON, v) end
+    alias_method :content_type, :genre
+    alias_method :content_type=, :genre=
+
+    def bpm()       frame_text(:TBPM) end
+    def bpm=(v) set_frame_text(:TBPM, v.to_s) end
+
+    def composer()       frame_text(:TCOM) end
+    def composer=(v) set_frame_text(:TCOM, v) end
+
+    def copyright()       frame_text(:TCOP) end
+    def copyright=(v) set_frame_text(:TCOP, v) end
+
+    def date()       frame_text(:TDAT) end
+    def date=(v) set_frame_text(:TDAT, v) end
+
+    def encoding_time()       frame_text(:TDEN) end
+    def encoding_time=(v) set_frame_text(:TDEN, v) end
+
+    def playlist_delay()       frame_text(:TDLY) end
+    def playlist_delay=(v) set_frame_text(:TDLY, v) end
+
+    def original_release_time()       frame_text(:TDOR) end
+    def original_release_time=(v) set_frame_text(:TDOR, v) end
+
+    def recording_time()       frame_text(:TDRC) end
+    def recording_time=(v) set_frame_text(:TDRC, v) end
+
+    def release_time()       frame_text(:TDRL) end
+    def release_time=(v) set_frame_text(:TDRL, v) end
+
+    def tagging_time()       frame_text(:TDTG) end
+    def tagging_time=(v) set_frame_text(:TDTG, v) end
+
+    def involved_people()       frame_text(:TIPL) end
+    def involved_people=(v) set_frame_text(:TIPL, v) end
+
+    def encoded_by()       frame_text(:TENC) end
+    def encoded_by=(v) set_frame_text(:TENC, v) end
+
+    def lyricist()       frame_text(:TEXT) end
+    def lyricist=(v) set_frame_text(:TEXT, v) end
+
+    def file_type()       frame_text(:TFLT) end
+    def file_type=(v) set_frame_text(:TFLT, v) end
+
+    def time()       frame_text(:TIME) end
+    def time=(v) set_frame_text(:TIME, v) end
+
+    def content_group()       frame_text(:TIT1) end
+    def content_group=(v) set_frame_text(:TIT1, v) end
+
+    def subtitle()       frame_text(:TIT3) end
+    def subtitle=(v) set_frame_text(:TIT3, v) end
+
+    def initial_key()       frame_text(:TKEY) end
+    def initial_key=(v) set_frame_text(:TKEY, v) end
+
+    def language()       frame_text(:TLAN) end
+    def language=(v) set_frame_text(:TLAN, v) end
+
+    def audio_length()       frame_text(:TLEN) end
+    def audio_length=(v) set_frame_text(:TLEN, v) end
+
+    def musician_credits()       frame_text(:TMCL) end
+    def musician_credits=(v) set_frame_text(:TMCL, v) end
+
+    def media_type()       frame_text(:TMED) end
+    def media_type=(v) set_frame_text(:TMED, v) end
+
+    def mood()       frame_text(:TMOO) end
+    def mood=(v) set_frame_text(:TMOO, v) end
+
+    def original_title()       frame_text(:TOAL) end
+    def original_title=(v) set_frame_text(:TOAL, v) end
+
+    def original_filename()       frame_text(:TOFN) end
+    def original_filename=(v) set_frame_text(:TOFN, v) end
+
+    def original_lyricist()       frame_text(:TOLY) end
+    def original_lyricist=(v) set_frame_text(:TOLY, v) end
+
+    def original_performer()       frame_text(:TOPE) end
+    def original_performer=(v) set_frame_text(:TOPE, v) end
+
+    def file_owner()       frame_text(:TOWN) end
+    def file_owner=(v) set_frame_text(:TOWN, v) end
+
+    def band()       frame_text(:TPE2) end
+    def band=(v) set_frame_text(:TPE2, v) end
+
+    def conductor()       frame_text(:TPE3) end
+    def conductor=(v) set_frame_text(:TPE3, v) end
+
+    def produced_notice()       frame_text(:TPRO) end
+    def produced_notice=(v) set_frame_text(:TPRO, v) end
+
+    def publisher()       frame_text(:TPUB) end
+    def publisher=(v) set_frame_text(:TPUB, v) end
+
+    def internet_radio_station()       frame_text(:TRSN) end
+    def internet_radio_station=(v) set_frame_text(:TRSN, v) end
+
+    def internet_radio_owner()       frame_text(:TRSO) end
+    def internet_radio_owner=(v) set_frame_text(:TRSO, v) end
+
+    def album_sort_order()       frame_text(:TSOA) end
+    def album_sort_order=(v) set_frame_text(:TSOA, v) end
+
+    def performer_sort_order()       frame_text(:TSOP) end
+    def performer_sort_order=(v) set_frame_text(:TSOP, v) end
+
+    def title_sort_order()       frame_text(:TSOT) end
+    def title_sort_order=(v) set_frame_text(:TSOT, v) end
+
+    def isrc()       frame_text(:TSRC) end
+    def isrc=(v) set_frame_text(:TSRC, v) end
+
+    def encoder_settings()       frame_text(:TSSE) end
+    def encoder_settings=(v) set_frame_text(:TSSE, v) end
+
+    def set_subtitle()       frame_text(:TSST) end
+    def set_subtitle=(v) set_frame_text(:TSST, v) end
+
+    def terms_of_use()       frame_text(:TPE2) end
+    def terms_of_use=(v) set_frame_text(:TPE2, v) end
+
+    def commercial_url()       frame_text(:WCOM) end
+    def commercial_url=(v) set_frame_text(:WCOM, v) end
+
+    def copyright_url()       frame_text(:WCOP) end
+    def copyright_url=(v) set_frame_text(:WCOP, v) end
+
+    def audio_file_url()       frame_text(:WOAF) end
+    def audio_file_url=(v) set_frame_text(:WOAF, v) end
+
+    def performer_url()       frame_text(:WOAR) end
+    def performer_url=(v) set_frame_text(:WOAR, v) end
+
+    def audio_source_url()       frame_text(:WOAS) end
+    def audio_source_url=(v) set_frame_text(:WOAS, v) end
+
+    def internet_radio_url()       frame_text(:WORS) end
+    def internet_radio_url=(v) set_frame_text(:WORS, v) end
+
+    def payment_url()       frame_text(:WPAY) end
+    def payment_url=(v) set_frame_text(:WPAY, v) end
+
+    def publisher_url()       frame_text(:WPUB) end
+    def publisher_url=(v) set_frame_text(:WPUB, v) end
+
+    # Returns an array of comment frames.
+    def comment_frames() select{ |f| f[:id] == :COMM } end
+
+    #
+    # Returns an array of one or two numbers.
+    #
+    #    tag.track                #=> [3,11]
+    #    tag.frame_text(:TRCK)    #=> "3/11"
+    #
+    #    tag_2.track              #=> [5]
+    #    tag_2.frame_text(:TRCK)  #=> "5"
+    #
+    def track() frame_text(:TRCK).split('/').collect{ |s| s.to_i } end
+
+    #
+    # Assign either an array or a string.
+    #
+    #    tag.track = [4,11]
+    #    tag.track = [5]
+    #    tag.track = "4/11"
+    #
+    def track=(v) set_frame_text(:TRCK, (v.join('/') rescue v.to_s)) end
+
+    #
+    # Returns an array of one or two numbers like #track.
+    #
+    def part_of_set() frame_text(:TPOS).split('/').collect{ |s| s.to_i } end
+    alias_method :disc, :part_of_set
+
+    #
+    # Assign either an array or a string like #track=.
+    #
+    def part_of_set=(v) set_frame_text(:TPOS, (v.join('/') rescue v.to_s)) end
+    alias_method :disc=, :part_of_set=
+
+    #
+    # Returns a number.
+    #
+    #    tag.year   #=> 2004
+    #
+    def year() frame_text(:TYER).to_i end
+
+    #
+    # Assign a number or a string.
+    #
+    #    tag.year = 2005
+    #    tag.year = "2005"
+    #
+    def year=(v) set_frame_text(:TYER, v.to_s) end
+
+  end
+
+end