jm.audio

## Class AudioObject

- java.lang.Object
- - jm.audio.AudioObject

- All Implemented Interfaces:
    Alignments, DrumMap, Durations, Dynamics, Frequencies, Noises, Panning, Pitches, ProgramChanges, RhythmValues, Scales, Tunings, Volumes, Waveforms, JMC
  Direct Known Subclasses:
    Add, ADSR, AllFGTR, AllPass, Comb, Compressor, Delay, Envelope, FFT, FGTR, Filter, Grain2, Granulator, InverseFFT, Invert, Multiply, Noise, NoteBuffer, NoteBufferReversed, Oscillator, Pluck, PrintOut, ReSample, RTIn, SampleIn, SampleOut, Smooth, Splitter, Spring, StereoPan, TapDelay, TextIn, Value, Volume, Wavelet, Waveshaper, WaveTable, Window

      public abstract class AudioObject
      extends java.lang.Object
      implements JMC

  Audio Object is the super class of all audio reading, writing, processing and generating units. An AudioObject in the jMusic audio architecture is any class which is used to form part of an audio chain, be that a generator object (such as a wavetable), a reader object (such as an audio file reader), a processor object (such as a filter), or a writer object ( such as a file writer).
  Audio chains are created by linking together AudioObjects into lists where every AudioObject knows which AudioObjects come before and after it. This link is achieved by passing an AudioObjects immediate predicesors in to its constructor as an array of AudioObjects. The number of inputs accepted by an AudioObject is a direct relation to the size of the AudioObject array passed to an AudioObject's constructor. AudioObjects also know who their successor is so that information (such as sample rate) can be deceminated from the top to the bottom of the audio chain.
  The chain works using a pull mechanism where the final AudioObject (defined in an Instrument object as the finalAO object) requests a number of samples from it's previous AudioObject(s). This request is then passed on up the chain until the requested number of samples is retrieved from each chains first AudioObject (defined in an Instrument as an array of primaryAO objects). These requests for samples are made by passing a float[] to each AudioObjects work() method and requesting that it fill the float[] with sample data (if it is a primary AudioObject) or process that float[] in some manner.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `channels` The number of audio channels for this audio object.
    `protected Note` | `currentNote` the note currently being rendered
    `protected double` | `currentNoteStartTime` the currentNotes startTime
    `protected boolean` | `finished`
    `protected int` | `inputs` how many inputs are attached to this object
    `protected Instrument` | `inst` The Instrument which currently implements this AudioObject
    `protected java.lang.String` | `name` The name of this Audio Object.
    `protected AudioObject[]` | `next` the AudioObject following to this one
    `protected int` | `numOfSamples` the number of samples which need to be processed for this note to be rendered (in mono, for stereo multiply by 2 etc.)
    `protected AudioObject[]` | `previous` the AudioObject previous to this one
    `protected int` | `sampleRate` This audio objects sampling rate

    - ### Fields inherited from interface jm.JMC

      `AMPLITUDE, DEBUG, DYNAMIC, EIGHT_BIT, FREQUENCY, KEY_SIG_EVT, MONO, NO_DENOMINATOR, NO_INSTRUMENT, NO_KEY_QUALITY, NO_KEY_SIGNATURE, NO_NUMERATOR, OCTAPHONIC, PAN, PITCH, PROG_EVT, QUADRAPHONIC, RHYTHM, SIXTEEN_BIT, STEREO, TEMP_EVT, THIRTY_TWO_BIT, TIME_SIG_EVT, VERBOSE`

    - ### Fields inherited from interface jm.constants.Durations

      `C, CD, CDD, CROTCHET, CROTCHET_TRIPLET, CT, DC, DDC, DDEN, DDHN, DDM, DDQ, DDQN, DEMI_SEMI_QUAVER, DEMI_SEMI_QUAVER_TRIPLET, DEN, DHN, DM, DOTTED_CROTCHET, DOTTED_EIGHTH_NOTE, DOTTED_HALF_NOTE, DOTTED_MINIM, DOTTED_QUARTER_NOTE, DOTTED_QUAVER, DOTTED_SEMI_QUAVER, DOTTED_SIXTEENTH_NOTE, DOUBLE_DOTTED_CROTCHET, DOUBLE_DOTTED_EIGHTH_NOTE, DOUBLE_DOTTED_HALF_NOTE, DOUBLE_DOTTED_MINIM, DOUBLE_DOTTED_QUARTER_NOTE, DOUBLE_DOTTED_QUAVER, DQ, DQN, DSN, DSQ, DSQT, EIGHTH_NOTE, EIGHTH_NOTE_TRIPLET, EN, ENT, HALF_NOTE, HALF_NOTE_TRIPLET, HN, HNT, M, MD, MDD, MINIM, MINIM_TRIPLET, MT, Q, QD, QDD, QN, QNT, QT, QUARTER_NOTE, QUARTER_NOTE_TRIPLET, QUAVER, QUAVER_TRIPLET, SB, SEMI_QUAVER, SEMI_QUAVER_TRIPLET, SEMIBREVE, SIXTEENTH_NOTE, SIXTEENTH_NOTE_TRIPLET, SN, SNT, SQ, SQD, SQT, THIRTYSECOND_NOTE, THIRTYSECOND_NOTE_TRIPLET, TN, TNT, TSN, TSNT, WHOLE_NOTE, WN`

    - ### Fields inherited from interface jm.constants.Pitches

      `a0, A0, a1, A1, a2, A2, a3, A3, a4, A4, a5, A5, a6, A6, a7, A7, a8, A8, af0, AF0, af1, AF1, af2, AF2, af3, AF3, af4, AF4, af5, AF5, af6, AF6, af7, AF7, af8, AF8, afn1, AFN1, an1, AN1, as0, AS0, as1, AS1, as2, AS2, as3, AS3, as4, AS4, as5, AS5, as6, AS6, as7, AS7, as8, AS8, asn1, ASN1, b0, B0, b1, B1, b2, B2, b3, B3, b4, B4, b5, B5, b6, B6, b7, B7, b8, B8, bf0, BF0, bf1, BF1, bf2, BF2, bf3, BF3, bf4, BF4, bf5, BF5, bf6, BF6, bf7, BF7, bf8, BF8, bfn1, BFN1, bn1, BN1, bs0, BS0, bs1, BS1, bs2, BS2, bs3, BS3, bs4, BS4, bs5, BS5, bs6, BS6, bs7, BS7, bs8, BS8, bsn1, BSN1, c0, C0, c1, C1, c2, C2, c3, C3, c4, C4, c5, C5, c6, C6, c7, C7, c8, C8, c9, C9, cf0, CF0, cf1, CF1, cf2, CF2, cf3, CF3, cf4, CF4, cf5, CF5, cf6, CF6, cf7, CF7, cf8, CF8, cf9, CF9, cn1, CN1, cs0, CS0, cs1, CS1, cs2, CS2, cs3, CS3, cs4, CS4, cs5, CS5, cs6, CS6, cs7, CS7, cs8, CS8, cs9, CS9, csn1, CSN1, d0, D0, d1, D1, d2, D2, d3, D3, d4, D4, d5, D5, d6, D6, d7, D7, d8, D8, d9, D9, df0, DF0, df1, DF1, df2, DF2, df3, DF3, df4, DF4, df5, DF5, df6, DF6, df7, DF7, df8, DF8, df9, DF9, dfn1, DFN1, dn1, DN1, ds0, DS0, ds1, DS1, ds2, DS2, ds3, DS3, ds4, DS4, ds5, DS5, ds6, DS6, ds7, DS7, ds8, DS8, ds9, DS9, dsn1, DSN1, e0, E0, e1, E1, e2, E2, e3, E3, e4, E4, e5, E5, e6, E6, e7, E7, e8, E8, e9, E9, ef0, EF0, ef1, EF1, ef2, EF2, ef3, EF3, ef4, EF4, ef5, EF5, ef6, EF6, ef7, EF7, ef8, EF8, ef9, EF9, efn1, EFN1, en1, EN1, es0, ES0, es1, ES1, es2, ES2, es3, ES3, es4, ES4, es5, ES5, es6, ES6, es7, ES7, es8, ES8, es9, ES9, esn1, ESN1, f0, F0, f1, F1, f2, F2, f3, F3, f4, F4, f5, F5, f6, F6, f7, F7, f8, F8, f9, F9, ff0, FF0, ff1, FF1, ff2, FF2, ff3, FF3, ff4, FF4, ff5, FF5, ff6, FF6, ff7, FF7, ff8, FF8, ff9, FF9, ffn1, FFN1, fn1, FN1, fs0, FS0, fs1, FS1, fs2, FS2, fs3, FS3, fs4, FS4, fs5, FS5, fs6, FS6, fs7, FS7, fs8, FS8, fs9, FS9, fsn1, FSN1, g0, G0, g1, G1, g2, G2, g3, G3, g4, G4, g5, G5, g6, G6, g7, G7, g8, G8, g9, G9, gf0, GF0, gf1, GF1, gf2, GF2, gf3, GF3, gf4, GF4, gf5, GF5, gf6, GF6, gf7, GF7, gf8, GF8, gf9, GF9, gfn1, GFN1, gn1, GN1, gs0, GS0, gs1, GS1, gs2, GS2, gs3, GS3, gs4, GS4, gs5, GS5, gs6, GS6, gs7, GS7, gs8, GS8, gsn1, GSN1, REST`

    - ### Fields inherited from interface jm.constants.Frequencies

      `FRQ`

    - ### Fields inherited from interface jm.constants.Tunings

      `EQUAL, JUST, MEAN, PYTHAGOREAN`

    - ### Fields inherited from interface jm.constants.Volumes

      `F, FF, FFF, FORTE, FORTISSIMO, MEZZO_FORTE, MEZZO_PIANO, MF, MP, P, PIANISSIMO, PP, PPP, SILENT`

    - ### Fields inherited from interface jm.constants.Panning

      `PAN_CENTER, PAN_CENTRE, PAN_LEFT, PAN_RIGHT`

    - ### Fields inherited from interface jm.constants.ProgramChanges

      `AAH, ABASS, AC_GUITAR, ACCORDION, ACOUSTIC_BASS, ACOUSTIC_GRAND, ACOUSTIC_GUITAR, AGOGO, AHHS, ALTO, ALTO_SAX, ALTO_SAXOPHONE, APPLAUSE, ATMOSPHERE, BAG_PIPES, BAGPIPE, BAGPIPES, BANDNEON, BANJO, BARI, BARI_SAX, BARITONE, BARITONE_SAX, BARITONE_SAXOPHONE, BASS, BASSOON, BELL, BELLS, BIRD, BOTTLE, BOTTLE_BLOW, BOWED_GLASS, BRASS, BREATH, BREATHNOISE, BRIGHT_ACOUSTIC, BRIGHTNESS, CALLOPE, CELESTA, CELESTE, CELLO, CGUITAR, CHARANG, CHIFFER, CHIFFER_LEAD, CHOIR, CHURCH_ORGAN, CLAR, CLARINET, CLAV, CLAVINET, CLEAN_GUITAR, CONCERTINA, CONTRA_BASS, CONTRABASS, CRYSTAL, CYMBAL, DGUITAR, DIST_GUITAR, DISTORTED_GUITAR, DOUBLE_BASS, DROPS, DRUM, DX_EPIANO, EBASS, ECHO, ECHO_DROP, ECHO_DROPS, ECHOS, EL_BASS, EL_GUITAR, ELECTRIC_BASS, ELECTRIC_GRAND, ELECTRIC_GUITAR, ELECTRIC_ORGAN, ELECTRIC_PIANO, ELPIANO, ENGLISH_HORN, EPIANO, EPIANO2, FANTASIA, FBASS, FIDDLE, FINGERED_BASS, FLUTE, FRENCH_HORN, FRET, FRET_NOISE, FRETLESS, FRETLESS_BASS, FRETNOISE, FRETS, GLOCK, GLOCKENSPIEL, GMSAW_WAVE, GMSQUARE_WAVE, GOBLIN, GT_HARMONICS, GUITAR, GUITAR_HARMONICS, GUNSHOT, HALO, HALO_PAD, HAMMOND_ORGAN, HARMONICA, HARMONICS, HARP, HARPSICHORD, HELICOPTER, HONKYTONK, HONKYTONK_PIANO, HORN, ICE_RAIN, ICERAIN, JAZZ_GUITAR, JAZZ_ORGAN, JGUITAR, KALIMBA, KOTO, MARIMBA, METAL_PAD, MGUITAR, MUSIC_BOX, MUTED_GUITAR, MUTED_TRUMPET, NGUITAR, NYLON_GUITAR, OBOE, OCARINA, OGUITAR, OOH, OOHS, ORCHESTRA_HIT, ORGAN, ORGAN2, ORGAN3, OVERDRIVE_GUITAR, PAD, PAN_FLUTE, PANFLUTE, PBASS, PHONE, PIANO, PIANO_ACCORDION, PIC, PICC, PICCOLO, PICKED_BASS, PIPE_ORGAN, PIPES, PITZ, PIZZ, PIZZICATO_STRINGS, POLY_SYNTH, POLYSYNTH, PSTRINGS, RAIN, RECORDER, REED_ORGAN, REVERSE_CYMBAL, RHODES, SAW, SAWTOOTH, SAX, SAXOPHONE, SBASS, SEA, SEASHORE, SFX, SGUITAR, SHAKUHACHI, SHAMISEN, SHANNAI, SITAR, SLAP, SLAP_BASS, SLAP_BASS_1, SLAP_BASS_2, SLOW_STRINGS, SOLO_VOX, SOP, SOPRANO, SOPRANO_SAX, SOPRANO_SAXOPHONE, SOUNDEFFECTS, SOUNDFX, SOUNDTRACK, SPACE_VOICE, SQUARE, STAR_THEME, STEEL_DRUM, STEEL_DRUMS, STEEL_GUITAR, STEELDRUM, STEELDRUMS, STR, STREAM, STRING_ENSEMBLE_1, STRING_ENSEMBLE_2, STRINGS, SWEEP, SWEEP_PAD, SYN_CALLIOPE, SYNTH_BASS, SYNTH_BASS_1, SYNTH_BASS_2, SYNTH_BRASS, SYNTH_BRASS_1, SYNTH_BRASS_2, SYNTH_CALLIOPE, SYNTH_DRUM, SYNTH_DRUMS, SYNTH_STRINGS, SYNTH_STRINGS_1, SYNTH_STRINGS_2, SYNVOX, TAIKO, TELEPHONE, TENOR, TENOR_SAX, TENOR_SAXOPHONE, THUMB_PIANO, THUNDER, TIMP, TIMPANI, TINKLE_BELL, TOM, TOM_TOM, TOM_TOMS, TOMS, TREMOLO, TREMOLO_STRINGS, TROMBONE, TRUMPET, TUBA, TUBULAR_BELL, TUBULAR_BELLS, VIBES, VIBRAPHONE, VIOLA, VIOLIN, VIOLIN_CELLO, VOICE, VOX, WARM_PAD, WHISTLE, WIND, WOODBLOCK, WOODBLOCKS, XYLOPHONE`

    - ### Fields inherited from interface jm.constants.DrumMap

      `ACOUSTIC_BASS_DRUM, ACOUSTIC_SNARE, BASS_DRUM_1, CABASA, CHINESE_CYMBAL, CLAVES, CLOSED_HI_HAT, COWBELL, CRASH_CYMBAL_1, CRASH_CYMBAL_2, ELECTRIC_SNARE, HAND_CLAP, HI_BONGO, HI_MID_TOM, HI_WOOD_BLOCK, HIGH_AGOGO, HIGH_FLOOR_TOM, HIGH_TIMBALE, HIGH_TOM, LONG_GUIRO, LONG_WHISTLE, LOW_AGOGO, LOW_BONGO, LOW_CONGA, LOW_FLOOR_TOM, LOW_MID_TOM, LOW_TIMBALE, LOW_TOM, LOW_WOOD_BLOCK, MARACAS, MUTE_CUICA, MUTE_HI_CONGA, MUTE_TRIANGLE, OPEN_CUICA, OPEN_HI_CONGA, OPEN_HI_HAT, OPEN_TRIANGLE, PEDAL_HI_HAT, RIDE_BELL, RIDE_CYMBAL_1, RIDE_CYMBAL_2, SHORT_GUIRO, SHORT_WHISTLE, SIDE_STICK, SPLASH_CYMBAL, TAMBOURINE, VIBRASLAP`

    - ### Fields inherited from interface jm.constants.Scales

      `AEOLIAN_SCALE, BLUES_SCALE, CHROMATIC_SCALE, DIATONIC_MINOR_SCALE, DORIAN_SCALE, HARMONIC_MINOR_SCALE, INDIAN_SCALE, LYDIAN_SCALE, MAJOR_SCALE, MELODIC_MINOR_SCALE, MINOR_SCALE, MIXOLYDIAN_SCALE, NATURAL_MINOR_SCALE, PENTATONIC_SCALE, TURKISH_SCALE`

    - ### Fields inherited from interface jm.constants.Waveforms

      `COSINE_WAVE, PULSE_WAVE, SABERSAW_WAVE, SAWDOWN_WAVE, SAWTOOTH_WAVE, SINE_WAVE, SQUARE_WAVE, TRIANGLE_WAVE`

    - ### Fields inherited from interface jm.constants.Noises

      `BROWN_NOISE, FRACTAL_NOISE, SMOOTH_NOISE, STEP_NOISE, WHITE_NOISE`

    - ### Fields inherited from interface jm.constants.Alignments

      `AFTER, BEFORE, CENTER_ALIGN, CENTER_ON_END, CENTER_ON_START, CENTRE_ALIGN, CENTRE_ON_END, CENTRE_ON_START, END_ON_CENTER, END_ON_CENTRE, END_TOGETHER, START_ON_CENTER, START_ON_CENTRE, START_TOGETHER`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AudioObject(AudioObject[] previous, java.lang.String name)` This constructor is used for all audio processors and writers that need to accept input from multiple streams (ie Audio Objects).
    `protected` | `AudioObject(AudioObject previous, java.lang.String name)` This constructor is used for all audio processors and writers that need to accept input from a single stream (ie Audio Object).
    `protected` | `AudioObject(Instrument inst, int sampleRate, java.lang.String name)` This constructor is used for generator and reader audio units where no previous audio objects exist in the stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `build()` The build method can be overriden by Audio Objects to provide any extra initialization that may be required before the Audio Object can be used for each new note that needs rendering.
    `protected void` | `buildNext(Note note, double startTime, int numOfSamples)` The buildNext method decimates information down through the audio chain passing data such as sampleRate, number channels, number of samples required etc.
    `int` | `getChannels()` Returns the number of channels in this Audio Object
    `int` | `getSampleRate()` getSampleRate returns an Audio Objects samples rate
    `void` | `newNote(Note note, double startTime, int numOfSamples)` The newNote method is called everytime a new note is passed to the AudioObject.
    `int` | `nextWork(float[] buffer)`
    `abstract int` | `work(float[] buffer)` The work method is responsible for handling the processing done by an AudioObject.

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

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

- - ### Field Detail

    - #### previous

          protected AudioObject[] previous

      the AudioObject previous to this one

    - #### next

          protected AudioObject[] next

      the AudioObject following to this one

    - #### name

          protected java.lang.String name

      The name of this Audio Object.

    - #### sampleRate

          protected int sampleRate

      This audio objects sampling rate

    - #### channels

          protected int channels

      The number of audio channels for this audio object.

    - #### inputs

          protected int inputs

      how many inputs are attached to this object

    - #### currentNote

          protected Note currentNote

      the note currently being rendered

    - #### currentNoteStartTime

          protected double currentNoteStartTime

      the currentNotes startTime

    - #### numOfSamples

          protected int numOfSamples

      the number of samples which need to be processed for this note to be rendered (in mono, for stereo multiply by 2 etc.)

    - #### inst

          protected Instrument inst

      The Instrument which currently implements this AudioObject

    - #### finished

          protected boolean finished

  - ### Constructor Detail

    - #### AudioObject

          protected AudioObject(AudioObject previous,
                     java.lang.String name)

      This constructor is used for all audio processors and writers that need to accept input from a single stream (ie Audio Object).
      Parameters:
        `previous` - The AudioObject previous to this one
        `name` - A name to associate with this Audio Object

    - #### AudioObject

          protected AudioObject(AudioObject[] previous,
                     java.lang.String name)

      This constructor is used for all audio processors and writers that need to accept input from multiple streams (ie Audio Objects).
      Parameters:
        `previous` - The AudioObjects previous to this one
        `name` - A name to associate with this Audio Object.

    - #### AudioObject

          protected AudioObject(Instrument inst,
                     int sampleRate,
                     java.lang.String name)

      This constructor is used for generator and reader audio units where no previous audio objects exist in the stream. This constructor sets the sampleRate which will then propogate through to all following Audio Objects when their build methods are called. Any AudioObjects that make use of this constructor should be defined as primaryAO objects in the Instrument createChain() method.
      Parameters:
        `sampleRate` - the sample rate to use for all objects
        `name` - A name to associate with this Audio Object

  - ### Method Detail

    - #### work

          public abstract int work(float[] buffer)
                            throws AOException

      The work method is responsible for handling the processing done by an AudioObject. This processing maybe as trivial as reading samples from an audio file or as complex as performing real-time fft transformations. The work method accepts an empty float[] as input and is responsible for filling and/or processing the samples contained in the array. The size of the array is defined in the Instrument class and is generally set to 4096.
      Throws:
        `AOException`

    - #### nextWork

          public int nextWork(float[] buffer)
                       throws AOException

      Throws:
        `AOException`

    - #### buildNext

          protected void buildNext(Note note,
                       double startTime,
                       int numOfSamples)

      The buildNext method decimates information down through the audio chain passing data such as sampleRate, number channels, number of samples required etc. The buildNext method is also responsible for calling each audio objects build method which provides any additional initialization that the object may require. The buildNext method should be called by the first audio object in the audio chain to initialise all following audio objects.
      Parameters:
        `Note` - The note this chain is currently processing.
        `startTime` - The startTime of the note.
        `int` - The number of samples which need to be processed.

    - #### build

          protected void build()

      The build method can be overriden by Audio Objects to provide any extra initialization that may be required before the Audio Object can be used for each new note that needs rendering. The AudioObject parameters currentNote, currentNoteStartTime and numOfSamples will provide any note specific information that the build method may need to utilise.

    - #### newNote

          public void newNote(Note note,
                     double startTime,
                     int numOfSamples)

      The newNote method is called everytime a new note is passed to the AudioObject. newNote sets a number of AudioObject parameters which are produced based on the new note information.
      Parameters:
        `note` - sets the parameter currentNote
        `startTime` - sets the parameter currentNoteStartTime
        `numOfSamples` - sets the parameter numOfSamples

    - #### getSampleRate

          public int getSampleRate()

      getSampleRate returns an Audio Objects samples rate
      Returns:
        An audio objects sampleRate.

    - #### getChannels

          public int getChannels()

      Returns the number of channels in this Audio Object
      Returns:
        An audio object's channels.