Package processing.sound

Class AudioSample

java.lang.Object
processing.sound.SoundObject
processing.sound.AudioSample
Direct Known Subclasses:
SoundFile
public class AudioSample extends SoundObject
This class allows you low-level access to an audio buffer to create, access, manipulate and play back sound samples. If you want to pre-load your audio sample with an audio file from disk you can do so using the SoundFile subclass.
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    AudioSample(PApplet parent, float[] data)
     
    AudioSample(PApplet parent, float[] data, boolean stereo)
     
    AudioSample(PApplet parent, float[] data, boolean stereo, int frameRate)
     
    AudioSample(PApplet parent, float[] data, int frameRate)
     
    AudioSample(PApplet parent, int frames)
     
    AudioSample(PApplet parent, int frames, boolean stereo)
     
    AudioSample(PApplet parent, int frames, boolean stereo, int frameRate)
    Allocate a new audiosample buffer with the given number of frames.
    AudioSample(PApplet parent, int frames, int frameRate)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    amp(float amp)
    Change the amplitude/volume of the player.
    int
    channels()
    Returns the number of channels in the audiosample as an int (1 for mono, 2 for stereo).
    void
    cue(float time)
    Cues the playhead to a fixed position in the audiosample.
    void
    cueFrame(int frameNumber)
    Cues the playhead to a fixed position in the audiosample.
    float
    duration()
    Returns the duration of the audiosample in seconds.
    int
    frames()
    Returns the number of frames of the audiosample as an int.
    boolean
    isPlaying()
    Check whether this audiosample is currently playing.
    void
    jump(float time)
    Jump to a specific position in the audiosample while continuing to play (or starting to play if it wasn't playing already).
    void
    jumpFrame(int frameNumber)
    Jump to a specific position in the audiosample without interrupting playback.
    void
    loop()
     
    void
    loop(float rate)
     
    void
    loop(float rate, float amp)
     
    void
    loop(float rate, float pos, float amp)
    Starts the playback of the audiosample.
    void
    loop(float rate, float pos, float amp, float add)
    Deprecated. 
    void
    pan(float pos)
    Pan the soundfile in a stereo panorama.
    void
    pause()
    Stop the playback of the sample, but cue it to the current position.
    float
    percent()
    Get current sound file playback position in percent.
    void
    play()
    Starts the generator
    void
    play(float rate)
     
    void
    play(float rate, float amp)
     
    void
    play(float rate, float pos, float amp)
     
    void
    play(float rate, float pos, float amp, float cue)
    Deprecated.
    void
    play(float rate, float pos, float amp, float add, float cue)
    Deprecated. 
    void
    playFor(float duration)
     
    void
    playFor(float duration, float cue)
    Starts the playback of the audiosample for the specified duration or to the end of the audiosample, whichever comes first.
    float
    position()
    Get current sound file playback position in seconds.
    int
    positionFrame()
    Get frame index of current sound file playback position.
    void
    rate(float rate)
    Set the relative playback rate of the audiosample.
    void
    read(float[] data)
    Get the current sample data and write it into the given array.
    float
    read(int frameIndex)
     
    void
    read(int startFrame, float[] data, int startIndex, int numFrames)
    The underlying data of the audiosample can be read and written in several different ways: the method taking a single float array `data` gets the current sample data and write it into the given array.
    float
    read(int frameIndex, int channelIndex)
     
    void
    resize(int frames)
     
    void
    resize(int frames, boolean stereo)
    Resizes the underlying buffer of the audiosample to the given number of frames.
    int
    sampleRate()
    Returns the underlying sample rate of the audiosample.
    void
    set(float rate, float pos, float amp)
    Set multiple parameters at once.
    void
    set(float rate, float pos, float amp, float add)
    Deprecated. 
    void
    stop()
    Stops the playback.
    void
    write(float[] data)
    Overwrite the sample with the data from the given array.
    void
    write(int index, float value)
     
    void
    write(int startFrame, float[] data, int startIndex, int numFrames)
    The underlying data of the audiosample can be read and (over)written in several different ways: the method taking a single float array `data` replaces the sample data with the content of the given array.

    Methods inherited from class processing.sound.SoundObject

    add, getUnitGenerator

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AudioSample

      public AudioSample(PApplet parent, int frames)

    • AudioSample

      public AudioSample(PApplet parent, int frames, boolean stereo)

    • AudioSample

      public AudioSample(PApplet parent, int frames, boolean stereo, int frameRate)
      Allocate a new audiosample buffer with the given number of frames.
      Parameters:
      parent - typically use "this"
      frames - the desired number of frames for this audiosample
      stereo - whether to treat the audiosample as 2-channel (stereo) or not (default: false)
      frameRate - the underlying frame rate of the sample (default: 44100)

    • AudioSample

      public AudioSample(PApplet parent, int frames, int frameRate)

    • AudioSample

      public AudioSample(PApplet parent, float[] data)
      Parameters:
      data - an array of float values to be used as this audiosample's sound data. The audiosample will consequently have as many frames as the length of the given array. To match the default amplitude of other sound generators, the sample values should be in the range [-0.5, 0.5]

    • AudioSample

      public AudioSample(PApplet parent, float[] data, boolean stereo)

    • AudioSample

      public AudioSample(PApplet parent, float[] data, int frameRate)

    • AudioSample

      public AudioSample(PApplet parent, float[] data, boolean stereo, int frameRate)

  • Method Details

    • isPlaying

      public boolean isPlaying()
      Check whether this audiosample is currently playing.
      Overrides:
      isPlaying in class SoundObject
      Returns:
      `true` if this sound object is currently playing, `false` if it is not.

    • amp

      public void amp(float amp)
      Change the amplitude/volume of the player. Values are between 0.0 and 1.0.
      Overrides:
      amp in class SoundObject
      Parameters:
      amp - A float value between 0.0 (complete silence) and 1.0 (full volume) controlling the amplitude/volume of this sound.

    • channels

      public int channels()
      Returns the number of channels in the audiosample as an int (1 for mono, 2 for stereo).
      Overrides:
      channels in class SoundObject
      Returns:
      the number of channels in the audiosample (1 for mono, 2 for stereo)
      See Also:

    • cue

      public void cue(float time)
      Cues the playhead to a fixed position in the audiosample. Note that cue() only affects the playhead for future calls to play(), but not to loop().
      Parameters:
      time - position in the audiosample that the next playback should start from, in seconds.

    • cueFrame

      public void cueFrame(int frameNumber)
      Cues the playhead to a fixed position in the audiosample.
      Parameters:
      frameNumber - frame number to start playback from.

    • duration

      public float duration()
      Returns the duration of the audiosample in seconds.
      Returns:
      The duration of the audiosample in seconds.

    • frames

      public int frames()
      Returns the number of frames of the audiosample as an int.
      Returns:
      The number of frames of the audiosample.

    • resize

      public void resize(int frames)

    • jump

      public void jump(float time)
      Jump to a specific position in the audiosample while continuing to play (or starting to play if it wasn't playing already).
      Parameters:
      time - position to jump to, in seconds
      See Also:

    • jumpFrame

      public void jumpFrame(int frameNumber)
      Jump to a specific position in the audiosample without interrupting playback.
      Parameters:
      time - frame number to jump to.
      See Also:

    • loop

      public void loop()

    • loop

      public void loop(float rate)

    • loop

      public void loop(float rate, float amp)

    • loop

      public void loop(float rate, float pos, float amp)
      Starts the playback of the audiosample. Only plays to the end of the audiosample once. If cue() or pause() were called previously, playback will resume from the cued position.
      Parameters:
      rate - relative playback rate to use. 1 is the original speed. 0.5 is half speed and one octave down. 2 is double the speed and one octave up.
      pos - the panoramic position of this sound unit from -1.0 (left) to 1.0 (right). Only works for mono audiosamples!
      amp - the desired playback amplitude of the audiosample as a value from 0.0 (complete silence) to 1.0 (full volume)

    • loop

      public void loop(float rate, float pos, float amp, float add)
      Deprecated.

    • play

      public void play()
      Description copied from class: SoundObject
      Starts the generator
      Overrides:
      play in class SoundObject

    • play

      public void play(float rate)

    • play

      public void play(float rate, float amp)

    • play

      public void play(float rate, float pos, float amp)

    • play

      public void play(float rate, float pos, float amp, float cue)
      Deprecated.
      Starts the playback of the audiosample. Only plays to the end of the audiosample once. If cue() or pause() were called previously, playback will resume from the cued position.
      Parameters:
      rate - relative playback rate to use. 1 is the original speed. 0.5 is half speed and one octave down. 2 is double the speed and one octave up.
      amp - the desired playback amplitude of the audiosample as a value from 0.0 (complete silence) to 1.0 (full volume)
      pos - the panoramic position of this sound unit from -1.0 (left) to 1.0 (right). Only works for mono audiosamples!
      cue - position in the audiosample that playback should start from, in seconds.

    • play

      public void play(float rate, float pos, float amp, float add, float cue)
      Deprecated.

    • playFor

      public void playFor(float duration)

    • playFor

      public void playFor(float duration, float cue)
      Starts the playback of the audiosample for the specified duration or to the end of the audiosample, whichever comes first.
      Parameters:
      duration - duration that this audiosample should be played back for, in seconds. If the start position plus duration exceeds the total duration of the sample, playback will stop at the end of the sample.
      cue - position in the audiosample that playback should start from, in seconds.

    • rate

      public void rate(float rate)
      Set the relative playback rate of the audiosample. 1 is the original speed. 0.5 is half speed and one octave down. 2 is double the speed and one octave up.
      Parameters:
      rate - Relative playback rate to use. 1 is the original speed. 0.5 is half speed and one octave down. 2 is double the speed and one octave up.

    • resize

      public void resize(int frames, boolean stereo)
      Resizes the underlying buffer of the audiosample to the given number of frames. Calling this method allocates a completely new buffer, so any ongoing playback will be stopped and all data currently stored in the sample will be lost.
      Parameters:
      frames - the desired number of frames for this audiosample
      stereo - whether to treat the audiosample as 2-channel (stereo) or not (default: false)

    • sampleRate

      public int sampleRate()
      Returns the underlying sample rate of the audiosample.
      Returns:
      Returns the underlying sample rate of the audiosample as an int.

    • pan

      public void pan(float pos)
      Pan the soundfile in a stereo panorama. -1.0 pans to the left channel and 1.0 to the right channel. Note that panning is only supported for mono (1 channel) audiosamples.
      Overrides:
      pan in class SoundObject
      Parameters:
      pos - the panoramic position of this sound unit from -1.0 (left) to 1.0 (right).

    • set

      public void set(float rate, float pos, float amp)
      Set multiple parameters at once.
      Parameters:
      rate - Relative playback rate to use. 1 is the original speed. 0.5 is half speed and one octave down. 2 is double the speed and one octave up.
      pos - the panoramic position of this sound unit from -1.0 (left) to 1.0 (right).
      amp - the desired playback amplitude of the audiosample as a value from 0.0 (complete silence) to 1.0 (full volume)

    • set

      public void set(float rate, float pos, float amp, float add)
      Deprecated.

    • stop

      public void stop()
      Stops the playback.
      Overrides:
      stop in class SoundObject

    • position

      public float position()
      Get current sound file playback position in seconds. Note that, if this audio sample was at some point played back in parallel (triggered by another call to play() before the original playback had finished), the position returned by this function can be of any of the concurrent playbacks, not necessarily the last one that was triggered.
      Returns:
      The current position of the audio sample playback in seconds

    • positionFrame

      public int positionFrame()
      Get frame index of current sound file playback position. Note that, if this audio sample was at some point played back in parallel (triggered by another call to play() before the original playback had finished), the position returned by this function can be of any of the concurrent playbacks, not necessarily the last one that was triggered.
      Returns:
      The current frame index position of the audio sample playback

    • percent

      public float percent()
      Get current sound file playback position in percent. Note that, if this audio sample was at some point played back in parallel (triggered by another call to play() before the original playback had finished), the position returned by this function can be of any of the concurrent playbacks, not necessarily the last one that was triggered.
      Returns:
      The current position of the audio sample playback in percent (a value between 0 and 100).

    • pause

      public void pause()
      Stop the playback of the sample, but cue it to the current position. The next call to play() will continue playing where it left off.
      See Also:

    • read

      public void read(float[] data)
      Get the current sample data and write it into the given array. Get the current sample data and write it into the given array. The array has to be able to store as many floats as there are frames in this sample, or twice the number of frames for a stereo sample.
      Parameters:
      data - the target array that the read data is written to

    • read

      public void read(int startFrame, float[] data, int startIndex, int numFrames)
      The underlying data of the audiosample can be read and written in several different ways: the method taking a single float array `data` gets the current sample data and write it into the given array. The array has to be able to store as many floats as there are frames in this sample. It is also possible to only read parts of the sample data using the method with four arguments, which allows you to specify the index of the first frame to read, the position in the array to write it to, as well as how many frames to copy over into the array in total. Finally, the method taking a single integer argument `index` returns the value of the single audio frame of the sample at this index as a float.
      Parameters:
      startFrame - the index of the first frame of the audiosample that should be read
      startIndex - the position in the array where the first read frame should be written to (typically 0)
      numFrames - the number of frames that should be read (can't be greater than audiosample.channels() * data.length - startIndex)

    • read

      public float read(int frameIndex)
      Parameters:
      frameIndex - the index of the single frame of the audiosample that should be read and returned. `frameIndex` has to be between 0 and `sample.frames() * sample.channels() - 1` (inclusive)`. For mono files, `read(frameIndex)` is identical to `read(frameIndex, 0)`. For stereo files, unless you also specify a `channelIndex`, `read(frameIndex)` will return the samples from both the left and right channel in interleaved order. (See the Soundfile > StereoSample example for a demonstration.)
      Returns:
      float: the value of the audio sample at the given index

    • read

      public float read(int frameIndex, int channelIndex)
      Parameters:
      channelIndex - the channel from which to extract the frame value (0 for left, 1 for right). `read(frameIndex, channelIndex)` is the same as calling `read(frameIndex * this.channels() + channelIndex)`.

    • write

      public void write(float[] data)
      Overwrite the sample with the data from the given array. The array should contain as many floats as there are frames in this sample, or twice as many as the number of frames for a stereo sample.
      Parameters:
      data - the array from which the sample data, up to sample.frames() * sample.channels() floats, should be copied

    • write

      public void write(int startFrame, float[] data, int startIndex, int numFrames)
      The underlying data of the audiosample can be read and (over)written in several different ways: the method taking a single float array `data` replaces the sample data with the content of the given array. The array has to contain as many floats as there are frames in this sample. It is also possible to only write parts of the sample data using the method with four arguments, which allows you to specify the index of the first frame to write, the position in the array to take the data from, as well as how many frames should be copied over. Finally, the method taking two arguments simply sets the value of the single audio frame specified by the first argument to the given float value.
      Parameters:
      startFrame - the index of the first frame of the audiosample that should be written to
      startIndex - the position in the array that the first value to write should be taken from (typically 0)
      numFrames - the number of frames that should be written (can't be greater than audiosample.channels() * data.length - startIndex)

    • write

      public void write(int index, float value)
      Parameters:
      index - the index of the single frame of the audiosample that should be set to the given value
      value - the float value that the given audio frame should be set to