WaveSwissKnife 0.2.0.20120302

data/lib/WSK/Launcher.rb

@@ -0,0 +1,216 @@
+#--
+# Copyright (c) 2009 - 2012 Muriel Salvan (muriel@x-aeon.com)
+# Licensed under the terms specified in LICENSE file. No warranty is provided.
+#++
+
+require 'optparse'
+require 'date'
+
+module WSK
+
+  class Launcher
+
+    include WSK::Common
+
+    # Constructor
+    def initialize
+      # Options set by the command line parser
+      @InputFileName = nil
+      @OutputFileName = nil
+      @Action = nil
+      @DisplayHelp = false
+      @Debug = false
+      parsePlugins
+
+      # The command line parser
+      @Options = OptionParser.new
+      @Options.banner = 'WSK.rb [--help] [--debug] --input <InputFile> --output <OutputFile> --action <ActionName> -- <ActionOptions>'
+      @Options.on( '--input <InputFile>', String,
+        '<InputFile>: WAVE file name to use as input',
+        'Specify input file name') do |iArg|
+        @InputFileName = iArg
+      end
+      @Options.on( '--output <OutputFile>', String,
+        '<OutputFile>: WAVE file name to use as output',
+        'Specify output file name') do |iArg|
+        @OutputFileName = iArg
+      end
+      @Options.on( '--action <ActionName>', String,
+        "<ActionName>: Name of the action to process. Available Actions: #{get_plugins_names('Actions').sort.join(', ')}",
+        'Specify the Action to execute') do |iArg|
+        @Action = iArg
+      end
+      @Options.on( '--help',
+        'Display help') do
+        @DisplayHelp = true
+      end
+      @Options.on( '--debug',
+        'Activate debug logs') do
+        @Debug = true
+      end
+    end
+
+    # Execute command line arguments
+    #
+    # Parameters::
+    # * *iArgs* (<em>list<String></em>): Command line arguments
+    # Return::
+    # * _Integer_: The error code to return to the terminal
+    def execute(iArgs)
+      rResult = 0
+
+      lBeginTime = DateTime.now
+      lError = nil
+      lActionArgs = nil
+      begin
+        # Split the arguments
+        lMainArgs, lActionArgs = splitParameters(iArgs)
+        lRemainingArgs = @Options.parse(lMainArgs)
+        if (!lRemainingArgs.empty?)
+          lError = RuntimeError.new("Unknown arguments: #{lRemainingArgs.join(' ')}")
+        end
+      rescue Exception
+        lError = $!
+      end
+      if (lError == nil)
+        if (@DisplayHelp)
+          puts @Options
+        else
+          if (@Debug)
+            activate_log_debug(true)
+          end
+          # Check mandatory arguments were given
+          if (@InputFileName == nil)
+            lError = RuntimeError.new('Missing --input option. Please specify an input file.')
+          elsif (@OutputFileName == nil)
+            lError = RuntimeError.new('Missing --output option. Please specify an output file.')
+          elsif (@Action == nil)
+            lError = RuntimeError.new('Missing --action option. Please specify an action to perform.')
+          elsif (!File.exists?(@InputFileName))
+            lError = RuntimeError.new("Missing input file #{@InputFileName}")
+          elsif (File.exists?(@OutputFileName))
+            lError = RuntimeError.new("Output file #{@OutputFileName} already exists.")
+          else
+            # Access the Action
+            access_plugin('Actions', @Action) do |ioActionPlugin|
+              lDesc = ioActionPlugin.pluginDescription
+              # Check the output interface required by this plugin
+              lOutputInterfaceName = lDesc[:OutputInterface]
+              if (lOutputInterfaceName == nil)
+                lOutputInterfaceName = 'DirectStream'
+              end
+              # Initialize the variables if options are specified
+              if (lDesc[:Options] == nil)
+                if (!lActionArgs.empty?)
+                  lError = RuntimeError.new("Unknown Action arguments: #{lActionArgs.join(' ')}. Normally no parameter was expected.")
+                end
+              else
+                # Check options
+                lPluginOptions = OptionParser.new
+                # Variables to instantiate
+                lVariables = {}
+                lDesc[:Options].each do |iVariable, iOptionInfo|
+                  # Set the variable correctly when the option is encountered
+                  lPluginOptions.on(*iOptionInfo) do |iArg|
+                    lVariables[iVariable] = iArg
+                  end
+                end
+                if (lActionArgs.empty?)
+                  lError = RuntimeError.new("Action was expecting arguments: #{lPluginOptions.to_s}. Please specify them after -- separator.")
+                else
+                  # Parse Action's options
+                  begin
+                    lRemainingActionArgs = lPluginOptions.parse(lActionArgs)
+                    if (!lRemainingActionArgs.empty?)
+                      lError = RuntimeError.new("Unknown Action arguments: #{lRemainingActionArgs.join(' ')}. Expected signature: #{lPluginOptions.to_s}")
+                    end
+                  rescue Exception
+                    lError = $!
+                  end
+                  # Instantiate variables if needed
+                  if (lError == nil)
+                    instantiateVars(ioActionPlugin, lVariables)
+                  end
+                end
+              end
+              # Plugin is initialized
+              if (lError == nil)
+                # Access the output interface plugin
+                access_plugin('OutputInterfaces', lOutputInterfaceName) do |ioOutputPlugin|
+                  # Access the input file
+                  lError = accessInputWaveFile(@InputFileName) do |iInputHeader, iInputData|
+                    lInputSubError = nil
+
+                    # Get the maximal output data samples
+                    lNbrOutputDataSamples = ioActionPlugin.get_nbr_samples(iInputData)
+                    log_debug "Number of samples to be written: #{lNbrOutputDataSamples}"
+
+                    # Access the output file
+                    lInputSubError = accessOutputWaveFile(@OutputFileName, iInputHeader, ioOutputPlugin, lNbrOutputDataSamples) do
+                      # Execute
+                      log_info "Execute Action #{@Action}, reading #{@InputFileName} and writing #{@OutputFileName} using #{lOutputInterfaceName} output interface."
+                      next ioActionPlugin.execute(iInputData, ioOutputPlugin)
+                    end
+
+                    next lInputSubError
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+
+      if (lError != nil)
+        log_err "Error encountered: #{lError}"
+        rResult = 1
+      end
+      log_info "Elapsed milliseconds: #{((DateTime.now-lBeginTime)*86400000).to_i}"
+
+      return rResult
+    end
+
+    private
+
+    # Split parameters, before and after the first -- encountered
+    #
+    # Parameters::
+    # * *iParameters* (<em>list<String></em>): The parameters
+    # Return::
+    # * <em>list<String></em>: The first part
+    # * <em>list<String></em>: The second part
+    def splitParameters(iParameters)
+      rFirstPart = iParameters
+      rSecondPart = []
+
+      lIdxSeparator = iParameters.index('--')
+      if (lIdxSeparator != nil)
+        if (lIdxSeparator == 0)
+          rFirstPart = []
+        else
+          rFirstPart = iParameters[0..lIdxSeparator-1]
+        end
+        if (lIdxSeparator == iParameters.size-1)
+          rSecondPart = []
+        else
+          rSecondPart = iParameters[lIdxSeparator+1..-1]
+        end
+      end
+
+      return rFirstPart, rSecondPart
+    end
+
+    # Store a map of variable names and their corresponding values as instance variables of a given class
+    #
+    # Parameters::
+    # * *ioObject* (_Object_): Object where we want to instantiate those variables
+    # * *iVars* (<em>map<Symbol,Object></em>): The map of variables and their values
+    def instantiateVars(ioObject, iVars)
+      iVars.each do |iVariable, iValue|
+        ioObject.instance_variable_set("@#{iVariable}".to_sym, iValue)
+      end
+    end
+
+  end
+
+end

data/lib/WSK/Maps.rb

@@ -0,0 +1,29 @@
+#--
+# Copyright (c) 2009 - 2012 Muriel Salvan (muriel@x-aeon.com)
+# Licensed under the terms specified in LICENSE file. No warranty is provided.
+#++
+
+module WSK
+
+  module Maps
+
+    # Apply map functions to an input data, writing into an output data
+    #
+    # Parameters::
+    # * *iInputData* (<em>WSK::Model::InputData</em>): The input data
+    # * *oOutputData* (_Object_): The output data to fill
+    # * *iFunctions* (<em>list<map<Symbol,Object>></em>): The functions to apply, per channel
+    def apply_map_functions(iInputData, oOutputData, iFunctions)
+      require 'WSK/ArithmUtils/ArithmUtils'
+      lArithmUtils = ArithmUtils::ArithmUtils.new
+      # Create the map corresponding to the functions
+      lMap = lArithmUtils.createMapFromFunctions(iInputData.Header.NbrBitsPerSample, iFunctions)
+      # Apply the map
+      iInputData.each_raw_buffer do |iInputRawBuffer, iNbrSamples, iNbrChannels|
+        oOutputData.pushRawBuffer(lArithmUtils.applyMap(lMap, iInputRawBuffer, iInputData.Header.NbrBitsPerSample, iNbrSamples))
+      end
+    end
+
+  end
+
+end

data/lib/WSK/Model/CachedBufferReader.rb

@@ -0,0 +1,151 @@
+#--
+# Copyright (c) 2009 - 2012 Muriel Salvan (muriel@x-aeon.com)
+# Licensed under the terms specified in LICENSE file. No warranty is provided.
+#++
+
+module WSK
+
+  module Model
+
+    # Class to be inherited to define the following virtual methods:
+    # * read_buffer(iIdxStart, iIdxEnd) -> Buffer
+    # * extract_sub_buffer(iBuffer, iIdxStart, iIdxEnd) -> Buffer
+    # * get_nbr_samples_per_buffer -> Integer (number of samples in 1 buffer)
+    # * get_nbr_samples -> Integer (total number of samples)
+    class CachedBufferReader
+
+      # Constructor
+      def initialize
+        @NbrSamples = get_nbr_samples
+        @NbrSamplesPerBuffer = get_nbr_samples_per_buffer
+        # The position of the first sample of the buffer
+        # Integer
+        @IdxStartBufferSample = nil
+        # The position of the last sample of the buffer
+        # Integer
+        @IdxEndBufferSample = nil
+        # The buffer itself
+        @Buffer = nil
+      end
+
+      # Iterate through the buffers.
+      #
+      # Parameters::
+      # * *iIdxStartSample* (_Integer_): Index of the first sample to begin with [optional = 0]
+      # * *iIdxEndSample* (_Integer_): Index of the last sample to end with [optional = @NbrSamples-1]
+      # * *iOptions* (<em>map<Symbol,Object></em>): Additional options [optional = {}]:
+      #   * *:nbr_samples_prefetch* (_Integer_): Specify a number of samples to effectively read if the data needs to be accessed. This number will always be minored by the number of samples to read and majored by the number of samples per buffer. [optional = 0]
+      # * *CodeBlock*: The code called for each iteration:
+      #   * *iBuffer* (_String_): The buffer
+      #   * *iNbrSamples* (_Integer_): The number of samples in this buffer
+      def each_buffer(iIdxStartSample = 0, iIdxEndSample = @NbrSamples-1, iOptions = {})
+        lNbrSamplesPrefetch = iOptions[:nbr_samples_prefetch]
+        if (lNbrSamplesPrefetch == nil)
+          lNbrSamplesPrefetch = 0
+        end
+        lIdxFirstSample = iIdxStartSample
+        while (lIdxFirstSample <= iIdxEndSample)
+          lIdxLastSample = lIdxFirstSample+@NbrSamplesPerBuffer
+          if (lIdxLastSample > iIdxEndSample)
+            lIdxLastSample = iIdxEndSample
+          end
+          # Compute the last sample to prefetch
+          lIdxLastSamplePrefetch = lIdxFirstSample + lNbrSamplesPrefetch
+          if (lIdxLastSamplePrefetch < lIdxLastSample)
+            lIdxLastSamplePrefetch = lIdxLastSample
+          elsif (lIdxLastSamplePrefetch > lIdxFirstSample+@NbrSamplesPerBuffer)
+            lIdxLastSamplePrefetch = lIdxFirstSample+@NbrSamplesPerBuffer
+          end
+          prepare_buffer(lIdxFirstSample, lIdxLastSample, lIdxFirstSample, lIdxLastSamplePrefetch)
+          # Check if we need to return a sub-copy of the buffer
+          lBuffer = []
+          if ((lIdxFirstSample == @IdxStartBufferSample) and
+              (lIdxLastSample == @IdxEndBufferSample))
+            lBuffer = @Buffer
+          else
+            lBuffer = extract_sub_buffer(@Buffer, lIdxFirstSample - @IdxStartBufferSample, lIdxLastSample - @IdxStartBufferSample)
+          end
+          # Call client code
+          yield(lBuffer, lIdxLastSample - lIdxFirstSample + 1)
+          lIdxFirstSample = lIdxLastSample+1
+        end
+      end
+
+      # Iterate through the buffers in reverse order.
+      #
+      # Parameters::
+      # * *iIdxStartSample* (_Integer_): Index of the first sample to begin with [optional = 0]
+      # * *iIdxEndSample* (_Integer_): Index of the last sample to end with [optional = @NbrSamples-1]
+      # * *iOptions* (<em>map<Symbol,Object></em>): Additional options [optional = {}]:
+      #   * *:nbr_samples_prefetch* (_Integer_): Specify a number of samples to effectively read if the data needs to be accessed. This number will always be minored by the number of samples to read and majored by the number of samples per buffer. [optional = 0]
+      # * *CodeBlock*: The code called for each iteration:
+      #   * *iBuffer* (_String_): The buffer
+      #   * *iNbrSamples* (_Integer_): The number of samples in this buffer
+      def each_reverse_buffer(iIdxStartSample = 0, iIdxEndSample = @NbrSamples-1, iOptions = {})
+        lNbrSamplesPrefetch = iOptions[:nbr_samples_prefetch]
+        if (lNbrSamplesPrefetch == nil)
+          lNbrSamplesPrefetch = 0
+        end
+        lIdxLastSample = iIdxEndSample
+        while (lIdxLastSample >= iIdxStartSample)
+          lIdxFirstSample = lIdxLastSample-@NbrSamplesPerBuffer
+          if (lIdxFirstSample < iIdxStartSample)
+            lIdxFirstSample = iIdxStartSample
+          end
+          # Compute the first sample to prefetch
+          lIdxFirstSamplePrefetch = lIdxLastSample - lNbrSamplesPrefetch
+          if (lIdxFirstSamplePrefetch > lIdxFirstSample)
+            lIdxFirstSamplePrefetch = lIdxFirstSample
+          elsif (lIdxFirstSamplePrefetch < lIdxLastSample-@NbrSamplesPerBuffer)
+            lIdxFirstSamplePrefetch = lIdxLastSample-@NbrSamplesPerBuffer
+          end
+          prepare_buffer(lIdxFirstSample, lIdxLastSample, lIdxFirstSamplePrefetch, lIdxLastSample)
+          # Check if we need to return a sub-copy of the buffer
+          lBuffer = []
+          if ((lIdxFirstSample == @IdxStartBufferSample) and
+              (lIdxLastSample == @IdxEndBufferSample))
+            lBuffer = @Buffer
+          else
+            lBuffer = extract_sub_buffer(@Buffer, lIdxFirstSample - @IdxStartBufferSample, lIdxLastSample - @IdxStartBufferSample)
+          end
+          # Call client code
+          yield(lBuffer, lIdxLastSample - lIdxFirstSample + 1)
+          lIdxLastSample = lIdxFirstSample-1
+        end
+      end
+
+      # Ensure that a given samples range is loaded in the buffer.
+      # Use the caching mechanism if needed.
+      # The buffer might contain more samples than desired.
+      #
+      # Parameters::
+      # * *iIdxStartSample* (_Integer_): Index of the first sample to begin with [optional = 0]
+      # * *iIdxEndSample* (_Integer_): Index of the last sample to end with [optional = @NbrSamples-1]
+      # * *iIdxStartSamplePrefetch* (_Integer_): Specify the first sample to effectively read if the data needs to be accessed. [optional = iIdxStartSample]
+      # * *iIdxEndSamplePrefetch* (_Integer_): Specify the last sample to effectively read if the data needs to be accessed. [optional = iIdxEndSample]
+      def prepare_buffer(iIdxStartSample, iIdxEndSample, iIdxStartSamplePrefetch = iIdxStartSample, iIdxEndSamplePrefetch = iIdxEndSample)
+        if ((@Buffer == nil) or
+            (iIdxStartSample < @IdxStartBufferSample) or
+            (iIdxEndSample > @IdxEndBufferSample))
+          # Read all from the data
+          @Buffer = read_buffer(iIdxStartSamplePrefetch, iIdxEndSamplePrefetch)
+          @IdxStartBufferSample = iIdxStartSamplePrefetch
+          @IdxEndBufferSample = iIdxEndSamplePrefetch
+        end
+      end
+
+      # Get the current buffer
+      #
+      # Return::
+      # * _Object_: The current buffer
+      # * _Integer_: The first sample of the buffer
+      # * _Integer_: The last sample of the buffer
+      def get_current_buffer
+        return @Buffer, @IdxStartBufferSample, @IdxEndBufferSample
+      end
+
+    end
+
+  end
+
+end

data/lib/WSK/Model/Header.rb

@@ -0,0 +1,133 @@
+#--
+# Copyright (c) 2009 - 2012 Muriel Salvan (muriel@x-aeon.com)
+# Licensed under the terms specified in LICENSE file. No warranty is provided.
+#++
+
+module WSK
+
+  module Model
+
+    class Header
+
+      # Audio format
+      # PCM = 1 (i.e. Linear quantization)
+      # Values other than 1 indicate some form of compression.
+      #   Integer
+      attr_reader :AudioFormat
+
+      # Number of channels
+      #   Integer
+      attr_reader :NbrChannels
+
+      # Sample Rate
+      #   Integer
+      attr_reader :SampleRate
+
+      # Bits per sample (per channel)
+      #   Integer
+      attr_reader :NbrBitsPerSample
+
+      # Constructor
+      #
+      # Parameters::
+      # * *iAudioFormat* (_Integer_): Audio format
+      # * *iNbrChannels* (_Integer_): Number of channels
+      # * *iSampleRate* (_Integer_): Sample rate
+      # * *iNbrBitsPerSample* (_Integer_): Number of bits per channel's sample
+      def initialize(iAudioFormat, iNbrChannels, iSampleRate, iNbrBitsPerSample)
+        @AudioFormat, @NbrChannels, @SampleRate, @NbrBitsPerSample = iAudioFormat, iNbrChannels, iSampleRate, iNbrBitsPerSample
+        # The pack/unpack formula to use
+        lStrChannelPackFormula = ''
+        case @NbrBitsPerSample
+        when 8
+          lStrChannelPackFormula = 'C'
+        when 16
+          lStrChannelPackFormula = 's'
+        when 24
+          lStrChannelPackFormula = 'Cs'
+        when 32
+          lStrChannelPackFormula = 'l'
+        else
+          raise RuntimeError.new("#{@NbrBitsPerSample} bits PCM data not supported.")
+        end
+        @StrSamplePackFormula = lStrChannelPackFormula*@NbrChannels
+      end
+
+      # Get decoded samples from an encoded PCM string.
+      #
+      # Parameters::
+      # * *iEncodedString* (_String_): The encoded string
+      # * *iNbrSamplesToDecode* (_String_): Number of samples to decode
+      # Return::
+      # * <em>list<Integer></em>: The list of samples (there will be iNbrSamplesToDecode*@NbrChannels values)
+      def getDecodedSamples(iEncodedString, iNbrSamplesToDecode)
+        rSamples = iEncodedString.unpack(@StrSamplePackFormula*iNbrSamplesToDecode)
+
+        if (@NbrBitsPerSample == 8)
+          # Values are read unsigned. Shift them.
+          rSamples.map! do |iChannelValue|
+            next iChannelValue-128
+          end
+        elsif (@NbrBitsPerSample == 24)
+          # Each channel value has been decoded into 2 integers. We have to sum them.
+          lRealSamples = []
+          (iNbrSamplesToDecode*@NbrChannels).times do |iIdxChannelSample|
+            lIdxSamples = iIdxChannelSample*2
+            lRealSamples[iIdxChannelSample] = rSamples[lIdxSamples] + rSamples[lIdxSamples+1] * 256
+          end
+          rSamples = lRealSamples
+        end
+
+        return rSamples
+      end
+
+      # Get encoded PCM string from decoded samples
+      #
+      # Parameters::
+      # * *iChannelSamples* (<em>list<Integer></em>): The list of samples to encode
+      # Return::
+      # * _String_: Encoded PCM samples
+      def getEncodedString(iChannelSamples)
+        lRealChannelSamples = nil
+        if (@NbrBitsPerSample == 8)
+          # Values have to be stored unsigned. Shift them.
+          lRealChannelSamples = []
+          iChannelSamples.each do |iChannelValue|
+            lRealChannelSamples << iChannelValue+128
+          end
+        elsif (@NbrBitsPerSample == 24)
+          # Each channel must be split into 2 integer values before encoding.
+          lRealChannelSamples = []
+          iChannelSamples.size.times do |iIdxChannelSample|
+            lIdxReal = iIdxChannelSample*2
+            lRealChannelSamples[lIdxReal] = iChannelSamples[iIdxChannelSample] & 255
+            lRealChannelSamples[lIdxReal+1] = iChannelSamples[iIdxChannelSample] / 256
+          end
+        else
+          lRealChannelSamples = iChannelSamples
+        end
+
+        return lRealChannelSamples.pack(@StrSamplePackFormula*(iChannelSamples.size/@NbrChannels))
+      end
+
+      # Compare with a different object
+      #
+      # Parameters::
+      # * *iOther* (_Object_): Another object
+      # Return::
+      # * _Boolean_: Are the objects equal ?
+      def ==(iOther)
+        return ((iOther.object_id == self.object_id) or
+                ((iOther.is_a?(WSK::Model::Header)) and
+                 (iOther.AudioFormat == @AudioFormat) and
+                 (iOther.NbrChannels == @NbrChannels) and
+                 (iOther.SampleRate == @SampleRate) and
+                 (iOther.NbrBitsPerSample == @NbrBitsPerSample)))
+
+      end
+
+    end
+
+  end
+
+end