Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package javax.microedition.media

The MIDP 2.0 Media API is a directly compatible building block of the Mobile Media API (JSR-135) specification.

See:
Description

Interface Summary
Control | A `Control` object is used to control some media processing functions.
Controllable | `Controllable` provides an interface for obtaining the `Control`s from an object like a `Player`.
Player | `Player` controls the rendering of time based media data.
PlayerListener | `PlayerListener` is the interface for receiving asynchronous events generated by `Players`.

Class Summary
Manager | `Manager` is the access point for obtaining system dependent resources such as `Players` for multimedia processing.

Exception Summary
MediaException | A `MediaException` indicates an unexpected error condition in a method.

## Package javax.microedition.media Description

The MIDP 2.0 Media API is a directly compatible building block of the Mobile Media API (JSR-135) specification. The use of this building block is intended for J2METM profiles aiming to include sound support in the specification, while maintaining upwards compatibility with the full Multimedia API. Such specification example is MIDP 2.0 (JSR-118). The development of these two interoperable API's enables seamless sound and multimedia content creation across the J2METM range of devices using the same API principles.

### Introduction

> J2METM devices range from cell phones with simple tone generation to PDAs and Web tablets with advanced audio and video rendering capabilities. To accommodate diverse configurations and multimedia processing capabilities, an API with a high level of abstraction is needed. The goal of the MMAPI Expert Group work has been to address this wide range of application areas, and the result of the work is a proposal of two API sets:
> - Mobile Media API (JSR 135)
> - MIDP 2.0 Media API
> The first API is intended for J2METM devices with advanced sound and multimedia capabilities, including powerful mobile phones, PDAs, and set-top boxes, for example. The latter API is a directly compatible subset of the Multimedia API, and is intended for resource-constrained devices such as mass-market mobile devices (running MIDP 2.0). Furthermore, this subset API can be adopted to other J2METM profiles requiring sound support. In the following, a more detailed description of the background and requirements of the building block API is given.

## Background of the Media API

> Some J2METM devices are very resource constrained. It may not be feasible for a device to support a full range of multimedia types, such as video on some cell phones. As a result, not all devices are required to support the full generality of a multimedia API, such as extensibility to support custom protocols and content types.

> The proposed builidng block subset API has been designed to meet the above constraints. This proposed building block fulfills the requirements set by the MIDP 2.0 Expert Group. These requirements include:

> - Low footprint audio playback
> - Protocol and content format agnostic
> - Supports tone generation
> - Supports general media flow controls: start, stop, etc.
> - Supports media-specific type controls: volume etc.
> - Supports capability query
> This subset differs from the full Mobile Media API in the following ways:
> - It is audio-only. It excludes all Controls specific to video or graphics.
> - It does not support custom protocols via custom DataSources. The javax.microedition.media.protocol package (DataSource) is excluded.

> It is important to note that the building block subset used in MIDP 2.0 is a proper subset of the full Mobile Media API and is fully forward compatible. In order to get the full Mobile Media API functionality into MIDP 2.0 one needs to only implement the additional classes and methods from that API.

### Basic Concepts

> The proposed audio building block system constists of three main parts.

> > - `Manager`
> > - `Player`
> > - `Control`

> The`Manager` is the top level controller of audio resources. Applications use `Manager` to request `Players` and to query properties, supported content types and supported protocols. The manager also includes a method to play simple tones.

> The`Player` plays the multimedia content. The application obtains a `Player` by giving the locator string to `Manager`.

> `A Control` is an interface that is used to implement all different controls a `Player` might have. An application can query a `Player` of controls it supports and then ask for a specific `Control` e.g. `VolumeControl` to control volume.

### API Details

> The `createPlayer` method is the top-level entry point to the API:

> >     Player Manager.createPlayer(String url)

> The `url` fully specifies the protocol and the content of the data:

> >     <protocol>:<content location>

> The `Manager` parses the URL, recognizes the content type and creates a `Player` to handle the presentation of the data. The resulting `Player` is returned for use by the application. Connections created by `createPlayer` follow the `Generic Connection` framework rules and policies.

> The `Player` provides general methods to control the data flow and presentation, for example:

> >     Player.realize()
> >     Player.prefetch()
> >     Player.start()

> Fine-grained control is an important feature of the API; therefore, each `Player` also provides type-specific controls with the `getControls` and`getControl` methods:

> > `Control[] Player.getControls()`
> > `Control Player.getControl(int controlType)`

> Since different types of media will yield different types of controls from its corresponding `Player`, the `getControls and getControl` methods can expose features that are unique to a particular media type.

### Tone Generation

> Tone generation is important for games and other audio applications. On very small devices, it is particularly important since that is likely to be the only form of multimedia capabilities supported. In its simplest form, tone generation reduces to a single buzzer or some simple monophonic tone generation. The Manager class provides a top level method to handle this simple form of single tone generation:

> > `Manager.playTone(int note, int duration, int volume)`

> The implementation of this method can be mapped directly to the device's hardware tone generator to provide the most responsive sound generation.

> In addition, the API also provides a way to create a specific type of Player for synthesizing tone sequences:

> > `Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR)`

> The Player created provides a special type of Control, ToneControl which can be used for programming a tone sequence. This enables more sophisticated applications written for slightly more powerful devices.

### Usage Scenarios

> In this section we demonstrate how the API could be used in four common scenarios.

> #### `Scenario 1: Single-Tone Generation`

>     try {
>         Manager.playTone(ToneControl.C4, 5000 /* ms */, 100 /* max vol */);
>     } catch (MediaException e) { }

> #### `Scenario 2: Simple Media Playback with Looping`

> `Notice that in MIDP 2.0 the wav format is mandatory only in a case the device supports sampled audio.`

>     try {
>         Player p = Manager.createPlayer("http://webserver/music.wav");
>         p.setLoopCount(5);
>         p.start();
>     } catch (IOException ioe) {
>     } catch (MediaException me) { }

> #### `Scenario 3: Playing Back from Media Stored in JAR`

> `Notice that in MIDP 2.0 the wav format is mandatory only in a case the device supports sampled audio.`

>     try {
>         InputStream is = getClass().getResourceAsStream("music.wav");
>         Player p = Manager.createPlayer(is, "audio/X-wav");
>         p.start();
>     } catch (IOException ioe) {
>     } catch (MediaException me) { }

> #### `Scenario 4: Tone Sequence Generation`

>     /**
>      * "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:
  MIDP 2.0

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.