Package net.paulhertz.pixelaudio.sampler

Class PASamplerInstrument

java.lang.Object
net.paulhertz.pixelaudio.sampler.PASamplerInstrument
All Implemented Interfaces:
PAPlayable, PASamplerPlayable
public class PASamplerInstrument extends Object implements PASamplerPlayable
PASamplerInstrument Represents a playable instrument that uses a PASampler instantiated as a PASharedBufferSampler to trigger audio playback from a shared buffer that is (currently) a Minim MultiChannelBuffer. TODO decide if MultiChannelBuffer or float[] is the appropriate structure for storing the buffer. float[] is preferred for the general style of PixelAudio, but MultiChannelBuffer support is a useful consideration for the future. TODO sample accurate start for sampler events to unify timing API with PAGranularInstrument. Currently sampler play() is block-time accurate only. In the future, add sample-time scheduling (startAtSampleTime / startAfterDelaySamples) using AudioScheduler so sampler and granular share a transport model. Supports: - Global pitch scaling - Global stereo pan - Default ADSR envelope - Linear trim (gain) per instrument - Compensation for differing buffer vs. output sample rates - Cached buffer size for efficiency Implements both PAPlayable and PASamplerPlayable for full compatibility.

  • Field Details

    • sampler

      private final PASampler sampler

    • buffer

      private ddf.minim.MultiChannelBuffer buffer

    • out

      private final ddf.minim.AudioOutput out

    • bufferSize

      private int bufferSize

    • maxVoices

      private int maxVoices

    • bufferSampleRate

      private float bufferSampleRate

    • outputSampleRate

      private float outputSampleRate

    • sampleRateRatio

      private float sampleRateRatio

    • defaultEnv

      private ADSRParams defaultEnv

    • globalPitch

      private volatile float globalPitch

    • globalPan

      private float globalPan

    • gain

      private volatile float gain

    • parentGain

      private volatile float parentGain

    • isClosed

      private boolean isClosed

  • Constructor Details

    • PASamplerInstrument

      public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int maxVoices, ddf.minim.AudioOutput audioOut, ADSRParams env)
      Primary constructor for backward compatibility.
      Parameters:
      buffer - the shared MultiChannelBuffer
      sampleRate - nominal sample rate of the buffer (Hz)
      maxVoices - number of simultaneous voices (polyphony)
      audioOut - target AudioOutput
      env - default ADSR envelope parameters

    • PASamplerInstrument

      public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, PASampler sampler, ADSRParams defaultEnv, float bufferSampleRate)
      Full constructor with explicit buffer sample rate, custom sampler, and envelope.

    • PASamplerInstrument

      public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out)
      Convenience constructor assuming buffer and output share the same rate.

  • Method Details

    • play

      public int play(float amplitude, float pitch, float pan)
      Generic play() from PAPlayable, will play the entire buffer from the beginning of the buffer with specified pitch and pan and default envelope.
      Specified by:
      play in interface PAPlayable
      Parameters:
      amplitude - gain multiplier (0..1+)
      pitch - playback rate or pitch factor (implementation-defined)
      pan - stereo pan (-1 left .. +1 right)
      Returns:
      non-zero if a voice/event was triggered

    • play

      public int play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      The primary play method, called by all playSample() methods, from PASamplerPlayable interface.
      Specified by:
      play in interface PASamplerPlayable

    • stop

      public void stop()
      Stop playback (stop all active voices).
      Specified by:
      stop in interface PAPlayable

    • fadeToStop

      public void fadeToStop()
      Smoothly stop all active voices by triggering their envelope release. This is the preferred performance stop.

    • fadeOutAll

      public void fadeOutAll()
      Alias for fadeToStop(), useful when calling from UI or pool code.

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Trigger playback using all six standard per-voice parameters.
      Specified by:
      playSample in interface PASamplerPlayable
      Parameters:
      samplePos - start position (samples)
      sampleLen - playback length (samples)
      amplitude - per-voice amplitude
      env - ADSR envelope parameters
      pitch - playback rate (1.0 = normal)
      pan - stereo position (-1.0 = left, +1.0 = right)
      Returns:
      the actual length of the audio event, in samples

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)
      All params except the envelope, so we use the default envelope.
      Parameters:
      samplePos -
      sampleLen -
      amplitude -
      pitch -
      pan -
      Returns:
      the actual length of the audio event, in samples

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude)
      Convenience overload: uses default envelope, default pitch, and center pan.
      Specified by:
      playSample in interface PASamplerPlayable

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, float pitch)
      Convenience overload: uses default envelope, supplied pitch and center pan.
      Specified by:
      playSample in interface PASamplerPlayable

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)
      Plays a sample using a supplied envelope with default pitch and default pan.

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
      Plays a sample using a supplied envelope, pitch, and current global pan.

    • playSample

      public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and pan. For large buffers, there may be some latency.

    • playSample

      public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
      Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and default pan.

    • setGain

      public void setGain(float linear)

    • getGain

      public float getGain()

    • setGainDb

      public void setGainDb(float db)

    • getGainDb

      public float getGainDb()

    • setParentGain

      void setParentGain(float linear)

    • getParentGain

      float getParentGain()

    • syncMasterGain

      private void syncMasterGain()

    • setMixProfile

      public void setMixProfile(PASharedBufferSampler.MixProfile profile)
      Pass-through to the underlying PASharedBufferSampler mix behavior. This lets a host application tune density normalization / soft clipping without changing per-event gain or envelope settings.
      Parameters:
      profile - a PASharedBufferSampler mix profile

    • getMixProfile

      public PASharedBufferSampler.MixProfile getMixProfile()
      Returns:
      the current PASharedBufferSampler mix profile, or BALANCED if the sampler implementation is not PASharedBufferSampler.

    • cycleMixProfile

      public PASharedBufferSampler.MixProfile cycleMixProfile()
      Convenience: cycle to the next available sampler mix profile.
      Returns:
      the newly selected profile

    • hasAvailableVoice

      public boolean hasAvailableVoice()

    • hasActiveOrReleasingVoices

      public boolean hasActiveOrReleasingVoices()

    • activeOrReleasingVoiceCount

      public int activeOrReleasingVoiceCount()

    • releaseAllVoices

      public void releaseAllVoices()
      Smoothly release all active voices (used only if we must recycle an instrument).

    • getSampler

      public PASampler getSampler()

    • getBuffer

      public ddf.minim.MultiChannelBuffer getBuffer()

    • getBufferSize

      public int getBufferSize()

    • setBuffer

      public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer)
      Copy the data and settings in the provided MultiChannelBuffer to this.buffer; bufferSampleRate is unchanged. The sampler and its voices are also refreshed. Note that bufferSize will change if the buffers are not the same size.
      Parameters:
      newBuffer - buffer to replace the current buffer

    • setBuffer

      public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newSampleRate)
      Copy the data and settings of the provided MultiChannelBuffer to this.buffer and set bufferSampleRate. The sampler and its voices are also refreshed. Note that bufferSize will change if the buffers are not the same size.
      Parameters:
      newBuffer - buffer to replace the current buffer
      newSampleRate -

    • setBuffer

      public void setBuffer(float[] newBuffer, float newSampleRate)
      Replace the instrument's active buffer contents with a new signal array using MultiChannelBuffer.setChannel(0, newBuffer), which creates a copy of the supplied array, and set a new bufferSamplerRate. The sampler and its voices are also refreshed. Note that bufferSize will change if the this.buffer and newBuffer are not the same size. The instrument retains its own MultiChannelBuffer but updates its internal copy. The sampler and its voices also receive a fresh copy.

    • getAudioOutput

      public ddf.minim.AudioOutput getAudioOutput()

    • getBufferSampleRate

      public float getBufferSampleRate()

    • getOutputSampleRate

      public float getOutputSampleRate()

    • getSampleRateRatio

      public float getSampleRateRatio()

    • setBufferSampleRate

      public void setBufferSampleRate(float newRate)
      Update the buffer's intrinsic sample rate.
      Parameters:
      newRate - new sample rate for the buffer, affects playback rate

    • setOutputSampleRate

      public void setOutputSampleRate(float newRate)
      Update the output sample rate, for example, if audio device changes. This is unlikely to happen, but we'll be cautious.
      Parameters:
      newRate -

    • updateRateFromOutput

      public void updateRateFromOutput()
      Synchronize output sample rate from AudioOutput directly.

    • getDefaultEnv

      public ADSRParams getDefaultEnv()

    • setDefaultEnv

      public void setDefaultEnv(ADSRParams env)

    • setPitchScale

      public void setPitchScale(float scale)

    • getPitchScale

      public float getPitchScale()

    • setGlobalPan

      public void setGlobalPan(float pan)

    • getGlobalPan

      public float getGlobalPan()

    • clampPan

      private static float clampPan(float pan)

    • close

      public void close()
      Stop all voices and disconnect UGens from the output.