arb.soundcipher
Class SCScore

java.lang.Object
  arb.soundcipher.SCUtilities
      arb.soundcipher.SCScore

All Implemented Interfaces:

DrumMap, MidiMessageTypes, PitchClassSets, ProgramChanges, java.util.EventListener, javax.sound.midi.MetaEventListener

public class SCScore
extends SCUtilities
implements javax.sound.midi.MetaEventListener, ProgramChanges, DrumMap, PitchClassSets, MidiMessageTypes

The SCScore class provides music data structure and scheduling services. It is part of the SoundCipher library for Processing. A score can contain notes, phrases (note sequences), chords (note clusters), or 'callbacks.' A score can be played back once, repeated or looped. Notes in a score play back using the internal JavaSound soundbank, MIDI Events (note messages) are sent to the active MIDI device, while Scheduled Events provide a callback into Processing for any arbitary synchronised purpose (e.g. audio file playback, drawing, sound synthesis parameter control, and OSC or MIDI message sending). When using a SCScore instance always include a stop() method in your Processing program to halt playback when the program exits. Like so, assuming your SCScore instance is called score.
void stop() {
score.stop();
}


Author:

Andrew R. Brown

Field Summary

double	articulation Specifies the amount of duration that will sound, e.g., 0.2 = stacatto, 1.0 = legato
double	channel Specifies the default MIDI channel to 0 [0-15]
double	denominator The lower number of the score's time signature.
double	instrument Specifies the default instrument to 0 [0 - 127] (0 = piano on the JavaSound synthesizer)
double	numerator The top number of the score's time signature.
double	pan Specifies the default pan poisition to be 64, in the centre [0 - 127]
boolean	playing A flag to indicate if the score is currently playing.
double	repeat The default number of repeats on score playback, 0.
double	repeatCounter The number of repeats a score has played
protected javax.sound.midi.Sequencer	sequencer A JavaSound Sequencer instance.
double	tempo The default tempo to the score, 120.0 beats per minute.

Fields inherited from interface arb.soundcipher.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, 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, 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, STRINGS, SWEEP, SWEEP_PAD, SYN_CALLIOPE, SYN_STRINGS, SYNTH_BASS, SYNTH_BRASS, SYNTH_CALLIOPE, SYNTH_DRUM, SYNTH_DRUMS, SYNTH_STRINGS, 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 arb.soundcipher.constants.DrumMap

ACOUSTIC_BASS_DRUM, ACOUSTIC_SNARE, BASS_DRUM, CABASA, CHINESE_CYMBAL, CLAVES, CLOSED_HI_HAT, COWBELL, CRASH, CRASH_CYMBAL_1, CRASH_CYMBAL_2, ELECTRIC_SNARE, HAND_CLAP, HI_BONGO, HI_HAT, HI_MID_TOM, HI_WOOD_BLOCK, HIGH_AGOGO, HIGH_FLOOR_TOM, HIGH_TIMBALE, HIGH_TOM, HIHAT, KICK, KICK_DRUM, 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, RIDE_BELL, RIDE_CYMBAL_1, RIDE_CYMBAL_2, SHORT_GUIRO, SHORT_WHISTLE, SIDE_STICK, SNARE, SNARE_DRUM, SPLASH_CYMBAL, TAMBOURINE, TRIANGLE, VIBRASLAP

Fields inherited from interface arb.soundcipher.constants.PitchClassSets

AEOLIAN, AUGMENTED, BLUES, CHROMATIC, DIATONIC_MINOR, DORIAN, HARMONIC_MINOR, INDIAN, IONIAN, LOCRIAN, LYDIAN, MAJOR, MAJOR_PENTATONIC, MAJOR_TRIAD, MELODIC_MINOR, MINOR, MINOR_PENTATONIC, MINOR_TRIAD, MIXOLYDIAN, NATURAL_MINOR, PENTATONIC, PHRYGIAN, ROOT, ROOT_FIFTH, TURKISH, WHOLETONE

Fields inherited from interface arb.soundcipher.constants.MidiMessageTypes

ACTIVE_SENSING, CHANNEL_PRESSURE, CONTROL_CHANGE, END_OF_EXCLUSIVE, MIDI_TIME_CODE, NOTE_OFF, NOTE_ON, PITCH_BEND, POLY_PRESSURE, PROGRAM_CHANGE, SONG_POSITION_POINTER, SONG_SELECT, START, STOP, SYSTEM_RESET, TIMING_CLOCK, TUNE_REQUEST

Constructor Summary

SCScore()
Creates a empty SoundCipher Score (SCScore) object.

Method Summary

void	addCallback(double startBeat, int callbackID) Schedules an callback event within the score.
void	addCallbackListener(PApplet pa) Register a listener with Processing to parse scheduled callbacks generated by the score when played.
void	addChord(double startBeat, double channel, double instrument, float[] pitches, double dynamic, double duration, double articulation, double pan) Schedules a note cluster (chord) within the score.
void	addChord(double startBeat, float[] pitches, double dynamic, double duration) Schedules a note cluster (chord) within the score.
void	addMidiFile(java.lang.String filePath) Read a MIDI file into a SoundCipher score
void	addMIDIMessage(double startBeat, int type, double channel, double val1, double val2) Creates a single MIDI message and adds it to the score.
void	addMidiStream(java.io.InputStream is) Read a MIDI file input stream into a SoundCipher score
void	addNote(double startBeat, double pitch, double dynamic, double duration) Schedules a single note in the score.
void	addNote(double startBeat, double channel, double instrument, double pitch, double dynamic, double duration, double articulation, double pan) Schedules a single note in the score.
void	addPhrase(double startBeat, double channel, double instrument, double[] pitches, double[] dynamics, double[] durations, double[] articulations, double[] pans) Schedules a note sequence (phrase) within the score.
void	addPhrase(double startBeat, double channel, double instrument, float[] pitches, float[] dynamics, float[] durations, float[] articulations, float[] pans) Schedules a note sequence (phrase) within the score.
void	channel(double newChan) Specify the default channel for notes added to this score.
void	denominator(double value) Specify the lower number of the time signture for this score.
void	empty() Remove all data from the score.
void	instrument(double newInst) Specify the default instrument for notes added to this score.
boolean	isPlaying() A conditional that indicates if the score is currently playing.
void	meta(javax.sound.midi.MetaMessage message) The MetaMessage callback handler.
void	numerator(double value) Specify the top number of the time signture for this score.
void	pan(double newPos) Specify the default pan position for notes added to this score.
void	play() Start the Score playback.
void	play(double repeat) Start the Score playback.
void	play(double repeat, double tempo) Start the Score playback.
void	repeat(double repeat) Specify the number of repetitions for the score (-1 = infinite loop)
javax.sound.midi.Sequencer	sequencer() Retreive the Sequencer object used by this SCScore.
void	setMidiDeviceOutput(int deviceNumber) Specify the MIDI device to be used for score playback.
void	stop() Halt the score playback.
void	tempo(double newTempo) Specify the speed (tempo) of the score in beats per minute
void	update() Refresh the sequence data and start time of the score.
void	writeMidiFile(java.lang.String filePath) Save the score as a MIDI file

Methods inherited from class arb.soundcipher.SCUtilities

gaussian, midiToFreq, midiToFreq, pcGaussianWalk, pcRandom, pcRandom, pcRandomWalk, pcRandomWalk

Methods inherited from class java.lang.Object

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

Field Detail

sequencer

protected javax.sound.midi.Sequencer sequencer

A JavaSound Sequencer instance.

tempo

public double tempo

The default tempo to the score, 120.0 beats per minute.

repeat

public double repeat

The default number of repeats on score playback, 0. -1 indicates infinite repeats (looping).

repeatCounter

public double repeatCounter

The number of repeats a score has played

playing

public boolean playing

A flag to indicate if the score is currently playing.

instrument

public double instrument

Specifies the default instrument to 0 [0 - 127] (0 = piano on the JavaSound synthesizer)

channel

public double channel

Specifies the default MIDI channel to 0 [0-15]

pan

public double pan

Specifies the default pan poisition to be 64, in the centre [0 - 127]

articulation

public double articulation

Specifies the amount of duration that will sound, e.g., 0.2 = stacatto, 1.0 = legato

numerator

public double numerator

The top number of the score's time signature.

denominator

public double denominator

The lower number of the score's time signature.

Constructor Detail

SCScore

public SCScore()

Creates a empty SoundCipher Score (SCScore) object. A SCScore is an enhanced and easy to use wrapper for a JavaSound sequencer.

Method Detail

channel

public void channel(double newChan)

Specify the default channel for notes added to this score.

Parameters:

newChan - The value to set the channel to, from 0-15.

instrument

public void instrument(double newInst)

Specify the default instrument for notes added to this score.

Parameters:

newChan - The value to set the instrument to, from 0-15.

pan

public void pan(double newPos)

Specify the default pan position for notes added to this score.

Parameters:

newPos - The value to set the pan psotion to, from 0 - 127.

numerator

public void numerator(double value)

Specify the top number of the time signture for this score.

Parameters:

value - The value for the numerator, whole number greater than 0.

denominator

public void denominator(double value)

Specify the lower number of the time signture for this score.

Parameters:

value - The value for the denamonator, whole number greater than 0.

tempo

public void tempo(double newTempo)

Specify the speed (tempo) of the score in beats per minute

Parameters:

newTempo - The new tempo value.

play

public void play()

Start the Score playback.

play

public void play(double repeat)

Start the Score playback.

Parameters:

repeat - The number of repeats (-1 = infinite)

play

public void play(double repeat,
                 double tempo)

Start the Score playback.

Parameters:

repeat - The number of repeats (-1 = infinite)

tempo - The playback speed in beats per minute

stop

public void stop()

Halt the score playback.

update

public void update()

Refresh the sequence data and start time of the score. An update is required if data is dynamically added to the score while it is playing.

empty

public void empty()

Remove all data from the score.

repeat

public void repeat(double repeat)

Specify the number of repetitions for the score (-1 = infinite loop)

Parameters:

repeat - The new repeat value.

isPlaying

public boolean isPlaying()

A conditional that indicates if the score is currently playing.

Returns:

True or False

sequencer

public javax.sound.midi.Sequencer sequencer()

Retreive the Sequencer object used by this SCScore.

Returns:

A JavaSound sequencer object

addNote

public void addNote(double startBeat,
                    double pitch,
                    double dynamic,
                    double duration)

Schedules a single note in the score. This reduced-argument version of the method can be useful for creating scores where all notes are on a same MIDI channel, instrument, articulation and pan settings.

Parameters:

startBeat - Specifies when the note will play, in beats, after the score starts

pitch - The MIDI pitch (frequency) at which the note will play [0-127]

dynamic - The loudness, MIDI velocity, of the note [0-127]

duration - The length that the note will sound, in beats

addNote

public void addNote(double startBeat,
                    double channel,
                    double instrument,
                    double pitch,
                    double dynamic,
                    double duration,
                    double articulation,
                    double pan)

Schedules a single note in the score.

Parameters:

startBeat - Specifies when the note will play, in beats, after the score starts

channel - The MIDI channel to use for this note [0-15]

instrument - The JavaSound instrument (sound) to use for this note [0-127]

pitch - The MIDI pitch (frequency) at which the note will play [0-127]

dynamic - The loudness, MIDI velocity, of the note [0-127]

duration - The length that the note will sound, in beats

articulation - An articulation multiplier for duration (0.8 by default)

pan - The note's left-right location in the stereo field [0-127]

addPhrase

public void addPhrase(double startBeat,
                      double channel,
                      double instrument,
                      float[] pitches,
                      float[] dynamics,
                      float[] durations,
                      float[] articulations,
                      float[] pans)

Schedules a note sequence (phrase) within the score.

Parameters:

startBeat - Specifies when the phrase will start to play, in beats, after the score starts

channel - The MIDI channel to use for this note [0-15]

instrument - The JavaSound instrument (sound) to use for this note [0-127]

pitches - The MIDI pitches (frequencies) at which the note will play [0-127]

dynamics - The loudness, MIDI velocity, of each note [0-127]

durations - The lengths that each note will sound, in beats

articulations - An articulation multiplier for each duration (0.8 by default)

pans - Each note's left-right location in the stereo field [0-127]

addPhrase

public void addPhrase(double startBeat,
                      double channel,
                      double instrument,
                      double[] pitches,
                      double[] dynamics,
                      double[] durations,
                      double[] articulations,
                      double[] pans)

Schedules a note sequence (phrase) within the score.

Parameters:

startBeat - Specifies when the phrase will start to play, in beats, after the score starts

channel - The MIDI channel to use for this note [0-15]

instrument - The JavaSound instrument (sound) to use for this note [0-127]

pitches - The MIDI pitches (frequencies) at which the note will play [0-127]

dynamics - The loudness, MIDI velocity, of each note [0-127]

durations - The lengths that each note will sound, in beats

articulations - An articulation multiplier for each duration (0.8 by default)

pans - Each note's left-right location in the stereo field [0-127]

addChord

public void addChord(double startBeat,
                     float[] pitches,
                     double dynamic,
                     double duration)

Schedules a note cluster (chord) within the score.

Parameters:

startBeat - Specifies when the notes will play, in beats, after the score starts

pitches - Arracy of MIDI pitches for each note [0-127]

dynamic - The loudness, MIDI velocity, of the notes [0-127]

duration - The length that the notes will sound, in beats

addChord

public void addChord(double startBeat,
                     double channel,
                     double instrument,
                     float[] pitches,
                     double dynamic,
                     double duration,
                     double articulation,
                     double pan)

Schedules a note cluster (chord) within the score.

Parameters:

startBeat - Specifies when the notes will play, in beats, after the score starts

channel - The MIDI channel to use for this note [0-15]

instrument - The JavaSound instrument (sound) to use for this note [0-127]

pitches - An array of MIDI pitches for each note [0-127]

dynamic - The loudness, MIDI velocity, of the notes [0-127]

duration - The length that the notes will sound, in beats

articulation - An articulation multiplier for duration (0.8 by default)

pan - The note's left-right location in the stereo field [0-127]

addCallback

public void addCallback(double startBeat,
                        int callbackID)

Schedules an callback event within the score.

Parameters:

startBeat - Specifies when the callback will be triggered, in beats, after the score starts.

callbackID - The identifier for this event, which is passed as part of the callback.

addMIDIMessage

public void addMIDIMessage(double startBeat,
                           int type,
                           double channel,
                           double val1,
                           double val2)

Creates a single MIDI message and adds it to the score.

Parameters:

startBeat - Specifies when the message will be sent, in beats, after the score starts

type - The MIDI message status value; the type of message to add (control change, pitch bend etc.)

channel - The MIDI channel to use for this message [0-15]

val1 - The first byte of data (e.g., control change number)

val2 - The second byte of data (e.g., control change value)

addMidiFile

public void addMidiFile(java.lang.String filePath)

Read a MIDI file into a SoundCipher score

Parameters:

filePath - Path and name of the MIDI file. Absolute file path required.

addMidiStream

public void addMidiStream(java.io.InputStream is)

Read a MIDI file input stream into a SoundCipher score

Parameters:

is - The InputStream for the MIDI file.

writeMidiFile

public void writeMidiFile(java.lang.String filePath)

Save the score as a MIDI file

Parameters:

filePath - Path and name of the MIDI file to be written. Absolute file path required

setMidiDeviceOutput

public void setMidiDeviceOutput(int deviceNumber)

Specify the MIDI device to be used for score playback.

Parameters:

deviceNumber - The id of the MIDI output as returned from getMidiDeviceInfo()

addCallbackListener

public void addCallbackListener(PApplet pa)

Register a listener with Processing to parse scheduled callbacks generated by the score when played. The program needs to override the method;
void handleCallbacks(int eventID);
which is called each time a callback is triggered during score playback. EventIDs are used to distinguish between different callback types and are allocated at the programmers discretion.

Parameters:

pa - The Processing Applet object

meta

public void meta(javax.sound.midi.MetaMessage message)

The MetaMessage callback handler. Parses callback from events when the score is played.

Specified by:

meta in interface javax.sound.midi.MetaEventListener

Parameters:

message - The MetaMessage object passed from JavaSound during sequence playback