Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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) { }

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

### VERSION

    public static final byte VERSION

  The VERSION attribute tag.

  Value -2 is assigned to `VERSION`.

### TEMPO

    public static final byte TEMPO

  The TEMPO event tag.

  Value -3 is assigned to `TEMPO`.

### RESOLUTION

    public static final byte RESOLUTION

  The RESOLUTION event tag.

  Value -4 is assigned to `RESOLUTION`.

### BLOCK_START

    public static final byte BLOCK_START

  Defines a starting point for a block.

  Value -5 is assigned to `BLOCK_START`.

### BLOCK_END

    public static final byte BLOCK_END

  Defines an ending point for a block.

  Value -6 is assigned to `BLOCK_END`.

### PLAY_BLOCK

    public static final byte PLAY_BLOCK

  Play a defined block.

  Value -7 is assigned to `PLAY_BLOCK`.

### SET_VOLUME

    public static final byte SET_VOLUME

  The SET_VOLUME event tag.

  Value -8 is assigned to `SET_VOLUME`.

### REPEAT

    public static final byte REPEAT

  The REPEAT event tag.

  Value -9 is assigned to `REPEAT`.

### C4

    public static final byte C4

  Middle C.

  Value 60 is assigned to `C4`.

### SILENCE

    public static final byte SILENCE

  Silence.

  Value -1 is assigned to `SILENCE`.

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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD