jm.audio

Class Instrument

java.lang.Object

java.lang.Thread

jm.audio.Instrument

All Implemented Interfaces:

java.lang.Runnable, Alignments, DrumMap, Durations, Dynamics, Frequencies, Noises, Panning, Pitches, ProgramChanges, RhythmValues, Scales, Tunings, Volumes, Waveforms, JMC

Direct Known Subclasses:

AudioSampleInst

public abstract class Instrument
extends java.lang.Thread
implements java.lang.Runnable, JMC

An Instrument in jMusic is a chain of AudioObjects which are strung together to form a signal processing chain. Instruments chains are each run in their own thread.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected int	bufsize buffer size for passing samples between work methods
protected AudioObject	finalAO the final audio chain object
boolean	finishedNewData
int	iterations the number of samples processed by this instrument for this note
protected java.util.Vector	listeners Vector for holding AudioChainListeners
protected int	numOfChannels the number of channels which this Instrument must supply
protected int	numOfSamples the number of samples which this Instrument needs to write
protected int	output Which output type is the instrument for? Rendering, realtime, or other.
protected java.util.Vector	primaryAO the primary audio chain objects (ie the first in each chain)
static int	REALTIME Output from instrument should go to RTLine and RTMixer for realtime playback.
static int	RENDER Output from instrument to go to a file of the hard drive.
protected long	samplesProcessed number of samples processed by this instrument in its lifetime

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

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	Instrument() Simple default constructor

Method Summary

Methods

Modifier and Type	Method and Description
void	addAudioChainListener(AudioChainListener listener) Attaches an AudioChainListener to this instrument
void	addPrimaryAO(AudioObject ao) Add primary Audio Objects to the primaryAO vector
void	addRTLine(RTLine rtline) Associates an RTLine with this Instrument
void	block() block is called to hold any further processing untill all instruments are in the same place (in time that is).
abstract void	createChain() This method is automatically called on startup to initialise any AudioObjects used by this instrument
int	getBufSize() Returns the buffer size being used by this instrument.
int	getChannels() Returns the number of channels being used by this instrument.
boolean	getFinished() Return the finished state of this note
boolean	getInitialised() Returns theinitialsed status of the instrument.
java.util.Enumeration	getListeners() Return this instruments audio chain listeners
int	getOutput() Check on the current output flag status.
int	getSampleRate() Returns the sample rate being used by this instrument.
void	iterateChain() The iterate chain method is resposible for pulling the appropriate number of samples through the audio chain.
void	pause()
void	release() release is called by RTAudio when the RTLine is ready to start processing data again.
void	renderNote(Note note, double startTime) The renderNote method is called whenever the instrument is asked to render a new note.
void	run() This thread's run method
void	setBlock(boolean block) Set whether the instrument should block or not.
void	setBufSize(int bufsize) Sets the buffer size which is used to pass sample data between work methods.
void	setClear(boolean clear) If clear is set to true the iterate method will not block after calling controlChange on all its listeners.
void	setController(double[] controlValues) An array of double values which can be used as controller messages.
void	setFinalAO(AudioObject ao) Sets the finalAO for this instrument
void	setFinished(boolean state) Is the instrument still processing a note? If set to false during playback the note will end abruptly.
void	setInitialised(boolean val) Tells if the instrument's creatchain method has been called or not.
void	setOutput(int out) Select the output flage value.
void	unPause()

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

iterations

public int iterations

the number of samples processed by this instrument for this note

primaryAO

protected java.util.Vector primaryAO

the primary audio chain objects (ie the first in each chain)

finalAO

protected AudioObject finalAO

the final audio chain object

numOfSamples

protected int numOfSamples

the number of samples which this Instrument needs to write

numOfChannels

protected int numOfChannels

the number of channels which this Instrument must supply

bufsize

protected int bufsize

buffer size for passing samples between work methods

listeners

protected volatile java.util.Vector listeners

Vector for holding AudioChainListeners

samplesProcessed

protected long samplesProcessed

number of samples processed by this instrument in its lifetime

finishedNewData

public boolean finishedNewData

RENDER

public static final int RENDER

Output from instrument to go to a file of the hard drive. This is normally associated with using the SampleOut audio object

See Also:

Constant Field Values

REALTIME

public static final int REALTIME

Output from instrument should go to RTLine and RTMixer for realtime playback. This normally means the SampleOut audio object is NOT part of the audio chain.

See Also:

Constant Field Values

output

protected int output

Which output type is the instrument for? Rendering, realtime, or other. This flag must be handled by each instrument, as it is not static (global).

Constructor Detail

Instrument

protected Instrument()

Simple default constructor

Method Detail

renderNote

public void renderNote(Note note,
              double startTime)

The renderNote method is called whenever the instrument is asked to render a new note. This method is responsible for caclulating the number of samples required for the note and calls any AudioObjects build methods prior to starting the chain.

Parameters:

note - The note to render

startTime - The startTime of the note

addPrimaryAO

public void addPrimaryAO(AudioObject ao)

Add primary Audio Objects to the primaryAO vector

setFinalAO

public void setFinalAO(AudioObject ao)
                throws AOException

Sets the finalAO for this instrument

Throws:

AOException

setFinished

public void setFinished(boolean state)

Is the instrument still processing a note? If set to false during playback the note will end abruptly.

getFinished

public boolean getFinished()

Return the finished state of this note

setBufSize

public void setBufSize(int bufsize)

Sets the buffer size which is used to pass sample data between work methods.

Parameters:

bufsize - The buffer size to set for this instrument

getBufSize

public int getBufSize()

Returns the buffer size being used by this instrument.

Returns:

bufsize The size of the buffer being used by this instrument

getChannels

public int getChannels()

Returns the number of channels being used by this instrument.

Returns:

numOfChannels The number of channels being used by this instrument

getSampleRate

public int getSampleRate()

Returns the sample rate being used by this instrument.

Returns:

sampleRate The sample rate being used by this instrument

setInitialised

public void setInitialised(boolean val)

Tells if the instrument's creatchain method has been called or not.

getInitialised

public boolean getInitialised()

Returns theinitialsed status of the instrument.

Returns:

initialised

addRTLine

public void addRTLine(RTLine rtline)

Associates an RTLine with this Instrument

getListeners

public java.util.Enumeration getListeners()

Return this instruments audio chain listeners

Returns:

listeners return all audio chain listeners

addAudioChainListener

public void addAudioChainListener(AudioChainListener listener)

Attaches an AudioChainListener to this instrument

Parameters:

listener - the AudioChainListener to add

setController

public void setController(double[] controlValues)

An array of double values which can be used as controller messages. Instruments that wish to implement controllers should override this method. Controller values which are not doubles will need to be cast to their appropriate types in the overriding method.

Parameters:

controlValues -

run

public void run()

This thread's run method

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

pause

public void pause()

unPause

public void unPause()

setBlock

public void setBlock(boolean block)

Set whether the instrument should block or not. This setting should be set to true if working in real-time and false if not working in real time.

setClear

public void setClear(boolean clear)

If clear is set to true the iterate method will not block after calling controlChange on all its listeners.

setOutput

public void setOutput(int out)

Select the output flage value. This is normally used to specify if the SampleOut object will be included in the audio chain. There are constats in this class for common values, RENDER = 0 and REALTIME = 1.

getOutput

public int getOutput()

Check on the current output flag status. Normally 0 = render to file, 1 = play via realtime output. However, these flags must be handled by each instrument, as they are not global.

release

public void release()

release is called by RTAudio when the RTLine is ready to start processing data again. This is required so that all instruments in turn provide the buffer they are currently processing to the real time audio stream

block

public void block()

block is called to hold any further processing untill all instruments are in the same place (in time that is). Block calls wait on this instrument and is released by a call to release. The RTAudio class is responsible for handling all block and release calls.

createChain

public abstract void createChain()
                          throws AOException

This method is automatically called on startup to initialise any AudioObjects used by this instrument

Throws:

AOException

iterateChain

public void iterateChain()

The iterate chain method is resposible for pulling the appropriate number of samples through the audio chain.