Added read(), removed AudioProperties.

The read() call asynchronously fetches read-only tags and audio properties and
discards the FileRef. This makes AudioProperties a redundant and synchronous
way to fetch audio properties. Since they are read only by default, unlike tags,
it is getter to just extract them and stuff them into an object rather than
have a backing C++ object.

Author: nikhilm

Diff for: README.md

@@ -56,6 +56,33 @@ The `examples` show usage.
 
 ## API
 
+### read(path, callback)
+
+The function you will most likely want to use. `callback` should have signature
+`callback(err, tag, audioProperties)` where `tag` and `audioProperties` are
+plain-old JavaScript objects. For the distinction between these and `Tag`, see
+`Tag` below.
+
+tag can have the following fields. node-taglib currently supports only the
+fields common to all formats:
+
+* title   (string)
+* album   (string)
+* comment (string)
+* artist  (string)
+* track   (string)
+* year    (integer)
+* genre   (string)
+
+The following fields are available in audioProperties, all are integers:
+
+* length
+* bitrate
+* sampleRate
+* channels
+
+Writing audio properties is not supported.
+
 ### tag(path, callback)
 
 Read the tag from the file at `path` _asynchronously_. The callback should have
@@ -75,16 +102,8 @@ errors occurred, throws an exception.
 **NOTE: A Tag object should *NOT* be created using `new`. Instead use `tag()`
 or `tagSync()`**
 
-A Tag object allows access to all the meta-data fields. node-taglib currently
-supports only the fields common to all formats:
-
-* title   (string)
-* album   (string)
-* comment (string)
-* artist  (string)
-* track   (string)
-* year    (integer)
-* genre   (string)
+A Tag object allows _read-write_ access to all the meta-data fields. For valid
+field names see `read()` above.
 
 To get a value, simply access the field -- `tag.artist`.
 
@@ -96,10 +115,9 @@ have to call `saveSync()`** to actually save the changes to the file on disc.
 Due to TagLib's design, every `Tag` object in memory has to keep its backing
 file descriptor open. If you are dealing with a large number of files, you will
 soon run into problems because operating systems impose limits on how many
-files a process can have open simultaneously. If you only want to read
-meta-data and not write it immediately, then **deep copy** the fields over to
-a plain JS object, then dispose the `Tag` object so that you can operate on
-more files.
+files a process can have open simultaneously. If you want to only read tags,
+use `read()` instead as it will immediately close the file after the tag is
+read.
 
 ### Tag.save(callback)
 
@@ -116,25 +134,6 @@ Save any changes in the Tag meta-data to disk _synchronously_.
 
 Returns whether the tag is empty or not.
 
-### AudioProperties(path)
-
-**NOTE: This will be replaced by a more functional API, similar to the tags API.**
-
-Object to get the audio properties of file at `path`. Throws an exception on
-errors.
-
-    var ap = new taglib.AudioProperties('path');
-    console.log("Bitrate", ap.bitrate);
-
-The following fields are available:
-
-* length
-* bitrate
-* sampleRate
-* channels
-
-Writing audio properties is not supported.
-
 ### taglib.WITH_ASF
 
 A boolean representing whether node-taglib supports ASF files. Depends on

Diff for: async.js

@@ -11,7 +11,7 @@ match.find(process.argv[2], {fileFilters: [isMp3]}, function(err, files) {
     var count = 0;
     console.log(files.length, "files");
     async.forEach(files, function(fn, cb) {
-        taglib.tag(fn, function(err, tag) {
+        taglib.read(fn, function(err, tag) {
             if (err) {
                 console.log("ERROR");
                 return cb(false);

Diff for: examples/simple.js

@@ -2,7 +2,7 @@ var Taglib = require(__dirname+"/../taglib")
 var util = require("util")
 
 for (var i = 2; i < process.argv.length; i++) {
-    Taglib.tag(process.argv[i], function(err, tag) {
-        console.dir(err ? err : tag);
+    Taglib.read(process.argv[i], function(err, tag, props) {
+        console.dir(err ? err : {'tag': tag, 'audioProperties': props});
     });
 }

Diff for: spec/taglibSpec.js

@@ -80,30 +80,6 @@ vows.describe('taglib bindings')
     }
   },
 
-  'reading AudioProperties from non-existent file': {
-    topic: function() {
-        return function() {
-          return new Taglib.AudioProperties('thisfileobviouslyshouldnot.exist');
-        }
-    },
-
-    'should throw an exception': function(topic) {
-        assert.throws(topic, /readable/);
-    }
-  },
-
-  'reading AudioProperties from a non-audio file': {
-    topic: function() {
-        return function() {
-          return new Taglib.AudioProperties(__filename);
-        }
-    },
-
-    'should throw an exception': function(topic) {
-        assert.throws(topic, /extract audio properties/);
-    }
-  },
-
   'writing Tags to File': {
     topic: function() {
       var filename = __dirname+'/sample-write.mp3';
@@ -142,25 +118,6 @@ vows.describe('taglib bindings')
     }
   },
 
-  'reading Properties from File': {
-    topic: new Taglib.AudioProperties(__dirname+'/blip.mp3'),
-    'should be a `AudioProperties`': function (prop) {
-      assert.equal(Taglib.AudioProperties, prop.constructor);
-    },
-    'should have length 1 second': function(prop) {
-      assert.equal(1, prop.length);
-    },
-    'should have bitrate 128kbps': function(prop) {
-      assert.equal(128, prop.bitrate);
-    },
-    'should have sampleRate 44100Hz': function(prop) {
-      assert.equal(44100, prop.sampleRate);
-    },
-    'should have 2 channels': function(prop) {
-      assert.equal(2, prop.channels);
-    },
-  },
-
   'reading Tag from a file asynchronously': {
     topic: function() {
         Taglib.tag(__dirname+'/sample.mp3', this.callback);
@@ -210,5 +167,69 @@ vows.describe('taglib bindings')
       var tag = Taglib.tagSync(filename);
       assert.equal(tag.title, "Something completely different…");
     }
+  },
+
+  'reading file metadata asynchronously': {
+    topic: function() {
+      Taglib.read(__dirname+'/sample.mp3', this.callback);
+    },
+
+    'should be called with three arguments': function (err, tag, props) {
+      assert.isNull(err);
+      assert.isObject(tag);
+      assert.isObject(props);
+    },
+
+    'reading tags': {
+      topic: function() {
+        Taglib.read(__dirname+'/sample.mp3', this.callback);
+      },
+
+      'title should be `A bit-bucket full of tags`': function (tag) {
+        assert.equal(tag.title, 'A bit-bucket full of tags');
+      },
+      'artist should be by `gitzer\'s`': function (tag) {
+        assert.equal(tag.artist, 'gitzer\'s');
+      },
+      'album should be on `Waffles for free!`': function (tag) {
+        assert.equal(tag.album, "Waffles for free!");
+      },
+      'track should be the first': function (tag) {
+        assert.equal(tag.track, 1);
+      },
+      'should be from 2011': function (tag) {
+        assert.equal(tag.year, 2011);
+      },
+      'should have a silly comment': function(tag) {
+        assert.equal(tag.comment, "Salami Wiglet.");
+      }
+    },
+
+    'reading audioProperties': {
+      topic: function() {
+        Taglib.read(__dirname+'/blip.mp3', this.callback);
+      },
+
+      'should have length 1 second': function(err, _, prop) {
+        assert.equal(prop.length, 1);
+      },
+      'should have bitrate 128kbps': function(err, _, prop) {
+        assert.equal(prop.bitrate, 128);
+      },
+      'should have sampleRate 44100Hz': function(err, _, prop) {
+        assert.equal(prop.sampleRate, 44100);
+      },
+      'should have 2 channels': function(err, _, prop) {
+        assert.equal(prop.channels, 2);
+      }
+    },
+  },
+
+  'read() on non-existent file': {
+    topic: function() {
+      return function() {
+        Taglib.read('thisfileobviouslyshouldnot.exist', this.callback);
+      }
+    },
   }
 }).export(module);