Package net.paulhertz.pixelaudio.granular

Class PAGranularInstrument

java.lang.Object
net.paulhertz.pixelaudio.granular.PAGranularInstrument
public class PAGranularInstrument extends Object
High-level granular instrument wrapper for PASource playback.

PAGranularInstrument is the instrument-level control surface in the granular synthesis chain. It applies global pan, global gain, and default envelope settings, then delegates voice allocation and sample-accurate scheduling to PAGranularSampler.

Most gesture-driven granular synthesis code should enter the chain through PAGranularInstrumentDirector, which creates the PABurstGranularSource instances and calls this class. Direct use of PAGranularInstrument is useful when callers already have a PASource and want immediate or scheduled playback.

This class does not manage Minim MultiChannelBuffer data. A PASource encapsulates its own audio data or rendering behavior.

See Also:

  • Field Details

    • sampler

      private final PAGranularSampler sampler

    • out

      private final ddf.minim.AudioOutput out

    • defaultEnv

      private ADSRParams defaultEnv

    • globalPan

      private float globalPan

    • globalGain

      private float globalGain

    • isClosed

      private boolean isClosed

  • Constructor Details

    • PAGranularInstrument

      public PAGranularInstrument(ddf.minim.AudioOutput out, ADSRParams defaultEnv, int maxVoices)
      Creates a granular instrument.
      Parameters:
      out - Minim audio output used by the sampler
      defaultEnv - default macro envelope for voices when a playback call supplies null
      maxVoices - maximum number of simultaneous granular voices

    • PAGranularInstrument

      public PAGranularInstrument(ddf.minim.AudioOutput out)
      Creates a granular instrument with a default envelope and 16 voices.
      Parameters:
      out - Minim audio output used by the sampler

  • Method Details

    • play

      public long play(PASource src, float amp, float pan, ADSRParams env, boolean looping)
      Plays a granular source immediately.

      The current gesture-driven granular engine normally supplies a PABurstGranularSource created by PAGranularInstrumentDirector. Other PASource implementations can be played directly if they satisfy the source rendering contract.

      Parameters:
      src - source to render
      amp - linear amplitude multiplier before global gain is applied
      pan - stereo pan offset in the range [-1, 1]
      env - envelope to use, or null to use the instrument default
      looping - true to loop the source path where supported
      Returns:
      voice id, or -1 if playback could not start

    • play

      public long play(PASource src, float amp, float pan)
      Convenience overload that uses the default envelope and disables looping.

    • play

      public long play(PASource src, float amp)
      Convenience overload that uses center pan and the default envelope.

    • play

      public long play(PASource src)
      Convenience overload that uses unity gain, global pan, and the default envelope.

    • playLooping

      public long playLooping(PASource src, float amp, float pan)
      Convenience overload that enables looping with the default envelope.

    • startAtSampleTime

      public void startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample)
      Schedules playback of a source at an absolute sample time.
      Parameters:
      src - source to render
      amp - linear amplitude multiplier before global gain is applied
      pan - stereo pan offset in the range [-1, 1]
      env - envelope to use, or null to use the instrument default
      looping - true to loop the source path where supported
      startSample - absolute sample index at which playback should start

    • startAtSampleTime

      public void startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
      Schedules playback of a source at an absolute sample time with grain-window settings.

      This overload is used by PAGranularInstrumentDirector so the resolved grain window and grain length can travel with a scheduled event into the sampler and voice.

      Parameters:
      src - source to render
      amp - linear amplitude multiplier before global gain is applied
      pan - stereo pan offset in the range [-1, 1]
      env - envelope to use, or null to use the instrument default
      looping - true to loop the source path where supported
      startSample - absolute sample index at which playback should start
      grainWindow - window function for shaping grain amplitude, or null for source default
      grainLenSamples - number of samples in one grain

    • startAfterDelaySamples

      public void startAfterDelaySamples(PASource src, float amp, float pan, ADSRParams env, boolean looping, long delaySamples)
      Schedules playback after a delay in samples relative to the current sampler time.
      Parameters:
      src - source to render
      amp - linear amplitude multiplier before global gain is applied
      pan - stereo pan offset in the range [-1, 1]
      env - envelope to use, or null to use the instrument default
      looping - true to loop the source path where supported
      delaySamples - delay from the current sample time

    • startNow

      public void startNow(PASource src, float amp, float pan, ADSRParams env, boolean looping)
      Schedules playback at the current instrument cursor.
      Parameters:
      src - source to render
      amp - linear amplitude multiplier before global gain is applied
      pan - stereo pan offset in the range [-1, 1]
      env - envelope to use, or null to use the instrument default
      looping - true to loop the source path where supported

    • stopAll

      public void stopAll()

    • setDefaultEnvelope

      public void setDefaultEnvelope(ADSRParams env)

    • getDefaultEnvelope

      public ADSRParams getDefaultEnvelope()

    • setGlobalPan

      public void setGlobalPan(float pan)

    • getGlobalPan

      public float getGlobalPan()

    • setGlobalGain

      public void setGlobalGain(float gLinear)

    • getGlobalGain

      public float getGlobalGain()

    • setGlobalGainDb

      public void setGlobalGainDb(float gDb)

    • getGlobalGainDb

      public float getGlobalGainDb()

    • getSampleRate

      public float getSampleRate()

    • getSampler

      public PAGranularSampler getSampler()

    • getSampleCursor

      public long getSampleCursor()

    • close

      public void close()
      Closes this instrument and stops all voices.

    • clearScheduled

      public void clearScheduled()
      Clears playback events that have been scheduled but have not started yet.

      Voices that are already active continue playing. For a musical stop, call this first and then call releaseAll().

    • releaseAll

      public void releaseAll()
      Releases all active or already-releasing voices through their envelopes.

      A release is generally less abrupt than a stop, because each active voice is allowed to pass through its envelope release stage. Scheduled events are not cleared by this method.

    • cancelAndStopAll

      public void cancelAndStopAll()
      Clears pending scheduled events and immediately stops all active voices.

      A stop halts voice processing directly and is therefore more abrupt than a release.

    • cancelAndReleaseAll

      public void cancelAndReleaseAll()
      Clears pending scheduled events and releases all active voices through their envelopes.

      This is the less abrupt counterpart to cancelAndStopAll() and is generally better suited to musical fade-outs.

    • activeOrReleasingVoiceCount

      public int activeOrReleasingVoiceCount()
      Counts active or releasing granular voices.
      Returns:
      active or releasing voice count

    • clampPan

      private static float clampPan(float p)