taglib-ruby 0.5.2 → 0.6.0

data/.yardopts

@@ -1,5 +1,5 @@
 --markup markdown
---markup-provider redcarpet
+--markup-provider kramdown
 --charset UTF-8
 --template-path docs
 docs/**/*.rb

data/CHANGES.md

@@ -1,6 +1,17 @@
 Changes in Releases of taglib-ruby
 ==================================
 
+## 0.6.0 (2013-04-26)
+
+* Add support for TagLib::MP4 (#3, by @jacobvosmaer)
+* Add support for TagLib::ID3v2::Header (#19, by @kaethorn)
+* Support saving ID3v2.3 with TagLib::MPEG::File#save (#17)
+  *  Note that this requires at least TagLib 1.8, and due to 1.8.0
+     having an incorrect version number in the headers, it currently
+     requires master. See issue #17 for details.
+* Fix segfault when passing a non-String to a String argument
+* Documentation updates
+
 ## 0.5.2 (2012-10-06)
 
 * Fix memory bug with TagLib::MPEG::File#tag and TagLib::FLAC::File#tag

data/LICENSE.txt

@@ -1,5 +1,3 @@
-Copyright (c) 2010-2012 Robin Stocker
-
 MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining

data/README.md

@@ -8,16 +8,15 @@ In contrast to other libraries, this one wraps the full C++ API, not
 only the minimal C API. This means that all tag data can be accessed,
 e.g. cover art of ID3v2 or custom fields of Ogg Vorbis comments.
 
-taglib-ruby is work in progress, but the following is already available:
+taglib-ruby currently supports the following:
 
 * Reading/writing common tag data of all formats that TagLib supports
 * Reading/writing ID3v1 and ID3v2 including ID3v2.4 and Unicode
 * Reading/writing Ogg Vorbis comments
+* Reading/writing MP4 tags (.m4a)
 * Reading audio properties (e.g. bitrate) of the above formats
 
-Some things are still left to do (contributors very welcome):
-
-* More coverage of the library
+Contributions for more coverage of the library are very welcome.
 
 [![Build status][travis-img]][travis-link]
 
@@ -41,9 +40,8 @@ Then do:
 Usage
 -----
 
-Complete API documentation can be found here:
-
-http://rubydoc.info/gems/taglib-ruby/frames
+Complete API documentation can be found on
+[rubydoc.info](http://rubydoc.info/gems/taglib-ruby/frames).
 
 Begin with the {TagLib} namespace.
 
@@ -87,7 +85,7 @@ Contributing
 License
 -------
 
-Copyright (c) 2010-2012 Robin Stocker.
+Copyright (c) 2010-2013 Robin Stocker and others, see Git history.
 
 taglib-ruby is distributed under the MIT License,
 see LICENSE.txt for details.
@@ -96,7 +94,7 @@ In the binary gem for Windows, a compiled [TagLib][taglib] is bundled as
 a DLL. TagLib is distributed under the GNU Lesser General Public License
 version 2.1 (LGPL) and Mozilla Public License (MPL).
 
-[taglib]: http://developer.kde.org/~wheeler/taglib.html
+[taglib]: http://taglib.github.io/
 [travis-img]: https://secure.travis-ci.org/robinst/taglib-ruby.png
 [travis-link]: http://travis-ci.org/robinst/taglib-ruby
 [flattr-img]: http://api.flattr.com/button/flattr-badge-large.png

data/docs/taglib/base.rb

@@ -25,6 +25,21 @@
 # using the {TagLib::ID3v2::FrameFactory}.
 module TagLib
 
+  # Major version of TagLib the extensions were compiled against
+  # (major.minor.patch). Note that the value is not actually 0, but
+  # depends on the version of the installed library.
+  TAGLIB_MAJOR_VERSION = 0
+
+  # Minor version of TagLib the extensions were compiled against
+  # (major.minor.patch). Note that the value is not actually 0, but
+  # depends on the version of the installed library.
+  TAGLIB_MINOR_VERSION = 0
+
+  # Patch version of TagLib the extensions were compiled against
+  # (major.minor.patch). Note that the value is not actually 0, but
+  # depends on the version of the installed library.
+  TAGLIB_PATCH_VERSION = 0
+
   # 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
@@ -35,16 +50,20 @@ module TagLib
   #
   # @example Reading tags
   #   TagLib::FileRef.open("foo.flac") do |file|
-  #     tag = file.tag
-  #     puts tag.artist
-  #     puts tag.title
+  #     unless file.null?
+  #       tag = file.tag
+  #       puts tag.artist
+  #       puts tag.title
+  #     end
   #   end
   #
   # @example Reading audio properties
   #   TagLib::FileRef.open("bar.oga") do |file|
-  #     prop = file.audio_properties
-  #     puts prop.length
-  #     puts prop.bitrate
+  #     unless file.null?
+  #       prop = file.audio_properties
+  #       puts prop.length
+  #       puts prop.bitrate
+  #     end
   #   end
   #
   class FileRef
@@ -86,6 +105,11 @@ module TagLib
                    audio_properties_style=TagLib::AudioProperties::Average)
     end
 
+    # Gets the audio properties. Before accessing it, check if there
+    # were problems reading the file using {#null?}. If the audio
+    # properties are accessed anyway, a warning will be printed and it
+    # will return nil.
+    #
     # @return [TagLib::AudioProperties] the audio properties
     def audio_properties
     end
@@ -100,7 +124,11 @@ module TagLib
     def save
     end
 
-    # @return [TagLib::Tag] the tag
+    # Gets the tag. Before accessing it, check if there were problems
+    # reading the file using {#null?}. If the tag is accessed anyway, a
+    # warning will be printed and it will return nil.
+    #
+    # @return [TagLib::Tag] the tag, or nil
     def tag
     end
 

data/docs/taglib/id3v2.rb

@@ -21,7 +21,7 @@ module TagLib::ID3v2
   #     title.text_encoding = TagLib::String::UTF8
   #
   # @example Read ID3v2 frames from a file
-  #   TagLib::MPEG::File.new("wake_up.mp3") do |file|
+  #   TagLib::MPEG::File.open("wake_up.mp3") do |file|
   #     tag = file.id3v2_tag
   #
   #     # Read basic attributes
@@ -43,7 +43,7 @@ module TagLib::ID3v2
   #   end
   #
   # @example Add frames and save file
-  #   TagLib::MPEG::File.new("joga.mp3") do |file|
+  #   TagLib::MPEG::File.open("joga.mp3") do |file|
   #     tag = file.id3v2_tag
   #
   #     # Write basic attributes
@@ -108,6 +108,38 @@ module TagLib::ID3v2
     end
   end
 
+  # Exposes properties defined in a standard ID3v2 header.
+  class Header
+    # The major version number (4 for a ID3v2.4.0 version tag).
+    # @return [Integer] major version number
+    attr_accessor :major_version
+
+    # The size of the tag without the size of the header.
+    # @return [Integer] size in bytes
+    attr_accessor :tag_size
+
+    # The revision version number (0 for a ID3v2.4.0 version tag).
+    # @return [Integer] revision version number
+    attr_reader :revision_number
+
+    # @return [Boolean] if unsynchronisation has been applied to all frames
+    attr_reader :unsynchronisation
+
+    # @return [Boolean] if an extended header is present in the tag
+    attr_reader :extended_header
+
+    # @return [Boolean] if the experimental indicator flag is set
+    attr_reader :experimental_indicator
+
+    # @return [Boolean] if a footer is present in the tag
+    attr_reader :footer_present
+
+    # Renders the header to binary.
+    # @return [TagLib::ByteVector]
+    def render
+    end
+  end
+
   # Frame factory for ID3v2 frames. Useful for setting the default text
   # encoding.
   class FrameFactory
@@ -384,7 +416,7 @@ module TagLib::ID3v2
     # @return [Array<String>] list of text strings in this frame
     attr_accessor :field_list
 
-    # @param [String] text simple text to set
+    # @param [String] value simple text to set
     attr_writer :text
   end
 
@@ -424,10 +456,10 @@ module TagLib::ID3v2
   # URL link frame (`W???`), e.g. `WOAR` for "official artist/performer
   # webpage".
   class UrlLinkFrame < Frame
-    # @param [String] text simple text to set
+    # @param [String] value simple text to set
     attr_writer :text
 
-    # @param [String] URL
+    # @param [String] value URL
     attr_accessor :url
   end
 

data/docs/taglib/mp4.rb

@@ -0,0 +1,267 @@
+module TagLib::MP4
+
+  # The file class for '.m4a' files.
+  #
+  # @example Finding an MP4 item by field name
+  #   TagLib::MP4::File.open("file.m4a") do |mp4|
+  #     item_list_map = mp4.tag.item_list_map
+  #     title = item_list_map["\xC2\xA9nam"].to_string_list
+  #     puts title.first
+  #   end
+  #
+  # @example Add new cover art to a tag
+  #   image_data = File.open('cover_art.jpeg', 'rb') { |f| f.read }
+  #   cover_art = TagLib::MP4::CoverArt.new(TagLib::MP4::CoverArt::JPEG, image_data)
+  #   item = TagLib::MP4::Item.from_cover_art_list([cover_art])
+  #   mp4.tag.item_list_map.insert('covr', item)
+  #   # => nil
+  #   mp4.save
+  #   # => true
+  #
+  # @example Extract cover art from a tag and save it to disk
+  #   cover_art_list = mp4.tag.item_list_map['covr'].to_cover_art_list
+  #   cover_art = cover_art_list.first
+  #   cover_art.format
+  #   # => 13
+  #   cover_art.format == TagLib::MP4::CoverArt::JPEG
+  #   # => true
+  #   File.open('cover_art.jpeg', 'wb') do |file|
+  #     file.write(cover_art.data)
+  #   end
+  #   # => 3108
+  #
+  # @example List all keys and items in the tag
+  #   mp4.tag.item_list_map.to_a
+  #   # => [["covr",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61e3d0 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["trkn",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61e268 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©ART",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61e128 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©alb",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61df48 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©cmt",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61de08 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©cpy",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61dc78 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©day",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61db88 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©gen",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61da48 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©nam",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61d930 @__swigtype__="_p_TagLib__MP4__Item">],
+  #   #  ["©too",
+  #   #   #<TagLib::MP4::Item:0x007f9bab61d818 @__swigtype__="_p_TagLib__MP4__Item">]]
+  class File < TagLib::File
+
+    # {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 an M4A file.
+    #
+    # @param [String] filename
+    # @param [Boolean] read_properties if audio properties should be
+    #                  read
+    # @return [TagLib::MP4::File]
+    def initialize(filename, read_properties=true)
+    end
+
+    # Returns the MP4 tag in the file
+    #
+    # @return [TagLib::MP4::Tag]
+    # @return [nil] if not present
+    def tag
+    end
+
+    # @return [TagLib::MP4::Properties]
+    def audio_properties
+    end
+  end
+
+  class Tag < TagLib::Tag
+    # Returns the map containing all the items in the tag
+    # @return [TagLib::MP4::ItemListMap]
+    def item_list_map
+    end
+  end
+
+  # TagLib's `MP4::Item` class is a C++ union. To create a new Item with a value
+  # of the right type, use one of the `Item.from_<type>`-constructors. The use
+  # of `Item.new` is discouraged. For more information, see [the TagLib
+  # documentation of `Item`](http://taglib.github.com/api/classTagLib_1_1MP4_1_1Item.html).
+  # @example Using a specific constructor
+  #   item = TagLib::MP4::Item.from_string_list(['hello'])
+  #   # => #<TagLib::MP4::Item:0x007ffd59796d60 @__swigtype__="_p_TagLib__MP4__Item">
+  #   item.to_string_list
+  #   # => ["hello"]
+  #   item.to_int # Good luck!
+  #   # => 1538916358
+  #
+  class Item
+    # @param [Boolean] value
+    # @return [TagLib::MP4::Item]
+    def self.from_bool(value)
+    end
+
+    # @param [Fixnum] number
+    # @return [TagLib::MP4::Item]
+    def self.from_int(number)
+    end
+
+    # @example
+    #   TagLib::MP4::Item.from_int_pair([4, 11])
+    # @param [Array<Fixnum, Fixnum>] integer_pair
+    # @return [TagLib::MP4::Item]
+    def self.from_int_pair(integer_pair)
+    end
+
+    # @param [Array<String>] string_array
+    # @return [TagLib::MP4::Item]
+    def self.from_string_list(string_array)
+    end
+
+    # @return [Boolean]
+    def to_bool
+    end
+
+    # @return [Array<TagLib::MP4::CoverArt>]
+    def to_cover_art_list
+    end
+
+    # @return [Fixnum]
+    def to_int
+    end
+
+    # @return [Array<Fixnum, Fixnum>]
+    def to_int_pair
+    end
+
+    # @return [Array<String>]
+    def to_string_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
+  # 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
+    # Return the Item under `key`, or `nil` if no Item is present.
+    # @param [String] key
+    # @return [TagLib::MP4::Item]
+    # @return [nil] if not present
+    def fetch(key)
+    end
+    alias :[] :fetch
+
+    # @example Triggering an ObjectPreviouslyDeleted exception
+    #   remember_me = mp4.tag.item_list_map["\xC2\xA9nam"]
+    #   mp4.tag.item_list_map.clear
+    #   # => nil
+    #   remember_me.to_string_list
+    #   # ObjectPreviouslyDeleted: Expected argument 0 of type TagLib::MP4::Item const *, but got TagLib::MP4::Item #<TagLib::MP4::Item:0x007f9199...
+    #   # 	in SWIG method 'toStringList'
+    #   # from (pry):7:in `to_string_list'
+    #
+    # Remove all Items from self, destroying each Item.
+    # @note May free memory referred to by Ruby objects
+    # @return [nil]
+    def clear
+    end
+
+    # Returns true if self has an Item under `key`.
+    # @param [String] key
+    # @return [Boolean]
+    def contains(key)
+    end
+    alias :has_key? :contains
+    alias :include? :contains
+
+    # Returns true if self is empty
+    # @return [Boolean]
+    def empty?
+    end
+
+    # Remove and destroy the value under `key`, if present.
+    # @example Triggering an ObjectPreviouslyDeleted exception
+    #   remember_me = mp4.tag.item_list_map["\xC2\xA9nam"]
+    #   mp4.tag.item_list_map.erase("\xC2\xA9nam")
+    #   # => nil
+    #   remember_me.to_string_list
+    #   # ObjectPreviouslyDeleted: Expected argument 0 of type TagLib::MP4::Item const *, but got TagLib::MP4::Item #<TagLib::MP4::Item:0x007f919a...
+    #   # 	in SWIG method 'toStringList'
+    #   # from (pry):13:in `to_string_list'
+    #
+    # @note May free memory referred to by Ruby objects
+    # @param [String] key
+    # @return [nil]
+    def erase(key)
+    end
+
+    # Insert an item at `key`, destoying the existing item under `key`.
+    # @example Triggering an ObjectPreviouslyDeleted exception
+    #   remember_me = mp4.tag.item_list_map["\xC2\xA9nam"]
+    #   mp4.tag.item_list_map.insert("\xC2\xA9nam", TagLib::MP4::Item.from_string_list(['New']))
+    #   remember_me.to_string_list
+    #   # ObjectPreviouslyDeleted: Expected argument 0 of type TagLib::MP4::Item const *, but got TagLib::MP4::Item #<TagLib::MP4::Item:0x007f919a...
+    #   # 	in SWIG method 'toStringList'
+    #   # from (pry):18:in `to_string_list'
+    # @note May free memory referred to by Ruby objects
+    # @param [String] key
+    # @param [TagLib::MP4::Item] item
+    # @return [nil]
+    def insert(key, item)
+    end
+
+    # The number of Items in self.
+    # @return [Fixnum]
+    def size
+    end
+
+    # Convert self into an array of `[key, value]` pairs.
+    # @return [Array<Array<String, TagLib::MP4::Item>>]
+    def to_a
+    end
+  end
+  #
+  class Properties < TagLib::AudioProperties
+    attr_reader :bits_per_sample, :encrypted?
+  end
+
+  # The `CoverArt` class is used to embed cover art images in MP4 tags.
+  #
+  # @example Creating a new CoverArt instance
+  #   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
+
+    # Returns the format of the image data: `JPEG` or `PNG`.
+    # @return [Fixnum]
+    attr_reader :format
+
+    # Returns the raw image data
+    # @return [String]
+   attr_reader :data
+
+    # @param [Fixnum] format
+    # @param [String] data
+    # @return [TagLib::MP4::CoverArt]
+    def initialize(format, data)
+    end
+  end
+end