ToneControl

A tone sequence is specified as a list of tone-duration pairs and user-defined sequence blocks. The list is packaged as an array of bytes. The setSequence method is used to input the sequence to the ToneControl.

The syntax of a tone sequence is described in Augmented BNF notations:

sequence = version *1tempo_definition *1resolution_definition
*block_definition 1*sequence_event

version = VERSION version_number
VERSION = byte-value
version_number = 1 ; version # 1

tempo_definition = TEMPO tempo_modifier
TEMPO = byte-value
tempo_modifier = byte-value
; multiply by 4 to get the tempo (in bpm) used
; in the sequence.

resolution_definition = RESOLUTION resolution_unit
RESOLUTION = byte-value
resolution_unit = byte-value

block_definition = BLOCK_START block_number
1*sequence_event
BLOCK_END block_number
BLOCK_START = byte-value
BLOCK_END = byte-value
block_number = byte-value
; block_number specified in BLOCK_END has to be the
; same as the one in BLOCK_START

sequence_event = tone_event / block_event /
volume_event / repeat_event

tone_event = note duration
note = byte-value ; note to be played
duration = byte-value ; duration of the note

block_event = PLAY_BLOCK block_number
PLAY_BLOCK = byte-value
block_number = byte-value
; block_number must be previously defined
; by a full block_definition

volume_event = SET_VOLUME volume
SET_VOLUME = byte-value
volume = byte-value ; new volume

repeat_event = REPEAT multiplier tone_event
REPEAT = byte-value
multiplier = byte-value
; number of times to repeat a tone

byte-value = -128 - 127
; the value of each constant and additional
; constraints on each parameter are specified below.

Following table shows the valid range of the parameters:

Parameter	Valid Range	Effective Range	Default
tempo_modifier	5<= tempo_modifier <= 127	20bpm to 508bpm	120bpm
resolution_unit	1<= resolution_unit <= 127	1/1 note to 1/127 note	1/64 note
block_number	0<= block_number <= 127	-	-
note	0<= note <= 127 or SILENCE	C-1 to G9 or rest	-
duration	1<= duration <= 127	-	-
volume	0<= volume <= 100	0% to 100% volume	100%
multiplier	2<= multiplier <= 127	-	-

SEMITONE_CONST = 17.31234049066755 = 1/(ln(2^(1/12)))
note = ln(freq/8.176)*SEMITONE_CONST

The duration of each tone is measured in units of 1/resolution notes and tempo is specified in beats/minute, where 1 beat = 1/4 note. Because the range of positive values of byte is only 1 - 127, the tempo is formed by multiplying the tempo modifier by 4. Very slow tempos are excluded so range of tempo modifiers is 5 - 127 providing an effective range of 20 - 508 bpm.

To compute the effective duration in milliseconds for a tone, the following formula can be used:

duration * 60 * 1000 * 4 / (resolution * tempo)

Note Length	Duration, Resolution=64	Duration, Resolution=96
1/1	64	96
1/4	16	24
1/4 dotted	24	36
1/8	8	12
1/8 triplets	-	8
4/1	REPEAT 4 <note> 64	REPEAT 4 <note> 96

Example

// "Mary Had A Little Lamb" has "ABAC" structure.
// Use block to repeat "A" section.

byte tempo = 30; // set tempo to 120 bpm
byte d = 8; // eighth-note

byte C4 = ToneControl.C4;;
byte D4 = (byte)(C4 + 2); // a whole step
byte E4 = (byte)(C4 + 4); // a major third
byte G4 = (byte)(C4 + 7); // a fifth
byte rest = ToneControl.SILENCE; // rest

byte[] mySequence = {
ToneControl.VERSION, 1, // version 1
ToneControl.TEMPO, tempo, // set tempo
ToneControl.BLOCK_START, 0, // start define "A" section
E4,d, D4,d, C4,d, E4,d, // content of "A" section
E4,d, E4,d, E4,d, rest,d,
ToneControl.BLOCK_END, 0, // end define "A" section
ToneControl.PLAY_BLOCK, 0, // play "A" section
D4,d, D4,d, D4,d, rest,d, // play "B" section
E4,d, G4,d, G4,d, rest,d,
ToneControl.PLAY_BLOCK, 0, // repeat "A" section
D4,d, D4,d, E4,d, D4,d, C4,d // play "C" section
};

try{
Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR);
p.realize();
ToneControl c = (ToneControl)p.getControl("ToneControl");
c.setSequence(mySequence);
p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }