lame 0.0.1 → 0.0.2

data/README.md

@@ -136,26 +136,51 @@ end
 
 ### Encoding
 
-TODO
+See `spec/integration/encoding_spec.rb` for an example how to encode a WAV file
+to an MP3 file.
 
-### Decoding
+The available encoding functions are:
 
-Check this link for a 'simple' example. Note that we need to deal with the
-ID3 tags ourselves before decoding MP3 frames.
+```ruby
+encoder = LAME::Encoder.new
 
-http://sourceforge.net/mailarchive/message.php?msg_id=26907120
+# encode shorts (−32,768 to +32,767), for 16-bit audio
+encoder.encode_short(left, right) do |mp3_frame|
+  # ...
+end
 
-Analysis of `lame_decode_initfile` in `get_audio.c`:
+# encode floats (−1.0 to +1.0), for 32-bit floating point audio
+encoder.encode_float(left, right) do |mp3_frame|
+  # ...
+end
 
-1. `hip_decode_init`
-2. Read ID3 tags, starting with "ID3"
-3. The length of the ID3 tag are at the start (right after "ID3")
-4. Optionally read the contents of the ID3 tag, or just skip it
-5. Check if there is a "AID" header, and skip it
-6. Read up until the first "mp123 syncword"
+# encode longs (system dependent, +/- 2^(bits_per_long-1)
+encoder.encode_long(left, right) do |mp3_frame|
+  # ...
+end
+
+# encode interleaved shorts
+encoder.encode_interleaved_short(samples) do |mp3_frame|
+  # ...
+end
+
+# encode interleaved floats
+encoder.encode_interleaved_float(samples) do |mp3_frame|
+  # ...
+end
+```
+
+The `left` and `right` are arrays of sample values for the given data type.
+
+### Decoding
+
+See `spec/integration/decoding_spec.rb` for an example how to decode an MP3 file
+to an WAV file.
 
 ### Development
 
+This section contains some references used during development of this gem.
+
 #### ID3v2 tags
 
 To use ID3v2 tags in files, see this post on the `lame-dev` mailing list:
@@ -165,13 +190,43 @@ http://sourceforge.net/mailarchive/message.php?msg_id=18557283
 So:
 
 1. Disable automatic id3tag writing
-2. Write id3v2 tag at start of file (keep track of position)
+2. Write id3v2 tag at start of file (keep track of size of this tag)
 3. Write audio to file
 4. Write id3v1 tag at end of file
-5. Write vbr 'lametag' at start of audio (using position)
+5. Write vbr 'lametag' at start of audio (using the size of the id3v2 tag)
 
 See the example code in `spec/integration/encoding_spec.rb` for an example.
 
+#### Decoding
+
+Check this link for a 'simple' example. Note that we need to deal with the
+ID3 tags ourselves before decoding MP3 frames.
+
+http://sourceforge.net/mailarchive/message.php?msg_id=26907120
+
+Analysis of `lame_decode_initfile` in `get_audio.c`:
+
+1. `hip_decode_init`
+2. Read ID3 tags, starting with "ID3"
+3. The length of the ID3 tag are at the start (right after "ID3")
+4. Optionally read the contents of the ID3 tag, or just skip it
+5. Check if there is a "AID" header, and skip it
+6. Read up until the first "mp123 syncword"
+
+After this, we are ready to decode MP3 data.
+
+1. Check if there are some samples in the internal decoder by passing an empty
+   input-buffer into the decoder.
+2. If some decoded audio samples were indeed left in the internal decoder, do 
+   something useful with them.
+3. Repeat this until no audio is left in the internal buffer.
+4. Read some data from the file (starting at the "mp123 syncword") and feed it
+   to the decoder.
+5. Handle the decoded audio.
+6. Now repeat this process (`GOTO 1`) until the end of the MP3 file.
+
+See the example code in `spec/integration/decoding_spec.rb` for an example.
+
 ## Contributing
 
 1. Fork it

data/lib/lame.rb

@@ -6,7 +6,13 @@ require "lame/delegation"
 require "lame/configuration"
 require "lame/buffer"
 
-require "lame/encoding/encode_short_buffer"
+require "lame/encoding/stereo_buffer_encoder"
+require "lame/encoding/short_buffer_encoder"
+require "lame/encoding/float_buffer_encoder"
+require "lame/encoding/long_buffer_encoder"
+require "lame/encoding/interleaved_buffer_encoder"
+require "lame/encoding/interleaved_short_buffer_encoder"
+require "lame/encoding/interleaved_float_buffer_encoder"
 require "lame/encoding/flusher"
 require "lame/encoding/id3"
 require "lame/encoding/vbr_info"

data/lib/lame/encoder.rb

@@ -1,6 +1,17 @@
 module LAME
   class Encoder
 
+    STEREO_ENCODERS = {
+      :short => Encoding::ShortBufferEncoder,
+      :float => Encoding::FloatBufferEncoder,
+      :long => Encoding::LongBufferEncoder
+    }
+
+    INTERLEAVED_ENCODERS = {
+      :short => Encoding::InterleavedShortBufferEncoder,
+      :float => Encoding::InterleavedFloatBufferEncoder
+    }
+
     attr_reader :global_flags
 
     def initialize
@@ -12,13 +23,24 @@ module LAME
       apply_configuration
     end
 
-    def encode_short(left, right)
-      apply_configuration
+    def encode_short(left, right, &block)
+      encode_stereo(left, right, :short, &block)
+    end
 
-      each_frame(left, right) do |left_frame, right_frame|
-        mp3_data = Encoding::EncodeShortBuffer.new(configuration).encode_frame(left_frame, right_frame)
-        yield mp3_data
-      end
+    def encode_float(left, right, &block)
+      encode_stereo(left, right, :float, &block)
+    end
+
+    def encode_long(left, right, &block)
+      encode_stereo(left, right, :long, &block)
+    end
+
+    def encode_interleaved_short(samples, &block)
+      encode_interleaved(samples, :short, &block)
+    end
+
+    def encode_interleaved_float(samples, &block)
+      encode_interleaved(samples, :float, &block)
     end
 
     def flush(&block)
@@ -55,12 +77,36 @@ module LAME
       configuration.apply! unless configuration.applied?
     end
 
+    def encode_stereo(left, right, data_type)
+      apply_configuration
+
+      each_frame(left, right) do |left_frame, right_frame|
+        mp3_data = STEREO_ENCODERS[data_type].new(configuration).encode_frame(left_frame, right_frame)
+        yield mp3_data
+      end
+    end
+
+    def encode_interleaved(interleaved_samples, data_type)
+      apply_configuration
+
+      each_interleaved_frame(interleaved_samples) do |interleaved_frame|
+        mp3_data = INTERLEAVED_ENCODERS[data_type].new(configuration).encode_frame(interleaved_frame)
+        yield mp3_data
+      end
+    end
+
     def each_frame(left, right)
       left.zip(right).each_slice(framesize) do |slice|
         yield slice.transpose
       end
     end
 
+    def each_interleaved_frame(interleaved_samples)
+      interleaved_samples.each_slice(framesize * 2) do |slice|
+        yield slice
+      end
+    end
+
     def yield_or_return(value)
       if block_given?
         yield value

data/lib/lame/encoding/float_buffer_encoder.rb

@@ -0,0 +1,15 @@
+module LAME
+  module Encoding
+    class FloatBufferEncoder < StereoBufferEncoder
+
+      def data_type
+        :float
+      end
+
+      def lame_function
+        :lame_encode_buffer_ieee_float
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/flusher.rb

@@ -3,7 +3,9 @@ module LAME
     class Flusher
       extend Forwardable
 
-      def_delegators :@configuration, :global_flags, :framesize, :output_buffer_size
+      attr_reader :configuration
+
+      def_delegators :configuration, :global_flags, :framesize, :output_buffer_size
 
       def initialize(configuration)
         @configuration = configuration

data/lib/lame/encoding/id3.rb

@@ -3,7 +3,9 @@ module LAME
     class Id3
       extend Forwardable
 
-      def_delegators :@configuration, :global_flags, :framesize, :output_buffer_size
+      attr_reader :configuration
+
+      def_delegators :configuration, :global_flags, :framesize, :output_buffer_size
 
       def initialize(configuration)
         @configuration = configuration

data/lib/lame/encoding/interleaved_buffer_encoder.rb

@@ -0,0 +1,27 @@
+module LAME
+  module Encoding
+    class InterleavedBufferEncoder
+      extend Forwardable
+
+      attr_reader :configuration
+
+      def_delegators :configuration, :global_flags, :framesize, :output_buffer_size
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def encode_frame(interleaved_samples)
+        interleaved_buffer = Buffer.create(data_type, interleaved_samples)
+        output             = Buffer.create_empty(:uchar, output_buffer_size)
+
+        mp3_size = LAME.send(lame_function, global_flags,
+                                            interleaved_buffer, interleaved_samples.size/2,
+                                            output, output_buffer_size)
+
+        output.get_bytes(0, mp3_size)
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/interleaved_float_buffer_encoder.rb

@@ -0,0 +1,15 @@
+module LAME
+  module Encoding
+    class InterleavedFloatBufferEncoder < InterleavedBufferEncoder
+
+      def data_type
+        :float
+      end
+
+      def lame_function
+        :lame_encode_buffer_interleaved_ieee_float
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/interleaved_short_buffer_encoder.rb

@@ -0,0 +1,15 @@
+module LAME
+  module Encoding
+    class InterleavedShortBufferEncoder < InterleavedBufferEncoder
+
+      def data_type
+        :short
+      end
+
+      def lame_function
+        :lame_encode_buffer_interleaved
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/long_buffer_encoder.rb

@@ -0,0 +1,15 @@
+module LAME
+  module Encoding
+    class LongBufferEncoder < StereoBufferEncoder
+
+      def data_type
+        :long
+      end
+
+      def lame_function
+        :lame_encode_buffer_long2
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/short_buffer_encoder.rb

@@ -0,0 +1,15 @@
+module LAME
+  module Encoding
+    class ShortBufferEncoder < StereoBufferEncoder
+
+      def data_type
+        :short
+      end
+
+      def lame_function
+        :lame_encode_buffer
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/stereo_buffer_encoder.rb

@@ -0,0 +1,28 @@
+module LAME
+  module Encoding
+    class StereoBufferEncoder
+      extend Forwardable
+
+      attr_reader :configuration
+
+      def_delegators :configuration, :global_flags, :framesize, :output_buffer_size
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def encode_frame(left, right)
+        left_buffer  = Buffer.create(data_type, left)
+        right_buffer = Buffer.create(data_type, right)
+        output       = Buffer.create_empty(:uchar, output_buffer_size)
+
+        mp3_size = LAME.send(lame_function, global_flags,
+                                            left_buffer, right_buffer, left.size,
+                                            output, output_buffer_size)
+
+        output.get_bytes(0, mp3_size)
+      end
+
+    end
+  end
+end

data/lib/lame/encoding/vbr_info.rb

@@ -3,7 +3,9 @@ module LAME
     class VBRInfo
       extend Forwardable
 
-      def_delegators :@configuration, :global_flags, :framesize, :output_buffer_size
+      attr_reader :configuration
+
+      def_delegators :configuration, :global_flags, :framesize, :output_buffer_size
 
       def initialize(configuration)
         @configuration = configuration

data/lib/lame/version.rb

@@ -1,3 +1,3 @@
 module LAME
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/encoder_spec.rb

@@ -54,86 +54,197 @@ module LAME
 
       let(:left) { [0] }
       let(:right) { [0] }
+      let(:samples) { [0,0] }
+
       let(:global_flags) { subject.global_flags }
       let(:configuration) { stub(Configuration, :framesize => 100) }
 
       before do
         Configuration.stub(:new).and_return(configuration)
         configuration.stub(:applied?).and_return(true)
-        Encoding::EncodeShortBuffer.stub(:new).and_return(stub.as_null_object)
       end
 
-      it "applies the configuration if not done already" do
-        configuration.stub(:applied?).and_return(false)
-        configuration.should_receive(:apply!)
-        encoder.encode_short(left, right) { }
-      end
+      describe "#encode_short" do
 
-      it "does not apply the configuration if already applied" do
-        configuration.stub(:applied?).and_return(true)
-        configuration.should_not_receive(:apply!)
-        encoder.encode_short(left, right) { }
+        before do
+          Encoding::ShortBufferEncoder.stub(:new).and_return(stub.as_null_object)
+        end
+
+        it "applies the configuration if not done already" do
+          configuration.stub(:applied?).and_return(false)
+          configuration.should_receive(:apply!)
+          encoder.encode_short(left, right) { }
+        end
+
+        it "does not apply the configuration if already applied" do
+          configuration.stub(:applied?).and_return(true)
+          configuration.should_not_receive(:apply!)
+          encoder.encode_short(left, right) { }
+        end
+
+        context "delegation" do
+          let(:short_encoder) { stub.as_null_object }
+
+          before do
+            Encoding::ShortBufferEncoder.stub(:new).and_return(short_encoder)
+          end
+
+          it "create a short encoder with configuration" do
+            Encoding::ShortBufferEncoder.should_receive(:new).with(configuration)
+
+            encoder.encode_short(left, right) { }
+          end
+
+          it "delegates encoding to the short encoder" do
+            left.stub(:length => 100) # exactly framesize
+            short_encoder.should_receive(:encode_frame).with(left, right)
+
+            encoder.encode_short(left, right) { }
+          end
+
+          it "yields the encoder results" do
+            mp3_data = stub
+            short_encoder.stub(:encode_frame).and_return(mp3_data)
+
+            expect { |block|
+              encoder.encode_short(left, right, &block)
+            }.to yield_with_args(mp3_data)
+          end
+
+          it "delegates multiple times for large input" do
+            right = left = [0]*150 # larger than framesize
+
+            short_encoder.should_receive(:encode_frame) do |left_frame, right_frame|
+              left_frame.length.should eql 100
+              right_frame.length.should eql 100
+            end
+
+            short_encoder.should_receive(:encode_frame) do |left_frame, right_frame|
+              left_frame.length.should eql 50
+              right_frame.length.should eql 50
+            end
+
+            encoder.encode_short(left, right) { }
+          end
+
+          it "yields multiple times for large input" do
+            mp3_data1 = stub("frame1")
+            mp3_data2 = stub("frame2")
+
+            left = [0]*150 # larger than framesize
+
+            short_encoder.stub(:encode_frame).and_return(mp3_data1, mp3_data2)
+
+            expect { |block|
+              encoder.encode_short(left, right, &block)
+            }.to yield_successive_args(mp3_data1, mp3_data2)
+          end
+        end
       end
 
-      context "delegation" do
-        let(:short_encoder) { stub.as_null_object }
+      describe "#encode_float" do
+        it "create a float encoder" do
+          Encoding::FloatBufferEncoder.stub(:new).and_return(stub.as_null_object)
+          Encoding::FloatBufferEncoder.should_receive(:new).with(configuration)
 
-        before do
-          Encoding::EncodeShortBuffer.stub(:new).and_return(short_encoder)
+          encoder.encode_float(left, right) { }
         end
+      end
 
-        it "create a short encoder with configuration" do
-          Encoding::EncodeShortBuffer.should_receive(:new).with(configuration)
+      describe "#encode_long" do
+        it "create a long encoder" do
+          Encoding::LongBufferEncoder.stub(:new).and_return(stub.as_null_object)
+          Encoding::LongBufferEncoder.should_receive(:new).with(configuration)
 
-          encoder.encode_short(left, right) { }
+          encoder.encode_long(left, right) { }
         end
+      end
 
-        it "delegates encoding to the short encoder" do
-          left.stub(:length => 100) # exactly framesize
-          short_encoder.should_receive(:encode_frame).with(left, right)
+      describe "#encode_interleaved_short" do
 
-          encoder.encode_short(left, right) { }
+        before do
+          Encoding::InterleavedShortBufferEncoder.stub(:new).and_return(stub.as_null_object)
         end
 
-        it "yields the encoder results" do
-          mp3_data = stub
-          short_encoder.stub(:encode_frame).and_return(mp3_data)
+        it "applies the configuration if not done already" do
+          configuration.stub(:applied?).and_return(false)
+          configuration.should_receive(:apply!)
+          encoder.encode_interleaved_short(samples) { }
+        end
 
-          expect { |block|
-            encoder.encode_short(left, right, &block)
-          }.to yield_with_args(mp3_data)
+        it "does not apply the configuration if already applied" do
+          configuration.stub(:applied?).and_return(true)
+          configuration.should_not_receive(:apply!)
+          encoder.encode_interleaved_short(samples) { }
         end
 
-        it "delegates multiple times for large input" do
-          right = left = [0]*150 # larger than framesize
+        context "delegation" do
+          let(:interleaved_short_encoder) { stub.as_null_object }
 
-          short_encoder.should_receive(:encode_frame) do |left_frame, right_frame|
-            left_frame.length.should eql 100
-            right_frame.length.should eql 100
+          before do
+            Encoding::InterleavedShortBufferEncoder.stub(:new).and_return(interleaved_short_encoder)
           end
 
-          short_encoder.should_receive(:encode_frame) do |left_frame, right_frame|
-            left_frame.length.should eql 50
-            right_frame.length.should eql 50
+          it "create a short encoder with configuration" do
+            Encoding::InterleavedShortBufferEncoder.should_receive(:new).with(configuration)
+
+            encoder.encode_interleaved_short(samples) { }
           end
 
-          encoder.encode_short(left, right) { }
-        end
+          it "delegates encoding to the short encoder" do
+            samples.stub(:length => 200) # exactly framesize
+            interleaved_short_encoder.should_receive(:encode_frame).with(samples)
 
-        it "yields multiple times for large input" do
-          mp3_data1 = stub("frame1")
-          mp3_data2 = stub("frame2")
+            encoder.encode_interleaved_short(samples) { }
+          end
+
+          it "yields the encoder results" do
+            mp3_data = stub
+            interleaved_short_encoder.stub(:encode_frame).and_return(mp3_data)
 
-          left = [0]*150 # larger than framesize
+            expect { |block|
+              encoder.encode_interleaved_short(samples, &block)
+            }.to yield_with_args(mp3_data)
+          end
 
-          short_encoder.stub(:encode_frame).and_return(mp3_data1, mp3_data2)
+          it "delegates multiple times for large input" do
+            samples = [0]*300 # larger than framesize
 
-          expect { |block|
-            encoder.encode_short(left, right, &block)
-          }.to yield_successive_args(mp3_data1, mp3_data2)
+            interleaved_short_encoder.should_receive(:encode_frame) do |samples|
+              samples.length.should eql 200
+            end
+
+            interleaved_short_encoder.should_receive(:encode_frame) do |samples|
+              samples.length.should eql 100
+            end
+
+            encoder.encode_interleaved_short(samples) { }
+          end
+
+          it "yields multiple times for large input" do
+            mp3_data1 = stub("frame1")
+            mp3_data2 = stub("frame2")
+
+            samples = [0]*300 # larger than framesize
+
+            interleaved_short_encoder.stub(:encode_frame).and_return(mp3_data1, mp3_data2)
+
+            expect { |block|
+              encoder.encode_interleaved_short(samples, &block)
+            }.to yield_successive_args(mp3_data1, mp3_data2)
+          end
         end
+      end
+
+      describe "#encode_interleaved_float" do
+        it "create a float encoder" do
+          Encoding::InterleavedFloatBufferEncoder.stub(:new).and_return(stub.as_null_object)
+          Encoding::InterleavedFloatBufferEncoder.should_receive(:new).with(configuration)
 
+          encoder.encode_interleaved_float(samples) { }
+        end
       end
+
     end
 
     context "flushing" do