javax.microedition.media.control
Interface ToneControl

All Superinterfaces:
Control

public interface ToneControl
extends Control

ToneControl is the interface to enable playback of a user-defined monotonic tone sequence.

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.
 
VERSION, TEMPO, RESOLUTION, BLOCK_START, BLOCK_END, PLAY_BLOCK SET_VOLUME REPEAT are pre-defined constants.

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 - -

The frequency of the note can be calculated from the following formula:
     SEMITONE_CONST = 17.31234049066755 = 1/(ln(2^(1/12)))
     note = ln(freq/8.176)*SEMITONE_CONST
 
The musical note A = note 69 (0x45) = 440 Hz.
Middle C (C4) and SILENCE are defined as constants.

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)
 
The following table lists some common durations in musical notes:
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) { }

 

Since:
JDE 4.0.0

Field Summary
static byte BLOCK_END
          Defines an ending point for a block.
static byte BLOCK_START
          Defines a starting point for a block.
static byte C4
          Middle C.
static byte PLAY_BLOCK
          Play a defined block.
static byte REPEAT
          The REPEAT event tag.
static byte RESOLUTION
          The RESOLUTION event tag.
static byte SET_VOLUME
          The SET_VOLUME event tag.
static byte SILENCE
          Silence.
static byte TEMPO
          The TEMPO event tag.
static byte VERSION
          The VERSION attribute tag.
 
Method Summary
 void setSequence(byte[] sequence)
          Sets the tone sequence.
 

Field Detail

BLOCK_END

public static final byte BLOCK_END
Defines an ending point for a block.

Value -6 is assigned to BLOCK_END.

Since:
JDE 4.0.0

BLOCK_START

public static final byte BLOCK_START
Defines a starting point for a block.

Value -5 is assigned to BLOCK_START.

Since:
JDE 4.0.0

C4

public static final byte C4
Middle C.

Value 60 is assigned to C4.

Since:
JDE 4.0.0

PLAY_BLOCK

public static final byte PLAY_BLOCK
Play a defined block.

Value -7 is assigned to PLAY_BLOCK.

Since:
JDE 4.0.0

REPEAT

public static final byte REPEAT
The REPEAT event tag.

Value -9 is assigned to REPEAT.

Since:
JDE 4.0.0

RESOLUTION

public static final byte RESOLUTION
The RESOLUTION event tag.

Value -4 is assigned to RESOLUTION.

Since:
JDE 4.0.0

SET_VOLUME

public static final byte SET_VOLUME
The SET_VOLUME event tag.

Value -8 is assigned to SET_VOLUME.

Since:
JDE 4.0.0

SILENCE

public static final byte SILENCE
Silence.

Value -1 is assigned to SILENCE.

Since:
JDE 4.0.0

TEMPO

public static final byte TEMPO
The TEMPO event tag.

Value -3 is assigned to TEMPO.

Since:
JDE 4.0.0

VERSION

public static final byte VERSION
The VERSION attribute tag.

Value -2 is assigned to VERSION.

Since:
JDE 4.0.0
Method Detail

setSequence

public void setSequence(byte[] sequence)
Sets the tone sequence.

Parameters:
sequence - The sequence to set.
Throws:
IllegalArgumentException - Thrown if the sequence is null or invalid.
IllegalStateException - Thrown if the Player that this control belongs to is in the PREFETCHED or STARTED state.
Since:
JDE 4.0.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.