Package net.paulhertz.pixelaudio.granular

# Class PAGranularInstrument

java.lang.Object
net.paulhertz.pixelaudio.granular.PAGranularInstrument

public class PAGranularInstrument extends Object
PAGranularInstrument High-level granular instrument wrapper. Mirrors PASamplerInstrument but uses: PAGranularSampler → PAGranularVoice → PASource. Provides: - Global pan - Global gain scaling - Default ADSR envelope - Looping option for granular paths - Thread-safe play() methods Does NOT manage MultiChannelBuffer. PASource encapsulates its data. Now also exposes helpers to schedule playback at sample-accurate times via the underlying PAGranularSampler.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private ADSRParams`
  `defaultEnv`
  `private float`
  `globalGain`
  `private float`
  `globalPan`
  `private boolean`
  `isClosed`
  `private final ddf.minim.AudioOutput`
  `out`
  `private final PAGranularSampler`
  `sampler`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PAGranularInstrument(ddf.minim.AudioOutput out)`
  `PAGranularInstrument(ddf.minim.AudioOutput out, ADSRParams defaultEnv, int maxVoices)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancelAndReleaseAll()`
  `void`
  `cancelAndStopAll()`
  `private static float`
  `clampPan(float p)`
  `void`
  `clearScheduled()`
  `void`
  `close()`
  `ADSRParams`
  `getDefaultEnvelope()`
  `float`
  `getGlobalGain()`
  `float`
  `getGlobalGainDb()`
  `float`
  `getGlobalPan()`
  `long`
  `getSampleCursor()`
  `PAGranularSampler`
  `getSampler()`
  `float`
  `getSampleRate()`
  `long`
  `play(PASource src)`
  Convenience: default env and global pan.
  `long`
  `play(PASource src, float amp)`
  Convenience: default pan, default envelope.
  `long`
  `play(PASource src, float amp, float pan)`
  Convenience: uses default envelope, no looping.
  `long`
  `play(PASource src, float amp, float pan, ADSRParams env, boolean looping)`
  Main granular play() method.
  `long`
  `playLooping(PASource src, float amp, float pan)`
  Convenience: looping version.
  `void`
  `releaseAll()`
  `void`
  `setDefaultEnvelope(ADSRParams env)`
  `void`
  `setGlobalGain(float gLinear)`
  `void`
  `setGlobalGainDb(float gDb)`
  `void`
  `setGlobalPan(float pan)`
  `void`
  `startAfterDelaySamples(PASource src, float amp, float pan, ADSRParams env, boolean looping, long delaySamples)`
  Schedule playback after a delay in samples relative to "now".
  `void`
  `startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample)`
  Schedule playback of a PASource at an absolute sample time.
  `void`
  `startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)`
  Schedule playback of a PASource at an absolute sample time.
  `void`
  `startNow(PASource src, float amp, float pan, ADSRParams env, boolean looping)`
  Convenience: schedule using current instrument cursor as "now".
  `void`
  `stopAll()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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)

  - ### PAGranularInstrument

    public PAGranularInstrument(ddf.minim.AudioOutput out)

- ## Method Details

  - ### play

    public long play(PASource src, float amp, float pan, ADSRParams env, boolean looping)
    Main granular play() method. The PASource in the current Granular synthesis engine is expected to be a PABurstGranularSource passed in by PAGranularInstrumentDirector, the standard entry point for granular synthesis in the PixelAudio library. Earlier PASource classes such as BasicIndexGranularSource, PathGranularSource, etc., are deprecated.
    Parameters:
      `src` - PASource (PABurstGranularSource)
      `amp` - amplitude
      `pan` - stereo pan (-1..+1)
      `env` - envelope (or null → default)
      `looping` - loop the grain path
    Returns:
      voiceId or -1

  - ### play

    public long play(PASource src, float amp, float pan)
    Convenience: uses default envelope, no looping.

  - ### play

    public long play(PASource src, float amp)
    Convenience: default pan, default envelope.

  - ### play

    public long play(PASource src)
    Convenience: default env and global pan.

  - ### playLooping

    public long playLooping(PASource src, float amp, float pan)
    Convenience: looping version.

  - ### startAtSampleTime

    public void startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample)
    Schedule playback of a PASource at an absolute sample time.
    Parameters:
      `src` - PASource
      `amp` - amplitude
      `pan` - stereo pan
      `env` - envelope (or null → default)
      `looping` - loop flag
      `startSample` - absolute sample index at which to start

  - ### startAtSampleTime

    public void startAtSampleTime(PASource src, float amp, float pan, ADSRParams env, boolean looping, long startSample, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
    Schedule playback of a PASource at an absolute sample time. Called by PAGranularInstrumentDirector
    Parameters:
      `src` - PASource
      `amp` - amplitude
      `pan` - stereo pan
      `env` - envelope (or null → default)
      `looping` - loop flag
      `startSample` - absolute sample index at which to start
      `grainWindow` - a WindowFunction
      `grainLenSamples` - number of samples in one grain

  - ### startAfterDelaySamples

    public void startAfterDelaySamples(PASource src, float amp, float pan, ADSRParams env, boolean looping, long delaySamples)
    Schedule playback after a delay in samples relative to "now".
    Parameters:
      `src` - PASource
      `amp` - amplitude
      `pan` - stereo pan
      `env` - envelope (or null → default)
      `looping` - loop flag
      `delaySamples` - how many samples from "now"

  - ### startNow

    public void startNow(PASource src, float amp, float pan, ADSRParams env, boolean looping)
    Convenience: schedule using current instrument cursor as "now".
    Parameters:
      `src` - PASource
      `amp` - amplitude
      `pan` - pan
      `env` - envelope (or null → default)
      `looping` - loop flag

  - ### 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()

  - ### clearScheduled

    public void clearScheduled()

  - ### releaseAll

    public void releaseAll()

  - ### cancelAndStopAll

    public void cancelAndStopAll()

  - ### cancelAndReleaseAll

    public void cancelAndReleaseAll()

  - ### clampPan

    private static float clampPan(float p)