taglib-ruby 0.1.1 → 0.2.0

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--markup-provider redcarpet
+--charset UTF-8
+--template-path docs
+docs/**/*.rb
+-
+README.md
+CHANGES.md
+LICENSE.txt

data/CHANGES.md

@@ -0,0 +1,22 @@
+Changes in Releases of taglib-ruby
+==================================
+
+## 0.2.0 (2011-10-22)
+
+* API documentation
+* Add support for:
+  * TagLib::AudioProperties and TagLib::MPEG::Properties (#4)
+  * TagLib::ID3v2::RelativeVolumeFrame
+
+## 0.1.1 (2011-09-17)
+
+* Add installation instructions and clean up description
+
+## 0.1.0 (2011-09-17)
+
+* Initial release
+* Coverage of the following API:
+  * TagLib::FileRef
+  * TagLib::MPEG::File
+  * TagLib::ID3v2::Tag
+  * TagLib::ID3v2::Frame and subclasses

data/Gemfile

@@ -7,5 +7,7 @@ group :development do
   gem 'bundler', '~> 1.0.0'
   gem 'jeweler', '~> 1.6.4'
   gem 'rcov', '>= 0'
-  gem 'rdoc', '~> 3.9'
+  gem 'yard', '~> 0.7'
+  gem 'redcarpet'
+  gem 'guard-test', '~> 0.4.0'
 end

data/Gemfile.lock

@@ -2,6 +2,11 @@ GEM
   remote: http://rubygems.org/
   specs:
     git (1.2.5)
+    guard (0.8.4)
+      thor (~> 0.14.6)
+    guard-test (0.4.0)
+      guard (>= 0.4)
+      test-unit (~> 2.2)
     jeweler (1.6.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
@@ -9,17 +14,22 @@ GEM
     rake (0.9.2)
     rake-compiler (0.7.9)
       rake
-    rcov (0.9.10)
-    rdoc (3.9.4)
+    rcov (0.9.11)
+    redcarpet (1.17.2)
     shoulda (2.11.3)
+    test-unit (2.4.0)
+    thor (0.14.6)
+    yard (0.7.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.0.0)
+  guard-test (~> 0.4.0)
   jeweler (~> 1.6.4)
   rake-compiler (~> 0.7)
   rcov
-  rdoc (~> 3.9)
+  redcarpet
   shoulda (~> 2.11)
+  yard (~> 0.7)

data/Guardfile

@@ -0,0 +1,8 @@
+# Guardfile for tests
+# More info at https://github.com/guard/guard#readme
+
+guard :test do
+  watch(%r{^lib/(.+)\.so$})     { "test" }
+  watch('test/test_helper.rb')  { "test" }
+  watch(%r{^test/test_.+\.rb$})
+end

data/README.md

@@ -10,7 +10,6 @@ accessed.
 taglib-ruby is work in progress, here are some of the things still left
 to do (contributors very welcome):
 
-* Wrap TagLib::MPEG::Properties
 * Pre-compiled Gem for Windows
 * More coverage of the library besides ID3v2
 
@@ -34,48 +33,52 @@ Usage
 
 Here's an example for reading an ID3v2 tag:
 
-    require 'taglib'
+```ruby
+require 'taglib'
 
-    # Load an ID3v2 tag from a file
-    file = TagLib::MPEG::File.new("wake_up.mp3")
-    tag = file.id3v2_tag
+# 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
+# Read basic attributes
+tag.title  #=> "Wake Up"
+tag.artist  #=> "Arcade Fire"
+tag.track  #=> 7
 
-    # Access all frames
-    tag.frame_list.size  #=> 13
+# Access all frames
+tag.frame_list.size  #=> 13
 
-    # Track frame
-    track = tag.frame_list('TRCK').first
-    track.to_s  #=> "7/10"
+# 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..."
+# Attached picture frame
+cover = tag.frame_list('APIC').first
+cover.mime_type  #=> "image/jpeg"
+cover.picture  #=> "\xFF\xD8\xFF\xE0\x00\x10JFIF..."
+```
 
 And here's an example for writing one:
 
-    file = TagLib::MPEG::File.new("joga.mp3")
-    tag = file.id3v2_tag
+```ruby
+file = TagLib::MPEG::File.new("joga.mp3")
+tag = file.id3v2_tag
 
-    # Write basic attributes
-    tag.artist = "Björk"
-    tag.title = "Jóga"
+# 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 }
+# 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)
+tag.add_frame(apic)
 
-    file.save
+file.save
+```
 
 ### Encoding
 
@@ -87,14 +90,23 @@ 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
+```ruby
+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
+```ruby
+title = tag.frame_list('TIT2').first
+title.text = "Jóga"
+title.text_encoding = TagLib::String::UTF8
+```
+
+Release Notes
+-------------
+
+See {file:CHANGES.md}.
 
 Contributing
 ------------

data/Rakefile

@@ -58,12 +58,10 @@ end
 
 task :default => :test
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
   version = TagLib::Version::STRING
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "taglib-ruby #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  t.options = ['--title', "taglib-ruby #{version}"]
 end
+
+FileList['tasks/**/*.rake'].each { |task| import task }

data/docs/default/fulldoc/html/css/common.css

@@ -0,0 +1 @@
+.showSource { display: none; }

data/docs/taglib/base.rb

@@ -0,0 +1,130 @@
+# This is the top-level module of taglib-ruby.
+#
+# Where to find what:
+#
+# * Reading/writing basic tag and audio properties without having to
+#   know the tagging format: {TagLib::FileRef}
+# * Reading properties of MPEG files: {TagLib::MPEG::File}
+# * Reading/writing ID3v2 tags: {TagLib::MPEG::File} and
+#   {TagLib::MPEG::File#id3v2_tag}
+# 
+# ## String Encodings
+#
+# Sometimes, it is necessary to specify which encoding should be used to
+# store strings in tags. For this, the following constants are defined:
+#
+# * `TagLib::String::Latin1`
+# * `TagLib::String::UTF16`
+# * `TagLib::String::UTF16BE`
+# * `TagLib::String::UTF8`
+# * `TagLib::String::UTF16LE`
+#
+# For ID3v2 frames, you can also set a default text encoding globally
+# using the {TagLib::ID3v2::FrameFactory}.
+module TagLib
+
+  # This class allows to read basic tagging and audio properties from
+  # files, without having to know what the file type is. Thus, it works
+  # for all tagging formats that taglib supports, but only provides a
+  # minimal API.
+  #
+  # Should you need more, use the file type specific classes, see
+  # subclasses of {TagLib::File}.
+  class FileRef
+    # Create a FileRef from a file name.
+    #
+    # @param [String] filename
+    # @param [Boolean] read_audio_properties
+    #   true if audio properties should be read
+    # @param [TagLib::AudioProperties constants] audio_properties_style
+    #   how accurately the audio properties should be read, e.g.
+    #   {TagLib::AudioProperties::Average}
+    def initialize(filename, read_audio_properties=true,
+                   audio_properties_style=TagLib::AudioProperties::Average)
+    end
+
+    # @return [TagLib::AudioProperties] the audio properties
+    def audio_properties
+    end
+
+    # @return [Boolean] if the file is null (i.e. it could not be read)
+    def null?
+    end
+
+    # Saves the file
+    #
+    # @return [Boolean] whether saving was successful
+    def save
+    end
+
+    # @return [TagLib::Tag] the tag
+    def tag
+    end
+  end
+
+  # @abstract Base class for files, see subclasses.
+  class File
+  end
+
+  # @abstract Base class for tags.
+  #
+  # This is a unified view which provides basic tag information, which
+  # is common in all tag formats. See subclasses for functionality that
+  # goes beyond this interface.
+  class Tag
+    # @return [String] the album
+    # @return [nil] if not present
+    attr_accessor :album
+
+    # @return [String] the artist/interpret
+    # @return [nil] if not present
+    attr_accessor :artist
+
+    # @return [String] the comment
+    # @return [nil] if not present
+    attr_accessor :comment
+
+    # @return [String] the genre
+    # @return [nil] if not present
+    attr_accessor :genre
+
+    # @return [String] the title
+    # @return [nil] if not present
+    attr_accessor :title
+
+    # @return [Integer] the track number
+    # @return [0] if not present
+    attr_accessor :track
+
+    # @return [Integer] the year
+    # @return [0] if not present
+    attr_accessor :year
+
+    # @return [Boolean]
+    def empty?; end
+  end
+
+  # @abstract Base class for audio properties.
+  class AudioProperties
+
+    Fast = 0
+    Average = 1
+    Accurate = 2
+
+    # @return [Integer] length of the file in seconds
+    def length
+    end
+
+    # @return [Integer] bit rate in kb/s (kilobit per second)
+    def bitrate
+    end
+
+    # @return [Integer] sample rate in Hz
+    def sample_rate
+    end
+
+    # @return [Integer] number of channels
+    def channels
+    end
+  end
+end

data/docs/taglib/id3v2.rb

@@ -0,0 +1,383 @@
+module TagLib::ID3v2
+  # An ID3v2 tag.
+  class Tag < TagLib::Tag
+    # Get a list of frames. Note that the frames returned are subclasses
+    # of {TagLib::ID3v2::Frame}, depending on the frame ID.
+    #
+    # @overload frame_list()
+    #   Returns all frames.
+    #
+    # @overload frame_list(frame_id)
+    #   Returns frames matching ID.
+    #
+    #   @param [String] frame_id Specify this parameter to get only the
+    #     frames matching a frame ID (e.g. "TIT2").
+    #
+    # @return [Array<TagLib::ID3v2::Frame>]
+    def frame_list
+    end
+
+    # Add a frame to the tag.
+    #
+    # @param [Frame] frame
+    # @return [void]
+    def add_frame(frame)
+    end
+
+    # 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.
+    #
+    # @param [Frame] frame to remove
+    # @return [void]
+    def remove_frame(frame)
+    end
+
+    # 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.
+    #
+    # @param [String] id
+    # @return [void]
+    def remove_frames(id)
+    end
+  end
+
+  # Frame factory for ID3v2 frames. Useful for setting the default text
+  # encoding.
+  class FrameFactory
+    # @return [FrameFactory] the default frame factory
+    def self.instance
+    end
+
+    # Get/set the default text encoding for new ID3v2 frames. See the
+    # section _String Encodings_ in {TagLib}.
+    #
+    # @return [TagLib::String constant] default text encoding
+    attr_accessor :default_text_encoding
+  end
+
+  # The base class for all ID3v2 frames.
+  #
+  # In ID3v2 all frames are identified by a {#frame_id frame ID}, such
+  # as `TIT2` or `APIC`. The data in the frames is different depending
+  # on the frame type, which is why there is a subclass for each type.
+  #
+  # The most common frame type is the text identification frame. All
+  # frame IDs of this type begin with `T`, for example `TALB` for the
+  # album. See {TextIdentificationFrame}.
+  #
+  # Then there are the URL link frames, which begin with `W`, see
+  # {UrlLinkFrame}.
+  #
+  # Finally, there are some specialized frame types and their
+  # corresponding classes:
+  #
+  # * `APIC`: {AttachedPictureFrame}
+  # * `COMM`: {CommentsFrame}
+  # * `GEOB`: {GeneralEncapsulatedObjectFrame}
+  # * `POPM`: {PopularimeterFrame}
+  # * `PRIV`: {PrivateFrame}
+  # * `RVAD`: {RelativeVolumeFrame}
+  # * `TXXX`: {UserTextIdentificationFrame}
+  # * `UFID`: {UniqueFileIdentifierFrame}
+  # * `USLT`: {UnsynchronizedLyricsFrame}
+  # * `WXXX`: {UserUrlLinkFrame}
+  #
+  class Frame
+    # @return [String] frame ID
+    attr_reader :frame_id
+
+    # @return [String] a subclass-specific string representation
+    def to_string
+    end
+  end
+
+  # Attached picture frame (`APIC`), e.g. for cover art.
+  #
+  # The constants in this class are used for the {#type} attribute.
+  class AttachedPictureFrame < Frame
+    # Other
+    Other              = 0x00
+    # 32x32 file icon (PNG only)
+    FileIcon           = 0x01
+    OtherFileIcon      = 0x02
+    FrontCover         = 0x03
+    BackCover          = 0x04
+    LeafletPage        = 0x05
+    Media              = 0x06
+    LeadArtist         = 0x07
+    Artist             = 0x08
+    Conductor          = 0x09
+    Band               = 0x0A
+    Composer           = 0x0B
+    Lyricist           = 0x0C
+    RecordingLocation  = 0x0D
+    DuringRecording    = 0x0E
+    DuringPerformance  = 0x0F
+    MovieScreenCapture = 0x10
+    ColouredFish       = 0x11
+    Illustration       = 0x12
+    BandLogo           = 0x13
+    PublisherLogo      = 0x14
+
+    def initialize()
+    end
+
+    # @return [String]
+    attr_accessor :description
+
+    # MIME type (e.g. `"image/png"`)
+    # @return [String]
+    attr_accessor :mime_type
+
+    # {include:GeneralEncapsulatedObjectFrame#object}
+    #
+    # @return [binary String]
+    attr_accessor :picture
+
+    # {include:TextIdentificationFrame#text_encoding}
+    #
+    # @return [TagLib::String constant]
+    attr_accessor :text_encoding
+
+    # Type of the attached picture, see constants.
+    # @return [AttachedPictureFrame constant]
+    attr_accessor :type
+  end
+
+  # Comments frame (`COMM`) for full text information that doesn't fit in
+  # any other frame.
+  class CommentsFrame < Frame
+    # @return [String] content description, which together with language
+    #   should be unique per tag
+    attr_accessor :description
+
+    # @return [String] alpha-3 language code of text (ISO-639-2),
+    #   e.g. "eng"
+    attr_accessor :language
+
+    # @return [String] the actual comment text
+    attr_accessor :text
+
+    # {include:TextIdentificationFrame#text_encoding}
+    #
+    # @return [TagLib::String constant]
+    attr_accessor :text_encoding
+  end
+
+  # General encapsulated object frame (`GEOB`).
+  class GeneralEncapsulatedObjectFrame < Frame
+    # @return [String] content description
+    attr_accessor :description
+
+    # @return [String] file name
+    attr_accessor :file_name
+
+    # @return [String] MIME type
+    attr_accessor :mime_type
+
+    # Binary data string.
+    #
+    # Be sure to use a binary string when setting this attribute. In
+    # Ruby 1.9, this means reading from a file with `"b"` mode to get a
+    # string with encoding `BINARY` / `ASCII-8BIT`.
+    #
+    # @return [binary String]
+    attr_accessor :object
+
+    # {include:TextIdentificationFrame#text_encoding}
+    #
+    # @return [String]
+    attr_accessor :text_encoding
+  end
+
+  # Popularimeter frame (`POPM`).
+  class PopularimeterFrame < Frame
+    # @return [Integer] play counter
+    attr_accessor :counter
+
+    # @return [String] e-mail address
+    attr_accessor :email
+
+    # @return [Integer] rating
+    attr_accessor :rating
+  end
+
+  # Private frame (`PRIV`).
+  class PrivateFrame < Frame
+    # {include:GeneralEncapsulatedObjectFrame#object}
+    #
+    # @return [binary String]
+    attr_accessor :data
+
+    # @return [String] owner identifier
+    attr_accessor :owner
+  end
+
+  # Relative volume adjustment frame (`RVAD` or `RVA2`).
+  class RelativeVolumeFrame < Frame
+    Other        = 0x00
+    MasterVolume = 0x01
+    FrontRight   = 0x02
+    FrontLeft    = 0x03
+    BackRight    = 0x04
+    BackLeft     = 0x05
+    FrontCentre  = 0x06
+    BackCentre   = 0x07
+    Subwoofer    = 0x08
+
+    # @return [Array<TagLib::ID3v2::RelativeVolumeFrame constant>]
+    #   the channel types for which volume adjustment information is
+    #   stored in this frame
+    def channels
+    end
+
+    # @return [String] relative volume identification
+    attr_accessor :identification
+
+    # Returns peak volume for channel type.
+    #
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [TagLib::ID3v2::PeakVolume]
+    def peak_volume(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+
+    # Sets peak volume for channel type.
+    #
+    # @param [TagLib::ID3v2::PeakVolume] peak peak volume
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [void]
+    def set_peak_volume(peak, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+
+    # Returns volume adjustment in decibels for a specific channel type.
+    # Internally, this is stored as an index, see
+    # {#volume_adjustment_index}.
+    #
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [Float]
+    def volume_adjustment(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+
+    # Sets volume adjustment in decibels for a specific channel type.
+    # Internally, this is stored as an index, see
+    # {#set_volume_adjustment_index}.
+    #
+    # @param [Float] adjustment
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [void]
+    def set_volume_adjustment(adjustment, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+
+    # Returns volume adjustment index for a specific channel type. When
+    # dividing the index by 512, it corresponds to the volume adjustment
+    # in decibel.
+    #
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [Integer]
+    def volume_adjustment_index(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+
+    # Sets volume adjustment index for a specific channel type. When
+    # dividing the index by 512, it corresponds to the volume adjustment
+    # in decibel.
+    #
+    # @param [Integer] index
+    # @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
+    # @return [void]
+    def set_volume_adjustment_index(index, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
+    end
+  end
+
+  # Peak volume used for {RelativeVolumeFrame}. The two attributes of
+  # this class must always read/written together, as they are used to
+  # describe one concept, the peak volume number.
+  #
+  # Note that due to how SWIG works, this is not a nested class of
+  # RelativeVolumeFrame as in taglib. That doesn't affect its usage
+  # though.
+  class PeakVolume
+    # @return [Integer] the number of bits of the {#peak_volume} that
+    #   represent the peak volume (0 to 255)
+    attr_accessor :bits_representing_peak
+
+    # @return [binary String] the (byte-padded) bits used for the peak
+    #   volume
+    attr_accessor :peak_volume
+  end
+
+  # Text identification frame (`T???`).
+  class TextIdentificationFrame < Frame
+    # Encoding for storing the text in the tag, e.g.
+    # `TagLib::String::UTF8`. See the section _String Encodings_ in
+    # {TagLib}.
+    #
+    # @return [TagLib::String constant]
+    attr_accessor :text_encoding
+
+    # @return [Array<String>] list of text strings in this frame
+    attr_accessor :field_list
+
+    # @param [String] text simple text to set
+    attr_writer :text
+  end
+
+  # User text identification frame (`TXXX`).
+  class UserTextIdentificationFrame < TextIdentificationFrame
+    # @return [String] description of content
+    attr_accessor :description
+  end
+
+  # Unique file identifier frame (`UFID`).
+  class UniqueFileIdentifierFrame < Frame
+    # @return [String] identifier
+    attr_accessor :identifier
+
+    # @return [String] owner
+    attr_accessor :owner
+  end
+
+  # Unsynchronized lyrics frame (`USLT`).
+  class UnsynchronizedLyricsFrame < Frame
+    # @return [String] frame description
+    attr_accessor :description
+
+    # @return [String] alpha-3 language code of text (ISO-639-2),
+    #   e.g. "eng"
+    attr_accessor :language
+
+    # @return [String] text
+    attr_accessor :text
+
+    # {include:TextIdentificationFrame#text_encoding}
+    #
+    # @return [String]
+    attr_accessor :text_encoding
+  end
+
+  # URL link frame (`W???`), e.g. `WOAR` for "official artist/performer
+  # webpage".
+  class UrlLinkFrame < Frame
+    # @param [String] text simple text to set
+    attr_writer :text
+
+    # @param [String] URL
+    attr_accessor :url
+  end
+
+  # User URL link frame (`WXXX`).
+  class UserUrlLinkFrame < UrlLinkFrame
+    # @return [String] description
+    attr_accessor :description
+
+    # {include:TextIdentificationFrame#text_encoding}
+    #
+    # @return [String]
+    attr_accessor :text_encoding
+  end
+end