taglib-ruby 0.2.1 → 0.3.0

data/CHANGES.md

@@ -1,6 +1,13 @@
 Changes in Releases of taglib-ruby
 ==================================
 
+## 0.3.0 (2012-01-02)
+
+* Add support for Ogg Vorbis
+* Add support for ID3v1 (#2)
+* Add #close to File classes for explicitly releasing resources
+* Fix compilation on Windows
+
 ## 0.2.1 (2011-11-05)
 
 * Fix compilation error due to missing typedef on some systems (#5)

data/Gemfile

@@ -6,8 +6,7 @@ group :development do
   gem 'shoulda', '~> 2.11'
   gem 'bundler', '~> 1.0.0'
   gem 'jeweler', '~> 1.6.4'
-  gem 'rcov', '>= 0'
   gem 'yard', '~> 0.7'
-  gem 'redcarpet'
+  gem 'redcarpet', '~> 1.0'
   gem 'guard-test', '~> 0.4.0'
 end

data/Gemfile.lock

@@ -1,35 +1,36 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    ffi (1.0.11)
     git (1.2.5)
-    guard (0.8.4)
+    guard (0.9.3)
+      ffi (>= 0.5.0)
       thor (~> 0.14.6)
-    guard-test (0.4.0)
+    guard-test (0.4.3)
       guard (>= 0.4)
       test-unit (~> 2.2)
     jeweler (1.6.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
       rake
-    rake (0.9.2)
+    rake (0.9.2.2)
     rake-compiler (0.7.9)
       rake
-    rcov (0.9.11)
     redcarpet (1.17.2)
     shoulda (2.11.3)
-    test-unit (2.4.0)
+    test-unit (2.4.3)
     thor (0.14.6)
-    yard (0.7.3)
+    yard (0.7.4)
 
 PLATFORMS
   ruby
+  x86-mingw32
 
 DEPENDENCIES
   bundler (~> 1.0.0)
   guard-test (~> 0.4.0)
   jeweler (~> 1.6.4)
   rake-compiler (~> 0.7)
-  rcov
-  redcarpet
+  redcarpet (~> 1.0)
   shoulda (~> 2.11)
   yard (~> 0.7)

data/README.md

@@ -3,15 +3,24 @@ taglib-ruby
 
 Ruby interface for the [TagLib C++ library][taglib].
 
-In contrast to other libraries, this one wraps the full C++ API using
-SWIG, not only the minimal C API. This means that all tags can be
-accessed.
+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, here are some of the things still left
-to do (contributors very welcome):
+taglib-ruby is work in progress, but the following is already available:
 
-* Pre-compiled Gem for Windows
-* More coverage of the library besides ID3v2
+* 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 audio properties (e.g. bitrate) of the above formats
+
+Some things are still left to do (contributors very welcome):
+
+* Pre-compiled Gem for Windows:
+  * Unicode filename support
+* More coverage of the library
+
+[![flattr this project][flattr-img]][flattr-link]
 
 Installation
 ------------
@@ -61,6 +70,9 @@ track.to_s  #=> "7/10"
 cover = tag.frame_list('APIC').first
 cover.mime_type  #=> "image/jpeg"
 cover.picture  #=> "\xFF\xD8\xFF\xE0\x00\x10JFIF..."
+
+# Close file to release resources
+file.close
 ```
 
 And here's an example for writing one:
@@ -83,6 +95,7 @@ apic.picture = File.open("cover.jpg", 'rb'){ |f| f.read }
 tag.add_frame(apic)
 
 file.save
+file.close
 ```
 
 ### Encoding
@@ -139,3 +152,5 @@ see LICENSE.txt for details.
 Copyright (c) 2010, 2011 Robin Stocker.
 
 [taglib]: http://developer.kde.org/~wheeler/taglib.html
+[flattr-img]: http://api.flattr.com/button/flattr-badge-large.png
+[flattr-link]: https://flattr.com/submit/auto?user_id=robinst&url=https://github.com/robinst/taglib-ruby&title=taglib-ruby&tags=github&category=software

data/Rakefile

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 require 'rubygems'
+require "rubygems/package_task"
 require 'bundler'
 begin
   Bundler.setup(:default, :development)
@@ -13,7 +14,7 @@ require 'rake'
 
 require 'jeweler'
 require './lib/taglib/version.rb'
-Jeweler::Tasks.new do |gem|
+jeweler_tasks = Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "taglib-ruby"
   gem.summary = %Q{Ruby interface for the taglib C++ library}
@@ -31,16 +32,15 @@ not only the minimal C API. This means that all tags can be accessed.
   gem.authors = ["Robin Stocker"]
   gem.extensions = ['ext/taglib_base/extconf.rb',
                     'ext/taglib_mpeg/extconf.rb',
-                    'ext/taglib_id3v2/extconf.rb']
+                    'ext/taglib_id3v1/extconf.rb',
+                    'ext/taglib_id3v2/extconf.rb',
+                    'ext/taglib_ogg/extconf.rb',
+                    'ext/taglib_vorbis/extconf.rb']
+  gem.extra_rdoc_files = ["README.md", "CHANGES.md", "LICENSE.txt"]
   # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new
 
-require 'rake/extensiontask'
-Rake::ExtensionTask.new("taglib_base")
-Rake::ExtensionTask.new("taglib_mpeg")
-Rake::ExtensionTask.new("taglib_id3v2")
-
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
@@ -48,14 +48,6 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
-end
-
 task :default => :test
 
 require 'yard'
@@ -64,4 +56,6 @@ YARD::Rake::YardocTask.new do |t|
   t.options = ['--title', "taglib-ruby #{version}"]
 end
 
+$gemspec = jeweler_tasks.jeweler.gemspec.dup
+
 FileList['tasks/**/*.rake'].each { |task| import task }

data/docs/taglib/base.rb

@@ -7,6 +7,7 @@
 # * Reading properties of MPEG files: {TagLib::MPEG::File}
 # * Reading/writing ID3v2 tags: {TagLib::MPEG::File} and
 #   {TagLib::MPEG::File#id3v2_tag}
+# * Reading/writing Ogg Vorbis tags: {TagLib::Ogg::Vorbis::File}.
 # 
 # ## String Encodings
 #
@@ -60,10 +61,36 @@ module TagLib
     # @return [TagLib::Tag] the tag
     def tag
     end
+
+    # Closes the file and releases all objects that were read from the
+    # file.
+    #
+    # @see TagLib::File#close
+    #
+    # @return [void]
+    def close
+    end
   end
 
   # @abstract Base class for files, see subclasses.
   class File
+    # Closes the file and releases all objects that were read from the
+    # file.
+    #
+    # After this method has been called, no other methods on this object
+    # may be called. So it's a good idea to always use it like this:
+    #
+    #     file.close
+    #     file = nil
+    #
+    # This method should always be called as soon as you're finished
+    # with a file. Otherwise the file will only be closed when GC is
+    # run, which may be much later. On Windows, this is especially
+    # important as the file is locked until it is closed.
+    #
+    # @return [void]
+    def close
+    end
   end
 
   # @abstract Base class for tags.
@@ -112,19 +139,15 @@ module TagLib
     Accurate = 2
 
     # @return [Integer] length of the file in seconds
-    def length
-    end
+    attr_reader :length
 
     # @return [Integer] bit rate in kb/s (kilobit per second)
-    def bitrate
-    end
+    attr_reader :bitrate
 
     # @return [Integer] sample rate in Hz
-    def sample_rate
-    end
+    attr_reader :sample_rate
 
     # @return [Integer] number of channels
-    def channels
-    end
+    attr_reader :channels
   end
 end

data/docs/taglib/id3v1.rb

@@ -0,0 +1,5 @@
+module TagLib::ID3v1
+  # An ID3v1 tag.
+  class Tag < TagLib::Tag
+  end
+end

data/docs/taglib/mpeg.rb

@@ -17,6 +17,14 @@ module TagLib::MPEG
     def tag
     end
 
+    # Returns the ID3v1 tag.
+    #
+    # @param create if a new tag should be created when none exists
+    # @return [TagLib::ID3v1::Tag]
+    # @return [nil] if not present
+    def id3v1_tag(create=false)
+    end
+
     # Returns the ID3v2 tag.
     #
     # @param create if a new tag should be created when none exists

data/docs/taglib/ogg.rb

@@ -0,0 +1,77 @@
+module TagLib::Ogg
+
+  # @abstract Base class for Ogg files, see subclasses.
+  class File < TagLib::File
+  end
+
+  # Xiph comments (aka VorbisComment), a metadata format used for Ogg
+  # Vorbis and other codecs.
+  #
+  # A Xiph comment is structured as a set of fields. Each field has a
+  # name and a value. Multiple fields with the same name are allowed, so
+  # you can also view it as a map from names to a list of values.
+  class XiphComment < TagLib::Tag
+
+    # Add a name-value pair to the comment.
+    #
+    # @param [String] name field name
+    # @param [String] value field value
+    # @param [Boolean] replace if true, all existing fields with the
+    #   given name will be replaced
+    # @return [void]
+    def add_field(name, value, replace=true)
+    end
+
+    # Check if the comment contains a field.
+    #
+    # @param [String] name field name
+    # @return [Boolean]
+    def contains?(name)
+    end
+
+    # Count the number of fields.
+    #
+    # @return [Integer] the number of fields in the comment (name-value
+    #   pairs)
+    def field_count
+    end
+
+    # Get the contents of the comment as a hash, with the key being a
+    # field name String and the value a list of field values for that
+    # key. Example result:
+    #
+    #     { 'TITLE' => ["Title"],
+    #       '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
+    # that.
+    #
+    # @return [Hash<String, Array<String>>] a hash from field names to
+    #   value lists
+    def field_list_map
+    end
+
+    # Remove one or more fields.
+    #
+    # @overload remove_field(name)
+    #   Removes all fields with the given name.
+    #
+    #   @param [String] name field name
+    #
+    # @overload remove_field(name, value)
+    #   Removes the field with the given name and value.
+    #
+    #   @param [String] name field name
+    #   @param [String] value field value
+    #
+    # @return [void]
+    def remove_field
+    end
+
+    # @return [String] vendor ID of the encoder used
+    attr_reader :vendor_id
+
+  end
+
+end

data/docs/taglib/vorbis.rb

@@ -0,0 +1,43 @@
+module TagLib::Ogg::Vorbis
+
+  # The file class for `.ogg` and other `.oga` files.
+  class File < TagLib::Ogg::File
+    # Load an Ogg Vorbis file.
+    #
+    # @param [String] filename
+    # @param [Boolean] read_properties if audio properties should be
+    #                  read
+    def initialize(filename, read_properties=true)
+    end
+
+    # Returns the VorbisComment tag.
+    #
+    # @return [TagLib::Ogg::XiphComment]
+    def tag
+    end
+
+    # Returns audio properties.
+    #
+    # @return [TagLib::Ogg::Vorbis::Properties]
+    def audio_properties
+    end
+  end
+
+  # Ogg Vorbis audio properties.
+  class Properties < TagLib::AudioProperties
+    # @return [Integer] Vorbis version
+    attr_reader :vorbis_version
+
+    # @return [Integer] maximum bitrate from Vorbis identification
+    #   header
+    attr_reader :bitrate_maximum
+
+    # @return [Integer] nominal bitrate from Vorbis identification
+    #   header
+    attr_reader :bitrate_nominal
+
+    # @return [Integer] minimum bitrate from Vorbis identification
+    #   header
+    attr_reader :bitrate_minimum
+  end
+end

data/ext/taglib_base/includes.i

@@ -1,7 +1,8 @@
 %trackobjects;
 
-// Undefine macro
+// Undefine macros we don't need for wrapping
 #define TAGLIB_EXPORT
+#define TAGLIB_IGNORE_MISSING_DESTRUCTOR
 
 // Replaces the typemap from swigtype.swg and just adds the line
 // SWIG_RubyUnlinkObjects. This is done to be safe in the case when a
@@ -15,6 +16,10 @@
 }
 
 %{
+#include <taglib/tstring.h>
+#include <taglib/tstringlist.h>
+#include <taglib/tfile.h>
+
 #if defined(HAVE_RUBY_ENCODING_H) && HAVE_RUBY_ENCODING_H
 # include <ruby/encoding.h>
 # define ASSOCIATE_UTF8_ENCODING(value) rb_enc_associate(value, rb_utf8_encoding());
@@ -68,6 +73,25 @@ TagLib::StringList ruby_array_to_taglib_string_list(VALUE ary) {
   }
   return result;
 }
+
+VALUE taglib_filename_to_ruby_string(TagLib::FileName filename) {
+#ifdef _WIN32
+  const char *s = (const char *) filename;
+  return rb_tainted_str_new2(s);
+#else
+  return rb_tainted_str_new2(filename);
+#endif
+}
+
+TagLib::FileName ruby_string_to_taglib_filename(VALUE s) {
+#ifdef _WIN32
+  const char *filename = StringValuePtr(s);
+  return TagLib::FileName(filename);
+#else
+  return StringValuePtr(s);
+#endif
+}
+
 %}
 
 // vim: set filetype=cpp sw=2 ts=2 expandtab: