taglib-ruby 0.3.1 → 0.4.0

data/CHANGES.md

@@ -1,6 +1,20 @@
 Changes in Releases of taglib-ruby
 ==================================
 
+## 0.4.0 (2012-03-18)
+
+* Pre-compiled binary gem for Windows (Ruby 1.9) with TagLib 1.7.1
+* Unicode filename support on Windows
+* Add `open` class method to `FileRef` and `File` classes (use it
+  instead of `new` and `close`):
+
+```ruby
+title = TagLib::FileRef.open("file.mp3") do |file|
+  tag = file.tag
+  tag.title
+end
+```
+
 ## 0.3.1 (2012-01-22)
 
 * Fix ObjectPreviouslyDeleted exception after calling

data/Gemfile

@@ -1,12 +1,4 @@
 source 'http://rubygems.org'
 
-group :development do
-  gem 'rake-compiler', '~> 0.7'
-
-  gem 'shoulda', '~> 2.11'
-  gem 'bundler', '~> 1.0.0'
-  gem 'jeweler', '~> 1.6.4'
-  gem 'yard', '~> 0.7'
-  gem 'redcarpet', '~> 1.0'
-  gem 'guard-test', '~> 0.4.0'
-end
+# Use dependencies from .gemspec
+gemspec

data/Guardfile

@@ -4,5 +4,5 @@
 guard :test do
   watch(%r{^lib/(.+)\.so$})     { "test" }
   watch('test/test_helper.rb')  { "test" }
-  watch(%r{^test/test_.+\.rb$})
+  watch(%r{^test/.+_test\.rb$})
 end

data/LICENSE.txt

@@ -1,5 +1,7 @@
 Copyright (c) 2010-2012 Robin Stocker
 
+MIT License
+
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
 "Software"), to deal in the Software without restriction, including

data/README.md

@@ -16,10 +16,10 @@ taglib-ruby is work in progress, but the following is already available:
 
 Some things are still left to do (contributors very welcome):
 
-* Pre-compiled Gem for Windows:
-  * Unicode filename support
 * More coverage of the library
 
+[![Build status][travis-img]][travis-link]
+
 [![flattr this project][flattr-img]][flattr-link]
 
 Installation
@@ -44,82 +44,7 @@ Complete API documentation can be found here:
 
 http://rubydoc.info/gems/taglib-ruby/frames
 
-What follows are some examples of how to use taglib-ruby. Here's how to
-read an ID3v2 tag:
-
-```ruby
-require 'taglib'
-
-# 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
-
-# Access all frames
-tag.frame_list.size  #=> 13
-
-# 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..."
-
-# Close file to release resources
-file.close
-```
-
-And here's an example for writing one:
-
-```ruby
-file = TagLib::MPEG::File.new("joga.mp3")
-tag = file.id3v2_tag
-
-# 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 }
-
-tag.add_frame(apic)
-
-file.save
-file.close
-```
-
-### Encoding
-
-By default, taglib stores text frames as ISO-8859-1 (Latin-1), if the
-text contains only characters that are available in that encoding. If
-not (e.g. with Cyrillic, Chinese, Japanese), it prints a warning and
-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:
-
-```ruby
-frame_factory = TagLib::ID3v2::FrameFactory.instance
-frame_factory.default_text_encoding = TagLib::String::UTF8
-```
-
-Another option is using the advanced API:
-
-```ruby
-title = tag.frame_list('TIT2').first
-title.text = "Jóga"
-title.text_encoding = TagLib::String::UTF8
-```
+Begin with the {TagLib} namespace.
 
 Release Notes
 -------------
@@ -146,11 +71,17 @@ Contributing
 License
 -------
 
+Copyright (c) 2010-2012 Robin Stocker.
+
 taglib-ruby is distributed under the MIT License,
 see LICENSE.txt for details.
 
-Copyright (c) 2010-2012 Robin Stocker.
+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
+[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
 [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,8 +1,6 @@
 # encoding: utf-8
 
-require 'rubygems'
-require "rubygems/package_task"
-require 'bundler'
+require 'bundler/gem_tasks'
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
@@ -10,45 +8,14 @@ rescue Bundler::BundlerError => e
   $stderr.puts "Run `bundle install` to install missing gems"
   exit e.status_code
 end
-require 'rake'
-
-require 'jeweler'
-require './lib/taglib/version.rb'
-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}
-  gem.description = <<-DESC
-Ruby interface for the taglib C++ library.
-
-In contrast to other libraries, this one wraps the C++ API using SWIG,
-not only the minimal C API. This means that all tags can be accessed.
-  DESC
-  gem.requirements = 'taglib (libtag1-dev in Debian/Ubuntu, taglib-devel in Fedora/RHEL)'
-  gem.version = TagLib::Version::STRING
-  gem.license = "MIT"
-  gem.email = "robin@nibor.org"
-  gem.homepage = "http://github.com/robinst/taglib-ruby"
-  gem.authors = ["Robin Stocker"]
-  gem.extensions = ['ext/taglib_base/extconf.rb',
-                    'ext/taglib_mpeg/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/testtask'
 Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
+  test.libs << 'test'
+  test.pattern = 'test/**/*_test.rb'
 end
 
-task :default => :test
+task :default => [:compile, :test]
 
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
@@ -56,6 +23,7 @@ YARD::Rake::YardocTask.new do |t|
   t.options = ['--title', "taglib-ruby #{version}"]
 end
 
-$gemspec = jeweler_tasks.jeweler.gemspec.dup
+# Change to Bundler::GemHelper.gemspec when it's released
+$gemspec = Bundler.load_gemspec('taglib-ruby.gemspec')
 
 FileList['tasks/**/*.rake'].each { |task| import task }

data/docs/taglib/base.rb

@@ -6,9 +6,9 @@
 #   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}
+#   {TagLib::ID3v2::Tag}
 # * Reading/writing Ogg Vorbis tags: {TagLib::Ogg::Vorbis::File}.
-# 
+#
 # ## String Encodings
 #
 # Sometimes, it is necessary to specify which encoding should be used to
@@ -31,7 +31,48 @@ module TagLib
   #
   # Should you need more, use the file type specific classes, see
   # subclasses of {TagLib::File}.
+  #
+  # @example Reading tags
+  #   TagLib::FileRef.open("foo.flac") do |file|
+  #     tag = file.tag
+  #     puts tag.artist
+  #     puts tag.title
+  #   end
+  #
+  # @example Reading audio properties
+  #   TagLib::FileRef.open("bar.oga") do |file|
+  #     prop = file.audio_properties
+  #     puts prop.length
+  #     puts prop.bitrate
+  #   end
+  #
   class FileRef
+
+    # Creates a new file and passes it to the provided block,
+    # closing the file automatically at the end of the block.
+    #
+    # Note that after the block is done, the file is closed and
+    # all memory is released for objects read from the file
+    # (basically everything from the `TagLib` namespace).
+    #
+    # Using `open` is preferable to using `new` and then
+    # manually `close`.
+    #
+    # @example Reading a title
+    #   title = TagLib::FileRef.open("file.oga") do |file|
+    #     tag = file.tag
+    #     tag.title
+    #   end
+    #
+    # @param (see #initialize)
+    # @yield [file] the {FileRef} object, as obtained by {#initialize}
+    # @return the return value of the block
+    #
+    # @since 0.4.0
+    def self.open(filename, read_audio_properties=true,
+                   audio_properties_style=TagLib::AudioProperties::Average)
+    end
+
     # Create a FileRef from a file name.
     #
     # @param [String] filename
@@ -75,11 +116,13 @@ module TagLib
   # @abstract Base class for files, see subclasses.
   class File
     # Closes the file and releases all objects that were read from the
-    # file.
+    # file (basically everything from the TagLib namespace).
     #
     # 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 = TagLib::MPEG::File.new("file.mp3")
+    #     # ...
     #     file.close
     #     file = nil
     #
@@ -88,6 +131,12 @@ module TagLib
     # run, which may be much later. On Windows, this is especially
     # important as the file is locked until it is closed.
     #
+    # As a better alternative to this, use the `open` class method:
+    #
+    #     TagLib::MPEG::File.open("file.mp3") do |file|
+    #        # ...
+    #     end
+    #
     # @return [void]
     def close
     end

data/docs/taglib/id3v2.rb

@@ -1,5 +1,66 @@
 module TagLib::ID3v2
-  # An ID3v2 tag.
+  # An ID3v2 tag. A tag consists of a list of frames, identified by IDs.
+  #
+  # ## Encoding
+  #
+  # By default, taglib stores ID3v2 text frames as ISO-8859-1 (Latin-1) if the
+  # text contains only characters that are available in that encoding. If
+  # not (e.g. with Cyrillic, Chinese, Japanese), it prints a warning and
+  # 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
+  #
+  # Another option is using the frame API directly:
+  #
+  #     title = tag.frame_list('TIT2').first
+  #     title.text = "Joga"
+  #     title.text_encoding = TagLib::String::UTF8
+  #
+  # @example Read ID3v2 frames from a file
+  #   TagLib::MPEG::File.new("wake_up.mp3") do |file|
+  #     tag = file.id3v2_tag
+  #
+  #     # Read basic attributes
+  #     tag.title  #=> "Wake Up"
+  #     tag.artist  #=> "Arcade Fire"
+  #     tag.track  #=> 7
+  #
+  #     # Access all frames
+  #     tag.frame_list.size  #=> 13
+  #
+  #     # 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..."
+  #   end
+  #
+  # @example Add frames and save file
+  #   TagLib::MPEG::File.new("joga.mp3") do |file|
+  #     tag = file.id3v2_tag
+  #
+  #     # 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 }
+  #
+  #     tag.add_frame(apic)
+  #
+  #     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.

data/docs/taglib/mpeg.rb

@@ -1,6 +1,23 @@
 module TagLib::MPEG
   # The file class for `.mp3` and other MPEG files.
+  #
+  # @example Reading a title
+  #   title = TagLib::MPEG::File.open("file.mp3") do |file|
+  #     tag = file.tag
+  #     tag.title
+  #   end
+  #
   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
+    #
+    # @since 0.4.0
+    def self.open(filename, read_properties=true)
+    end
+
     # Load an MPEG file.
     #
     # @param [String] filename

data/docs/taglib/vorbis.rb

@@ -1,7 +1,26 @@
 module TagLib::Ogg::Vorbis
 
   # The file class for `.ogg` and other `.oga` files.
+  #
+  # @example Reading Vorbis comments
+  #   TagLib::Ogg::Vorbis::File.open("file.oga") do |file|
+  #     tag = file.tag
+  #     puts tag.title
+  #     fields = tag.field_list_map
+  #     puts fields['DATE']
+  #   end
+  #
   class File < TagLib::Ogg::File
+    # {include:TagLib::FileRef.open}
+    #
+    # @param (see #initialize)
+    # @yield [file] the {File} object, as obtained by {#initialize}
+    # @return the return value of the block
+    #
+    # @since 0.4.0
+    def self.open(filename, read_properties=true)
+    end
+
     # Load an Ogg Vorbis file.
     #
     # @param [String] filename

data/ext/taglib_base/includes.i

@@ -85,8 +85,26 @@ VALUE taglib_filename_to_ruby_string(TagLib::FileName filename) {
 
 TagLib::FileName ruby_string_to_taglib_filename(VALUE s) {
 #ifdef _WIN32
-  const char *filename = StringValuePtr(s);
-  return TagLib::FileName(filename);
+  #if defined(HAVE_RUBY_ENCODING_H) && HAVE_RUBY_ENCODING_H
+    VALUE ospath;
+    const char *utf8;
+    int len;
+    wchar_t *wide;
+
+    ospath = rb_str_encode_ospath(s);
+    utf8 = StringValuePtr(ospath);
+    len = MultiByteToWideChar(CP_UTF8, 0, utf8, -1, NULL, 0);
+    if (!(wide = (wchar_t *) xmalloc(sizeof(wchar_t) * len))) {
+      return TagLib::FileName((const char *) NULL);
+    }
+    MultiByteToWideChar(CP_UTF8, 0, utf8, -1, wide, len);
+    TagLib::FileName filename(wide);
+    xfree(wide);
+    return filename;
+  #else
+    const char *filename = StringValuePtr(s);
+    return TagLib::FileName(filename);
+  #endif
 #else
   return StringValuePtr(s);
 #endif