Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. and Motorola, Inc. All rights reserved.
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 Controls 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: 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:

This subset differs from the full Mobile Media API in the following ways:

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.

    DataSource, Player and Manager

    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    
    Copyright © 2006 Sun Microsystems, Inc. and Motorola, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

    For more information, please consult the JSR 118 specification.