taglib-ruby 0.6.0 → 1.1.0

data/docs/taglib/id3v1.rb

@@ -1,5 +1,34 @@
 module TagLib::ID3v1
   # An ID3v1 tag.
   class Tag < TagLib::Tag
+    # @return [Integer] the genre as a number
+    # @return [255] if not present
+    #
+    # @since 1.0.0
+    attr_accessor :genre_number
+  end
+
+  # @return [Array<String>] the ID3v1 genre list.
+  #
+  # @since 1.0.0
+  def genre_list
+  end
+
+  # @return [Map<String, int>] the map associating a genre to its index.
+  #
+  # @since 1.0.0
+  def genre_map
+  end
+
+  # @return [String] the name of genre at `index` in the ID3v1 genre list.
+  #
+  # @since 1.0.0
+  def genre(index)
+  end
+
+  # @return [String] the genre index for the (case sensitive) genre `name`.
+  #
+  # @since 1.0.0
+  def genre_index(name)
   end
 end

data/docs/taglib/id3v2.rb

@@ -62,8 +62,13 @@ module TagLib::ID3v2
   #     file.save
   #   end
   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.
+    # Get a list of frames.
+    #
+    # Note that the frames returned are subclasses of {TagLib::ID3v2::Frame},
+    # depending on the frame ID. But it's also possible that a
+    # {TagLib::ID3v2::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.
     #
     # @overload frame_list()
     #   Returns all frames.
@@ -405,7 +410,16 @@ module TagLib::ID3v2
   end
 
   # Text identification frame (`T???`).
+  #
+  # @example Create a new TIT2 frame
+  #   frame = TagLib::ID3v2::TextIdentificationFrame.new("TIT2", TagLib::String::UTF8)
+  #   frame.text = "Title"
   class TextIdentificationFrame < Frame
+    # @param [String] type the frame ID, e.g. `TDRC`
+    # @param [TagLib::String constant] encoding text encoding, e.g. `TagLib::String::UTF8`
+    def initialize(type, encoding)
+    end
+
     # Encoding for storing the text in the tag, e.g.
     # `TagLib::String::UTF8`. See the section _String Encodings_ in
     # {TagLib}.
@@ -435,6 +449,11 @@ module TagLib::ID3v2
     attr_accessor :owner
   end
 
+  # Unknown frame used by TagLib to represent a frame whose type is not
+  # known, not implemented or deprecated in later versions of ID3v2.
+  class UnknownFrame < Frame
+  end
+
   # Unsynchronized lyrics frame (`USLT`).
   class UnsynchronizedLyricsFrame < Frame
     # @return [String] frame description
@@ -459,7 +478,7 @@ module TagLib::ID3v2
     # @param [String] value simple text to set
     attr_writer :text
 
-    # @param [String] value URL
+    # @return [String] the URL
     attr_accessor :url
   end
 

data/docs/taglib/mp4.rb

@@ -54,7 +54,7 @@ module TagLib::MP4
   #   #   #<TagLib::MP4::Item:0x007f9bab61d818 @__swigtype__="_p_TagLib__MP4__Item">]]
   class File < TagLib::File
 
-    # {include:TagLib::FileRef.open}
+    # {include:::TagLib::FileRef.open}
     #
     # @param (see #initialize)
     # @yield [file] the {File} object, as obtained by {#initialize}
@@ -82,12 +82,48 @@ module TagLib::MP4
     # @return [TagLib::MP4::Properties]
     def audio_properties
     end
+
+    # @return [Boolean] Returns whether or not the file actually has an MP4 tag, or the
+    # file has a Metadata Item List (ilst) atom.
+    #
+    # @since 1.0.0
+    def mp4_tag?
+    end
   end
 
   class Tag < TagLib::Tag
-    # Returns the map containing all the items in the tag
-    # @return [TagLib::MP4::ItemListMap]
-    def item_list_map
+    # @return [TagLib::MP4::ItemMap] The map containing all the items in the tag.
+    #
+    # @since 1.0.0
+    def item_map
+    end
+
+    # @return [TagLib::MP4::Item] The Item associated to `key` (will be invalid in `key` does not exists).
+    #
+    # @since 1.0.0
+    def [](key)
+    end
+
+    # Associate the `value` Item to `key`, overwriting any previous value.
+    # @param key [String]
+    # @param value [TagLib::MP4::Item]
+    # @return [nil]
+    #
+    # @since 1.0.0
+    def []=(key, value)
+    end
+
+    # Remove the [TagLib::MP4::Item] associated to `key`.
+    # @return [nil]
+    #
+    # @since 1.0.0
+    def remove_item(key)
+    end
+
+    # @return True if the tag has an entry for `key`, false otherwise.
+    #
+    # @since 1.0.0
+    def contains(key)
     end
   end
 
@@ -109,11 +145,32 @@ module TagLib::MP4
     def self.from_bool(value)
     end
 
+    # @param [Fixnum] value
+    # @return [TagLib::MP4::Item]
+    #
+    # @since 1.0.0
+    def self.from_byte(value)
+    end
+
+    # @param [Boolean] value
+    # @return [TagLib::MP4::Item]
+    #
+    # @since 1.0.0
+    def self.from_uint(value)
+    end
+
     # @param [Fixnum] number
     # @return [TagLib::MP4::Item]
     def self.from_int(number)
     end
 
+    # @param [Fixnum] number
+    # @return [TagLib::MP4::Item]
+    #
+    # @since 1.0.0
+    def self.from_long_long(number)
+    end
+
     # @example
     #   TagLib::MP4::Item.from_int_pair([4, 11])
     # @param [Array<Fixnum, Fixnum>] integer_pair
@@ -126,18 +183,43 @@ module TagLib::MP4
     def self.from_string_list(string_array)
     end
 
+    # @param [TagLib::ByteVectorList] list
+    # @return [TagLib::MP4::Item]
+    #
+    # @since 1.0.0
+    def self.from_byte_vector_list(list)
+    end
+
     # @return [Boolean]
     def to_bool
     end
 
-    # @return [Array<TagLib::MP4::CoverArt>]
-    def to_cover_art_list
+    # @return [Fixnum]
+    #
+    # @since 1.0.0
+    def to_byte
+    end
+
+    # @return [Fixnum]
+    #
+    # @since 1.0.0
+    def to_uint
     end
 
     # @return [Fixnum]
     def to_int
     end
 
+    # @return [Fixnum]
+    #
+    # @since 1.0.0
+    def to_long_long
+    end
+
+    # @return [Array<TagLib::MP4::CoverArt>]
+    def to_cover_art_list
+    end
+
     # @return [Array<Fixnum, Fixnum>]
     def to_int_pair
     end
@@ -146,19 +228,25 @@ module TagLib::MP4
     def to_string_list
     end
 
+    # @return [TagLib::ByteVectorList]
+    #
+    # @since 1.0.0
+    def to_byte_vector_list
+    end
+
     # @return [Boolean]
     def valid?
     end
   end
 
-  # The underlying C++-structure of `ItemListMap` inherits from `std::map`.
-  # Consequently, `ItemListMap` behaves differently from a Ruby hash in a few
-  # places: the C++ memory management strategies of ItemListMap can lead to
+  # The underlying C++-structure of `ItemMap` inherits from `std::map`.
+  # Consequently, `ItemMap` behaves differently from a Ruby hash in a few
+  # places: the C++ memory management strategies of ItemMap can lead to
   # a situation where a Ruby object refers to a location in memory that was
   # freed by C++. To prevent Ruby from crashing on us with a segmentation
   # fault, we raise an `ObjectPreviouslyDeleted` exception when we try to access
   # data that is no longer available.
-  class ItemListMap
+  class ItemMap
     # Return the Item under `key`, or `nil` if no Item is present.
     # @param [String] key
     # @return [TagLib::MP4::Item]
@@ -235,10 +323,30 @@ module TagLib::MP4
     # @return [Array<Array<String, TagLib::MP4::Item>>]
     def to_a
     end
+
+    # Convert self into an hash.
+    # @return [Hash<String, TagLib::MP4::Item>]
+    #
+    # @since 1.0.0
+    def to_h
+    end
   end
   #
   class Properties < TagLib::AudioProperties
-    attr_reader :bits_per_sample, :encrypted?
+    Unknown = 0
+    AAC     = 1
+    ALAC    = 2
+
+    # @return [Integer] The number of bits per audio sample.
+    attr_reader :bits_per_sample
+
+    # @return [Boolean] Whether or not the file is encrypted.
+    attr_reader :encrypted?
+
+    # @return [Integer] The codec used in the file.
+    #
+    # @since 1.0.0
+    attr_reader :codec
   end
 
   # The `CoverArt` class is used to embed cover art images in MP4 tags.
@@ -247,8 +355,11 @@ module TagLib::MP4
   #   image_data = File.open('cover_art.jpeg', 'rb') { |f| f.read }
   #   cover_art = TagLib::MP4::CoverArt.new(TagLib::MP4::CoverArt::JPEG, image_data)
   class CoverArt
-    JPEG = 0x0D
-    PNG  = 0x0E
+    Unknown = 0x00
+    JPEG    = 0x0D
+    PNG     = 0x0E
+    BMP     = 0x1B
+    GIF     = 0x0C # Deprecated
 
     # Returns the format of the image data: `JPEG` or `PNG`.
     # @return [Fixnum]

data/docs/taglib/mpeg.rb

@@ -14,7 +14,7 @@ module TagLib::MPEG
     APE     = 0x0004
     AllTags = 0xffff
 
-    # {include:TagLib::FileRef.open}
+    # {include:::TagLib::FileRef.open}
     #
     # @param (see #initialize)
     # @yield [file] the {File} object, as obtained by {#initialize}
@@ -103,6 +103,24 @@ module TagLib::MPEG
     # @return [Boolean] whether stripping was successful
     def strip(tags=TagLib::MPEG::File::AllTags)
     end
+
+    # @return [Boolean] Whether or not the file on disk actually has an ID3v1 tag.
+    #
+    # @since 1.0.0
+    def id3v1_tag?
+    end
+
+    # @return [Boolean] Whether or not the file on disk actually has an ID3v2 tag.
+    #
+    # @since 1.0.0
+    def id3v2_tag?
+    end
+
+    # @return [Boolean] Whether or not the file on disk actually has an APE tag.
+    #
+    # @since 1.0.0
+    def ape_tag?
+    end
   end
 
   # Audio properties for MPEG files.
@@ -153,6 +171,11 @@ module TagLib::MPEG
 
   # Xing VBR header.
   class XingHeader
+
+    Invalid = 0
+    Xing    = 1
+    VBRI    = 2
+
     # @return [true] if a valid Xing header is present
     def valid?
     end
@@ -164,5 +187,11 @@ module TagLib::MPEG
     # @return [Integer] total size of stream in bytes
     def total_size
     end
+
+    # @return [Integer] the type of the VBR header.
+    #
+    # @since 1.0.0
+    def type
+    end
   end
 end

data/docs/taglib/ogg.rb

@@ -29,10 +29,9 @@ module TagLib::Ogg
     def contains?(name)
     end
 
-    # Count the number of fields.
+    # Count the number of fields (including the pictures).
     #
-    # @return [Integer] the number of fields in the comment (name-value
-    #   pairs)
+    # @return [Integer] the number of fields in the comment (name-value pairs)
     def field_count
     end
 
@@ -44,7 +43,7 @@ module TagLib::Ogg
     #       'GENRE' => ["Rock", "Pop"] }
     #
     # Note that the returned hash is read-only. Changing it will have no
-    # effect on the comment; use {#add_field} and {#remove_field} for
+    # effect on the comment; use {#add_field} and {#remove_fields} for
     # that.
     #
     # @return [Hash<String, Array<String>>] a hash from field names to
@@ -66,7 +65,50 @@ module TagLib::Ogg
     #   @param [String] value field value
     #
     # @return [void]
-    def remove_field
+    #
+    # @since 1.0.0
+    def remove_fields
+    end
+
+    # Remove all the fields.
+    #
+    # @since 1.0.0
+    def remove_all_fields
+    end
+
+    # @return [Boolean] True if the specified string is a valid Xiph comment key.
+    #
+    # @since 1.0.0
+    def self.check_key(key)
+    end
+
+    # @return [Array<TagLib::FLAC::Picture>] The list of the pictures associated to this comment.
+    #
+    # @since 1.0.0
+    def picture_list
+    end
+
+    # Add a picture.
+    # @param [TagLib::FLAC::Picture] picture
+    # @return [void]
+    #
+    # @since 1.0.0
+    def add_picture(picture)
+    end
+
+    # Remove a picture.
+    # @param [TagLib::FLAC::Picture] picture
+    # @return [void]
+    #
+    # @since 1.0.0
+    def remove_picture(picture)
+    end
+
+    # Remove all the pictures.
+    # @return [void]
+    #
+    # @since 1.0.0
+    def remove_all_pictures
     end
 
     # @return [String] vendor ID of the encoder used

data/docs/taglib/riff.rb

@@ -0,0 +1,3 @@
+# @since 0.7.0
+module TagLib::RIFF
+end

data/docs/taglib/vorbis.rb

@@ -11,7 +11,7 @@ module TagLib::Ogg::Vorbis
   #   end
   #
   class File < TagLib::Ogg::File
-    # {include:TagLib::FileRef.open}
+    # {include:::TagLib::FileRef.open}
     #
     # @param (see #initialize)
     # @yield [file] the {File} object, as obtained by {#initialize}

data/docs/taglib/wav.rb

@@ -0,0 +1,116 @@
+# @since 0.7.0
+module TagLib::RIFF::WAV
+
+  FORMAT_UNKNOWN = 0x0000 # @since 1.0.0
+  FORMAT_PCM     = 0x0001 # @since 1.0.0
+
+  # The file class for `.wav` files.
+  #
+  # @example Reading the title
+  #   title = TagLib::RIFF::WAV::File.open("sample.wav") do |file|
+  #     file.tag.title
+  #   end
+  #
+  # @example Reading WAV-specific audio properties
+  #   TagLib::RIFF::WAV::File.open("sample.wav") do |file|
+  #     file.audio_properties.sample_width  #=>  16
+  #   end
+  #
+  # @example Saving ID3v2 cover-art to disk
+  #   TagLib::RIFF::WAV::File.open("sample.wav") do |file|
+  #     id3v2_tag = file.tag
+  #     cover = id3v2_tag.frame_list('APIC').first
+  #     ext = cover.mime_type.rpartition('/')[2]
+  #     File.open("cover-art.#{ext}", "wb") { |f| f.write cover.picture }
+  #   end
+  #
+  # @see ID3v2::Tag ID3v2 examples.
+  #
+  class File < TagLib::File
+
+    NoTags  = 0x0000
+    ID3v1   = 0x0001
+    ID3v2   = 0x0002
+    APE     = 0x0004
+    AllTags = 0xffff
+
+    # {include:::TagLib::FileRef.open}
+    #
+    # @param (see #initialize)
+    # @yield [file] the {File} object, as obtained by {#initialize}
+    # @return the return value of the block
+    #
+    def self.open(filename, read_properties=true)
+    end
+
+    # Load a WAV file.
+    #
+    # @param [String] filename
+    # @param [Boolean] read_properties if audio properties should be
+    #                  read
+    def initialize(filename, read_properties=true)
+    end
+
+    # Returns the ID3v2 tag.
+    #
+    # @return [TagLib::ID3v2::Tag]
+    def tag
+    end
+
+    # Returns the ID3v2 tag.
+    #
+    # @return [TagLib::ID3v2::Tag]
+    #
+    # @since 1.0.0
+    def id3v2_tag
+    end
+
+    # Returns audio properties.
+    #
+    # @return [TagLib::RIFF::WAV::Properties]
+    def audio_properties
+    end
+
+    # Remove the tags matching the specified OR-ed types.
+    #
+    # @param [int] tags The types of tags to remove.
+    # @return [void]
+    #
+    # @since 1.0.0
+    def strip(tags=TagLib::RIFF::WAV::File::AllTags)
+    end
+
+  end
+
+  class Properties < TagLib::AudioProperties
+    # @return [Integer] Number of bits per audio sample.
+    #
+    # @since 1.0.0
+    attr_reader :bits_per_sample
+
+    # @return [Integer] Number of sample frames.
+    #
+    # @since 1.0.0
+    attr_reader :sample_frames
+
+    # @return [Integer] length of the file in seconds
+    #
+    # @since 1.0.0
+    attr_reader :length_in_seconds
+
+    # @return [Integer] length of the file in milliseconds
+    #
+    # @since 1.0.0
+    attr_reader :length_in_milliseconds
+
+    # @return [Integer] The format ID of the file.
+    #
+    # 0 for unknown, 1 for PCM, 2 for ADPCM, 3 for 32/64-bit IEEE754, and
+    # so forth. For further information, refer to the WAVE Form
+    # Registration Numbers in RFC 2361.
+    #
+    # @since 1.0.0
+    attr_reader :format
+  end
+
+end