arb.soundcipher
Class SoundCipher

java.lang.Object
  arb.soundcipher.SCUtilities
      arb.soundcipher.SoundCipher

All Implemented Interfaces:

DrumMap, MidiMessageTypes, PitchClassSets, ProgramChanges

public class SoundCipher
extends SCUtilities
implements ProgramChanges, DrumMap, PitchClassSets, MidiMessageTypes

The SoundCipher class provides an easy way to play music in Processing. It has methods for playing a single note, a phrase (a sequence of notes), or a chord (a cluster of notes) using JavaSound's built-in synthesizer or via MIDI output to an external synthesizer. The class also provides methods for simple playback of a specified audio file. The SCScore class is used to provide musical data structure and timing of events.

Below is a simple Processing example using the SoundCipher library:


 import arb.soundcipher.*;
 
 SoundCipher sc = new SoundCipher();
 int[] scale = {57, 60, 60, 62, 64, 67, 67, 69, 72};
 
 void setup() {
     frameRate(8);
 }
 
 void draw() {
     if (random(1) < 0.8) {
         sc.playNote(scale[(int)random(scale.length)], (int)random(80)+40, 0.2);
         stroke(color(random(256), random (256), random(256)));
         rect(random(100), random(100), random(40), random(40));
     }
 }
 

SoundCipher does not provide sound synthesis or audio recording functions, for these we suggest using the Minim library which can be integrated with SoundCipher when required.

Author:

Andrew R. Brown

Field Summary

PApplet	app A reference to the Processing application used to communicate with it
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	instrument Specifies the default instrument to 0 [0 - 127] (0 = piano on the JavaSound synthesizer)
double	pan Specifies the default pan poisition to be 64, in the centre [0 - 127]
double	repeat Specifies the defult number of repeats for score playback [-1 = infinite]
SCScore	score Creates an instance of the SCScore class for use behind the scenes
double	tempo Specifies the default tempo (speed) to the 120 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

SoundCipher()
An alternative constructor for using SoundCipher outside of Processing.

SoundCipher(PApplet processingInstance)
The normal constructor used for SoundCipher as a Processing Library.

Method Summary

void	channel(double channelNumber) Specifies the default channel number [0-15].
static void	getMidiDeviceInfo() Report the availible MIDI devices.
void	instrument(double instrumentNumber) Specifies the default instrument number [0-127].
java.applet.AudioClip	loadAudioClip(java.lang.String fileLocation) Load a specified audio file using the Applet class.
void	loopAudioClip(java.applet.AudioClip clip) Repeat indefinitly the specified audio clip.
void	loopAudioClip(java.lang.String fileLocation) Load a specified audio file into memory and play it repeatedly using the Applet class.
void	pan(int newPanVal) Specifies the default pan position [0-127].
void	playAudioClip(java.applet.AudioClip clip) Playback a previously loaded audio clip.
void	playAudioClip(java.lang.String fileLocation) Load a specified audio file into memory and play using the Applet class.
void	playAudioFile(java.lang.String fileName) Stream playback of a specified audio file using JavaSound.
void	playChord(double startBeat, double channel, double instrument, float[] pitches, double dynamic, double duration, double articulation, double pan) Schedules a note cluster (chord) for playback.
void	playChord(float[] pitches, double dynamic, double duration) Schedules a note cluster (chord) for immediate playback.
void	playMidiFile(java.lang.String fileName)
void	playMidiFile(java.lang.String fileName, double tempo)
void	playNote(double pitch, double dynamic, double duration) Creates a single note for immediate playback.
void	playNote(double startBeat, double channel, double instrument, double pitch, double dynamic, double duration, double articulation, double pan) Schedules a single note for playback.
void	playPhrase(double[] pitches, double[] dynamics, double[] durations) Creates a note sequence for immediate playback.
void	playPhrase(double startBeat, double channel, double instrument, double[] pitches, double[] dynamics, double[] durations, double[] articulations, double[] pans) Schedules a note sequence for playback.
void	playPhrase(float[] pitches, float[] dynamics, float[] durations) Creates a note sequence for immediate playback.
void	repeat(double newRepeatVal) Specifies the default number of repeatitions of the score on playback.
void	sendMidi(int type, double channel, double val1, double val2) Transmit a MIDI message immediatly.
void	sendOSC() Transmit an Open Sound Control message immediatly.
void	setMidiDeviceOutput(int deviceNumber) Specify the MIDI device to be used by SoundCipher.
void	stop() Halt any playing note, phrase, chord or audioClip.
void	stopAudioClip() Halt the playing audio clip
void	stopAudioClip(java.applet.AudioClip clip) Halt the specified audio clip
void	tempo(double newTempo) Specifies the default tempo (speed).

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

score

public SCScore score

Creates an instance of the SCScore class for use behind the scenes

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]

tempo

public double tempo

Specifies the default tempo (speed) to the 120 beats per minute

pan

public double pan

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

repeat

public double repeat

Specifies the defult number of repeats for score playback [-1 = infinite]

articulation

public double articulation

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

app

public PApplet app

A reference to the Processing application used to communicate with it

Constructor Detail

SoundCipher

public SoundCipher(PApplet processingInstance)

The normal constructor used for SoundCipher as a Processing Library. The PApplet instance provides a link to the Processing application and is used to access the class path for loading files and so on.

Parameters:

processingInstance - The current Processing instance (normally pass 'this' here).

SoundCipher

public SoundCipher()

An alternative constructor for using SoundCipher outside of Processing. A Warning!! When using this constructor the audio methods expect explicit path and file name arguments, rather than filenames assumed to be relative to the Processing 'data' folder associated with the sketch file.

Method Detail

playNote

public void playNote(double pitch,
                     double dynamic,
                     double duration)

Creates a single note for immediate playback.

Parameters:

pitch - The MIDI pitch 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

playNote

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

Schedules a single note for playback.

Parameters:

startBeat - Specifies when the note will play, in beats, after code execution

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 duration that the note will sound, in beats

articulation - A length multiplier for duration (0.8 by default)

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

playPhrase

public void playPhrase(float[] pitches,
                       float[] dynamics,
                       float[] durations)

Creates a note sequence for immediate playback.

Parameters:

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 length that each note will sound, in beats

playPhrase

public void playPhrase(double[] pitches,
                       double[] dynamics,
                       double[] durations)

Creates a note sequence for immediate playback.

Parameters:

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 length that each note will sound, in beats

playPhrase

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

Schedules a note sequence for playback.

Parameters:

startBeat - Specifies when the notes will play, in beats, after code execution

channel - The MIDI channel to use for these notes [0-15]

instrument - The JavaSound instrument (sound) to use for these notes [0-127]

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

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

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

articulations - Length multipliers for each duration (0.8 by default)

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

playChord

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

Schedules a note cluster (chord) for immediate playback.

Parameters:

pitches - The MIDI pitches (frequencies) 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

playChord

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

Schedules a note cluster (chord) for playback.

Parameters:

startBeat - Specifies when the notes will play, in beats, after code execution

channel - The MIDI channel to use for these notes [0-15]

instrument - The JavaSound instrument (sound) to use for these notes [0-127]

pitches - The MIDI pitches (frequencies) 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 - A length multiplier for duration (0.8 by default)

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

instrument

public void instrument(double instrumentNumber)

Specifies the default instrument number [0-127].

channel

public void channel(double channelNumber)

Specifies the default channel number [0-15].

tempo

public void tempo(double newTempo)

Specifies the default tempo (speed).

pan

public void pan(int newPanVal)

Specifies the default pan position [0-127].

repeat

public void repeat(double newRepeatVal)

Specifies the default number of repeatitions of the score on playback. -1 = infinite

getMidiDeviceInfo

public static void getMidiDeviceInfo()

Report the availible MIDI devices. Prints the list of devices and id info to the console. For external MIDI device info. to be accessible on Mac OSX you need to install Bob Lang's Mandalone Java extension. http://www.mandolane.co.uk/ An alternative that uses CoreMIDI but does not work directly with this code is mmj. http://www.humatic.de/htools/mmj.htm - not compatible with OS X Java 1.6 : (

setMidiDeviceOutput

public void setMidiDeviceOutput(int deviceNumber)

Specify the MIDI device to be used by SoundCipher. To see the availible devices and their device number use getMidiDeviceInfo().

Parameters:

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

playMidiFile

public void playMidiFile(java.lang.String fileName)

playMidiFile

public void playMidiFile(java.lang.String fileName,
                         double tempo)

sendMidi

public void sendMidi(int type,
                     double channel,
                     double val1,
                     double val2)

Transmit a MIDI message immediatly.

Parameters:

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)

sendOSC

public void sendOSC()

Transmit an Open Sound Control message immediatly.

playAudioFile

public void playAudioFile(java.lang.String fileName)

Stream playback of a specified audio file using JavaSound. Audio files are assumed to be in a folder named 'data' in the processing file directory. Audio reading of MP3 files may not work for Processing Applets. Use the Minim library for more robust audio handling.

Parameters:

fileName - Name of audio file.

loadAudioClip

public java.applet.AudioClip loadAudioClip(java.lang.String fileLocation)

Load a specified audio file using the Applet class. Use playAudioClip(AudioClip clip) to load and play in one process. Audio files are assumed to be in a 'data' folder in the processing file directory. Audio reading of files may not work for Processing Applets. Use the Minim library for more robust audio handling.

Parameters:

fileLocation - Path and name of audio file. Absolute file path required.

Returns:

An AudioClip object for use by playAudioClip()

playAudioClip

public void playAudioClip(java.applet.AudioClip clip)

Playback a previously loaded audio clip.

Parameters:

clip - The audioclip object loaded by loadAudioClip()

playAudioClip

public void playAudioClip(java.lang.String fileLocation)

Load a specified audio file into memory and play using the Applet class. Audio files are assumed to be in a folder called 'data' in the processing file directory. Audio reading of files may not work for Processing Applets. Use the Minim library for more robust audio handling.

Parameters:

fileLocation - Path and name of audio file. Absolute file path required.

stopAudioClip

public void stopAudioClip(java.applet.AudioClip clip)

Halt the specified audio clip

Parameters:

clip - A previously created AudioClip object

stopAudioClip

public void stopAudioClip()

Halt the playing audio clip

loopAudioClip

public void loopAudioClip(java.applet.AudioClip clip)

Repeat indefinitly the specified audio clip. Use stopAudioClip() to halt playback.

Parameters:

AudioClip - A previously loaded AudioClip object

loopAudioClip

public void loopAudioClip(java.lang.String fileLocation)

Load a specified audio file into memory and play it repeatedly using the Applet class. Audio files are assumed to be in a folder called 'data' in the processing file directory. Audio reading of files may not work for Processing Applets. Use the Minim library for more robust audio handling. Use stopAudioClip() to halt looping.

Parameters:

fileLocation - Path and name of audio file. Absolute file path required.

stop

public void stop()

Halt any playing note, phrase, chord or audioClip.