fmod 0.9.0

data/lib/fmod/effects/normalize.rb

@@ -0,0 +1,47 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit normalizes or amplifies the sound to a certain level.
+    #
+    # Normalize amplifies the sound based on the maximum peaks within the
+    # signal.
+    #
+    # For example if the maximum peaks in the signal were 50% of the bandwidth,
+    # it would scale the whole sound by 2.
+    #
+    # The lower threshold value makes the normalizer ignores peaks below a
+    # certain point, to avoid over-amplification if a loud signal suddenly came
+    # in, and also to avoid amplifying to maximum things like background hiss.
+    #
+    # Because FMOD is a realtime audio processor, it doesn't have the luxury of
+    # knowing the peak for the whole sound (ie it can't see into the future), so
+    # it has to process data as it comes in.
+    #
+    #
+    # To avoid very sudden changes in volume level based on small samples of new
+    # data, fmod fades towards the desired amplification which makes for smooth
+    # gain control. The fade-time parameter can control this.
+    #
+    # @attr fade_time [Float] Time to ramp the silence to full in ms.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 20000.0
+    #   * *Default:* 5000.0
+    # @attr threshold [Float] Lower volume range threshold to ignore. Raise
+    #   higher to stop amplification of very quiet signals.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    #   * *Default:* 0.1
+    # @attr max_amp [Float] Maximum amplification allowed. Higher values allow
+    #   more boost.
+    #   * *Minimum:* 1.0 (no amplification)
+    #   * *Maximum:* 100000.0
+    #   * *Default:* 20.0
+    class Normalize < Dsp
+      float_param(0, :fade_time, min: 0.0, max: 20000.0)
+      float_param(1, :threshold, min: 0.0, max: 1.0)
+      float_param(2, :max_amp, min: 1.0, max: 100000.0)
+    end
+  end
+end

data/lib/fmod/effects/object_pan.rb

@@ -0,0 +1,62 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit sends the signal to a 3d object encoder like Dolby Atmos.
+    # Supports a subset of the {DspType::PAN} parameters.
+    #
+    # 3D Object panners are meant for hardware 3d object systems like Dolby
+    # Atmos or Sony Morpheus. These object panners take input in, and send it to
+    # the 7.1 bed, but do not send the signal further down the DSP chain (the
+    # output of the dsp is silence).
+    #
+    # @attr position [Pointer|String] 3D Position
+    # @attr rolloff [Integer] 3D Rolloff
+    #   * *Minimum:* 0
+    #   * *Maximum:* 4
+    #   * *Default:* 0 (linear-squared)
+    #   @see Pan::ROLLOFF_LINEAR_SQUARED
+    #   @see Pan::ROLLOFF_LINEAR
+    #   @see Pan::ROLLOFF_INVERSE
+    #   @see Pan::ROLLOFF_INVERSE_TAPERED
+    #   @see Pan::ROLLOFF_CUSTOM
+    # @attr min_distance [Float] 3D Min Distance
+    #   * *Minimum:* 0.0
+    #   * *Default:* 1.0
+    # @attr max_distance [Float] 3D Max Distance
+    #   * *Minimum:* 0.0
+    #   * *Default:* 1.0
+    # @attr extent_mode [Integer] 3D Extent Mode
+    #   * *Minimum:* 0 (auto)
+    #   * *Maximum:* 2 (off)
+    #   * *Default:* 0 (auto)
+    #   @see Pan::EXTENT_AUTO
+    #   @see Pan::EXTENT_USER
+    #   @see Pan::EXTENT_OFF
+    # @attr sound_size [Float] 3D Sound Size
+    #   * *Minimum:* 0.0
+    #   * *Default:* 0.0
+    # @attr min_extent [Float] 3D Min Extent (degrees)
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 360.0
+    #   * *Default:* 0.0
+    # @attr overall_gain [Pointer|String] Overall gain. For information only,
+    #   not set by user. Allows FMOD to know the DSP is scaling the signal for
+    #   virtualization purposes.
+    # @attr output_gain [Float] Output gain level, linear scale. For the user to
+    #   scale the output of the object panner's signal.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    class ObjectPan < Dsp
+      data_param(0, :position)
+      integer_param(1, :rolloff, min: 0, max: 4)
+      float_param(2, :min_distance, min: 0.0)
+      float_param(3, :max_distance, min: 0.0)
+      integer_param(4, :extent_mode, min: 0, max: 2)
+      float_param(5, :sound_size, min: 0.0)
+      float_param(6, :min_extent, min: 0.0, max: 360.0)
+      data_param(7, :overall_gain)
+      float_param(8, :output_gain, min: 0.0, max: 20.0)
+    end
+  end
+end

data/lib/fmod/effects/oscillator.rb

@@ -0,0 +1,52 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit generates sine/square/saw/triangle or noise tones.
+    #
+    # @attr waveform [Integer] Waveform type.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 5
+    #   * *Default:* 0 (sine)
+    #   @see SINE
+    #   @see SQUARE
+    #   @see SAW_UP
+    #   @see SAW_DOWN
+    #   @see TRIANGLE
+    #   @see NOISE
+    # @attr rate [Float] Frequency of the sine-wave in Hz.
+    #   * *Minimum:* 1.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 220.0
+    class Oscillator < Dsp
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      SINE = 0
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      SQUARE = 1
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      SAW_UP = 2
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      SAW_DOWN = 3
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      TRIANGLE = 4
+
+      ##
+      # Strongly-typed waveform shape for {#waveform} parameter.
+      NOISE = 5
+
+      integer_param(0, :waveform, min: 0, max: 5)
+      float_param(1, :rate, min: 1.0, max: 22000.0)
+    end
+  end
+end

data/lib/fmod/effects/pan.rb

@@ -0,0 +1,166 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit pans the signal, possibly up-mixing or down-mixing as well.
+    #
+    # @attr panning_mode [Integer] Panner mode.
+    #   * *0:* Mono down-mix
+    #   * *1:* Stereo panning
+    #   * *2:* Surround panning
+    # @attr stereo_position [Float] 2D Stereo pan position.
+    #   * *Minimum:* -100.0
+    #   * *Maximum:* 100.0
+    #   * *Default:* 0.0
+    # @attr surround_direction [Float] 2D Surround pan direction. Direction from
+    #   center point of panning circle, in degrees.
+    #   * *Minimum:* -180.0 (rear-speakers center point)
+    #   * *Maximum:* 180.0 (rear-speakers center point)
+    #   * *Default:* 0.0 (front-center)
+    # @attr surround_extent [Float] 2D Surround pan extent. Distance from center
+    #   point of panning circle, in degrees.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 360.0
+    #   * *Default:* 360.0
+    # @attr surround_rotation [Float] 2D Surround pan rotation.
+    #   * *Minimum:* -180.0 (degrees)
+    #   * *Maximum:* 180.0 (degrees)
+    #   * *Default:* 0.0
+    # @attr surround_lfe_level [Float] 2D Surround pan LFE level. 2D LFE level
+    #   in dB.
+    #   * *Minimum:* -80.0
+    #   * *Maximum:* 20.0
+    #   * *Default:* 0.0
+    # @attr stereo_surround [Integer] Stereo-to-surround mode.
+    #   * *0:* Distributed
+    #   * *1:* Discrete (default)
+    # @attr surround_stereo_separation [Float] Stereo-To-Surround Stereo (only
+    #   for {#stereo_surround}) "discrete" mode). Separation/width of L/R parts
+    #   of stereo sound, in degrees.
+    #   * *Minimum:* -180.0
+    #   * *Maximum:* 180.0
+    #   * *Default:* 60.0
+    # @attr surround_stereo_axis [Float] Stereo-To-Surround Stereo (only for
+    #   {#stereo_surround}) "discrete" mode). Axis/rotation of L/R parts of
+    #   stereo sound, in degrees.
+    #   * *Minimum:* -180.0
+    #   * *Maximum:* 180.0
+    #   * *Default:* 0.0
+    # @attr surround_speakers [Integer] Speakers Enabled. Bit-mask for each
+    #   speaker from 0 to 32 to be considered by panner. Use to disable speakers
+    #   from being panned to.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 0xFFF
+    #   * *Default:* 0xFFF (all on)
+    # @attr position [Pointer|String] 3D Position.
+    # @attr rolloff [Integer] 3D Rolloff.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 4
+    #   * *Default:* 0 (linear-squared)
+    #   @see ROLLOFF_LINEAR_SQUARED
+    #   @see ROLLOFF_LINEAR
+    #   @see ROLLOFF_INVERSE
+    #   @see ROLLOFF_INVERSE_TAPERED
+    #   @see ROLLOFF_CUSTOM
+    # @attr min_distance [Float] 3D Min Distance.
+    #   * *Minimum:* 0.0
+    #   * *Default:* 1.0
+    # @attr max_distance [Float] 3D Max Distance.
+    #   * *Minimum:* 0.0
+    #   * *Default:* 20.0
+    # @attr extent_mode [Integer] 3D Extent Mode.
+    #   * *Minimum:* 0 (auto)
+    #   * *Maximum:* 2 (off)
+    #   * *Default:* 0 (auto)
+    #   @see EXTENT_AUTO
+    #   @see EXTENT_USER
+    #   @see EXTENT_OFF
+    # @attr sound_size [Float] 3D Sound Size.
+    #   * *Minimum:* 0.0
+    #   * *Default:* 0.0
+    # @attr min_extent [Float] 3D Min Extent.
+    #   * *Minimum:* 0.0 (degrees)
+    #   * *Maximum:* 360.0 (degrees)
+    #   * *Default:* 0.0
+    # @attr pan_blend [Float] 3D Pan Blend.
+    #   * *Minimum:* 0.0 (fully 2D)
+    #   * *Maximum:* 1.0 (fully 3D)
+    #   * *Default:* 0.0
+    # @attr lfe_upmix_enabled [Integer] LFE Up-mix Enabled. Determines whether
+    #   non-LFE source channels should mix to the LFE or leave it alone.
+    #   * *Minimum:* 0 (off)
+    #   * *Maximum:* 1 (on)
+    #   * *Default:* 0 (off)
+    # @attr overall_gain [Pointer] Overall gain. For information only,
+    #   not set by user. Data to provide to FMOD, to allow FMOD to know the DSP
+    #   is scaling the signal for virtualization purposes.
+    # @attr speaker_mode [Integer] Surround speaker mode. Target speaker mode
+    #   for surround panning.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 9
+    #   * *Default:* {SpeakerMode::DEFAULT}
+    #   @see SpeakerMode
+    # @attr height_blend [Float] 2D Height blend. When the input or
+    #   {#speaker_mode} has height speakers, control the blend between ground
+    #   and height.
+    #   * *Minimum:* -1.0 (push top speakers to ground)
+    #   * *Maximum:* 1.0 (push ground speakers to top)
+    #   * *Default:* 0.0 (preserve top / ground separation)
+    class Pan < Dsp
+      integer_param(0, :panning_mode, min: 0, max: 2)
+      float_param(1, :stereo_position, min: -100.0, max: 100.0)
+      float_param(2, :surround_direction, min: -180.0, max: 180.0)
+      float_param(3, :surround_extent, min: 0.0, max: 360.0)
+      float_param(4, :surround_rotation, min: -180.0, max: 180.0)
+      float_param(5, :surround_lfe_level, min: -80.0, max: 20.0)
+      integer_param(6, :stereo_surround, min: 0, max: 1)
+      float_param(7, :surround_stereo_separation, min: -180.0, max: 180.0)
+      float_param(8, :surround_stereo_axis, min: -180.0, max: 180.0)
+      integer_param(9, :surround_speakers, min: 0, max: 4095)
+      data_param(10, :position)
+      integer_param(11, :rolloff, min: 0, max: 4)
+      float_param(12, :min_distance, min: 0.0)
+      float_param(13, :max_distance, min: 0.0)
+      integer_param(14, :extent_mode, min: 0, max: 2)
+      float_param(15, :sound_size, min: 0.0)
+      float_param(16, :min_extent, min: 0.0, max: 360.0)
+      float_param(17, :pan_blend, min: 0.0, max: 1.0)
+      integer_param(18, :lfe_upmix_enabled, min: 0, max: 1)
+      data_param(19, :overall_gain)
+      integer_param(20, :speaker_mode, min: 0, max: 8)
+      float_param(21, :height_blend, min: -1.0, max: 1.0)
+
+      ##
+      # Strongly-typed value used with {#extent_mode}.
+      EXTENT_AUTO = 0
+
+      ##
+      # Strongly-typed value used with {#extent_mode}.
+      EXTENT_USER = 1
+
+      ##
+      # Strongly-typed value used with {#extent_mode}.
+      EXTENT_OFF = 2
+
+      ##
+      # Strongly typed 3D rolloff value used with {#rolloff}.
+      ROLLOFF_LINEAR_SQUARED = 0
+
+      ##
+      # Strongly typed 3D rolloff value used with {#rolloff}.
+      ROLLOFF_LINEAR = 1
+
+      ##
+      # Strongly typed 3D rolloff value used with {#rolloff}.
+      ROLLOFF_INVERSE = 2
+
+      ##
+      # Strongly typed 3D rolloff value used with {#rolloff}.
+      ROLLOFF_INVERSE_TAPERED = 3
+
+      ##
+      # Strongly typed 3D rolloff value used with {#rolloff}.
+      ROLLOFF_CUSTOM = 4
+    end
+  end
+end

data/lib/fmod/effects/param_eq.rb

@@ -0,0 +1,36 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # @deprecated Will be removed in a future FMOD version. See {MultibandEq}
+    #   for alternatives.
+    #
+    # This unit attenuates or amplifies a selected frequency range.
+    #
+    # Parametric EQ is a single band peaking EQ filter that attenuates or
+    # amplifies a selected frequency and its neighbouring frequencies.
+    #
+    # When a frequency has its gain set to 1.0, the sound will be unaffected and
+    # represents the original signal exactly.
+    #
+    # @attr center [Float] Frequency center.
+    #   * *Minimum:* 20.0
+    #   * *Maximum:* 22000.0
+    #   * *Default:* 8000.0
+    # @attr bandwidth [Float] Octave range around the center frequency to
+    #   filter.
+    #   * *Minimum:* 0.2
+    #   * *Maximum:* 5.0
+    #   * *Default:* 1.0
+    # @attr gain [Float] Frequency gain in dB.
+    #   * *Minimum:* -30.0
+    #   * *Maximum:* 30.0
+    #   * *Default:* 0.0
+    class ParamEq < Dsp
+      float_param(0, :center, min: 20.0, max: 22000.0)
+      float_param(1, :bandwidth, min: 0.2, max: 5.0)
+      float_param(2, :gain, min: -30.0, max: 30.0)
+    end
+  end
+end

data/lib/fmod/effects/pitch_shift.rb

@@ -0,0 +1,47 @@
+module FMOD
+  module Effects
+
+    ##
+    # This unit bends the pitch of a sound without changing the speed of playback.
+    #
+    # This pitch shifting unit can be used to change the pitch of a sound
+    # without speeding it up or slowing it down.
+    #
+    # It can also be used for time stretching or scaling, for example if the
+    # pitch was doubled, and the frequency of the sound was halved, the pitch of
+    # the sound would sound correct but it would be twice as slow.
+    #
+    # @note This filter is very computationally expensive! Similar to a vocoder,
+    #   it requires several overlapping FFT and IFFT's to produce smooth output,
+    #   and can require around 440mhz for 1 stereo 48khz signal using the
+    #   default settings.
+    #
+    #   Reducing the signal to mono will half the CPU usage.
+    #
+    #   Reducing this will lower audio quality, but what settings to use are
+    #   largely dependant on the sound being played. A noisy polyphonic signal
+    #   will need higher FFT size compared to a speaking voice for example.
+    #
+    # @attr pitch [Float] Pitch value.
+    #   * *Minimum:* 0.5 (one octave lower)
+    #   * *Maximum:* 2.0 (one octave higher)
+    #   * *Default:* 1.0 (normal)
+    # @attr window_size [Float] FFT window size. Increase this to reduce
+    #   "smearing". This effect is a warbling sound similar to when an MP3 is
+    #   encoded at very low bit-rates.
+    #   * *Minimum:* 256
+    #   * *Maximum:* 4096
+    #   * *Default:* 1024
+    #   * *Valid:* 256, 512, 1024, 2048, 4096
+    # @attr max_channels [Float] Maximum channels supported. 0 = same
+    #   as FMOD's default output polyphony, 1 = mono, 2 = stereo etc.
+    #   * *Minimum:* 0
+    #   * *Maximum:* 16
+    #   * *Default:* 0 (strongly recommended to leave at 0!)
+    class PitchShift < Dsp
+      float_param(0, :pitch, min: 0.5, max: 2.0)
+      float_param(1, :window_size, min: 256, max: 4096)
+      float_param(3, :max_channels, min: 0, max: 16)
+    end
+  end
+end

data/lib/fmod/effects/return.rb

@@ -0,0 +1,18 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit receives signals from a number of send DSPs.
+    #
+    # @attr_reader id [Integer] ID of this Return DSP.
+    #   * *Default:* -1
+    # @attr speaker_mode [Integer] Input speaker mode of this return.
+    #   * *Default:* {SpeakerMode::DEFAULT}
+    #   @see SpeakerMode
+    class Return < Dsp
+      integer_param(0, :id, readonly: true)
+      integer_param(1, :speaker_mode, min: 0, max: 9)
+    end
+  end
+end

data/lib/fmod/effects/send.rb

@@ -0,0 +1,21 @@
+
+module FMOD
+  module Effects
+
+    ##
+    # This unit sends a copy of the signal to a return DSP anywhere in the DSP
+    # tree.
+    #
+    # @attr id [Integer] ID of the Return DSP this send is connected to (integer
+    #   values only).
+    #   * *Default:* -1 (indicates no connected {Return} DSP)
+    # @attr level [Float] Send level.
+    #   * *Minimum:* 0.0
+    #   * *Maximum:* 1.0
+    #   * *Default:* 1.0
+    class Send < Dsp
+      integer_param(0, :id, min: -1)
+      integer_param(1, :level, min: 0.0, max: 1.0)
+    end
+  end
+end