Sound in J2MESound in J2ME

Khanh Le

OverviewOverview

The central goal of the specification work for the Sound API was to address the wide range of application areas. As a result, two API sets were developed: MIDP 2.0 Sound API Mobile Media API (MMAPI)

The division into two interoperable API sets arose from the fact that some devices are very resource-constrained. It may not be feasible to support a full range of multimedia types, such as video, on some mobile phones.

As a result, not all MIDP 2.0 target devices are required to support the full generality of the Mobile Media API, such as the ability to support custom protocols and content types.

MIDP Sound APIMIDP Sound API

The MIDP 2.0 Sound API is intended for resource-constrained devices such as mass-market mobile phones.

The basic level of sound support mandated for all devices is the presence of monophonic buzzer tones.

This API is a directly compatible subset of the full Mobile Media API. Furthermore, due to its building block nature, this subset API can be adopted to other J2ME profiles that require sound support

Mobile Media APIMobile Media API

The full Mobile Media API is intended for J2ME devices with advanced sound and multimedia capabilities. The target devices for the Mobile Media API include powerful mobile phones, as well as PDAs and set-top boxes.

ApplicationsApplications

Sound and media are a key feature in many applications. Games, music applications, user interface tones, and alerts are examples of application areas that will benefit from the MIDP Sound API.

MIDP Sound Architecture MIDP Sound Architecture

The framework of sound and media support in MIDP 2.0 consists of three main components: Manager, Player, and Controls.

MIDP Sound Architecture MIDP Sound Architecture

Class Manager is the access point for obtaining system-dependent resources such as Player objects for multimedia processing. Applications use the Manager class to request Players and to query supported content types and supported protocols. The Manager class also includes a method to play simple tones.

A Player is an object that is used to control and render media that is specific to the content type of the data. The application may obtain a Player by giving a locator string or an InputStream and a content type to the Manager class.

A Control is an interface that is used to implement all of the different controls a Player might have. An application can query a Player to check which controls it supports and then ask for a specific Control—for example, VolumeControl—to control volume.

Player Creation and Player Creation and ManagementManagement

Property queries: The MIDP sound API provides a mechanism for querying the type of content and protocols that the device supports. The property queries are enabled by the methods Manager.getSupportedContentTypes and Manager.getSupportedProtocols.

Creating Players for Media Data: The Player interface controls the rendering of time-based media data. It provides the methods to manage the life cycle of the Player, controls the playback progress, and obtains the presentation components.

A Player can be created using one of the two createPlayer methods of the Manager class:

// Create a Player to play back media from an InputStream createPlayer(java.io.InputStream stream, String type) // Create a Player from an input locator createPlayer(String locator)

Data Source for MediaData Source for Media

Content types identify the type of media data for Player objects when the Player is created using an InputStream.

For example, here are a few common content types: Tone sequences: audio/x-tone-seq Wave audio files: audio/x-wav AU audio files: audio/basic MP3 audio files: audio/mpeg MIDI files: audio/midi

MIDP Sound API Player state MIDP Sound API Player state diagram diagram

Player life cycle Player life cycle

Typically, a Player moves from the UNREALIZED state to the REALIZED state, then to the PREFETCHED state, and finally on to the STARTED state. A Player stops when it reaches the end of media or when the stop method is invoked. When that happens, the Player moves from the STARTED state back to the PREFETCHED state. Upon calling the Player.stop method, the playback position in the file does not change, so calling Player.start again will continue the playback from the same location.

The basic use of a Player only requires the Player.start and Player.stop methods. However, in order to fully utilize all the functionality of the Player, parameters must be set up appropriately to manage the life-cycle states, and the state transition methods should be used correctly to advance between the various Player states.

Additional Player functionalities include looping of audio using the setLoopCount method, and obtaining or setting the current position of media playback using the getMediaTime and setMediaTime methods. Furthermore, the getDuration method can be used to query the length of the media file.

PlayerListener PlayerListener

Class PlayerListener defines an interface that can be used for receiving asynchronous events generated by Player objects. Applications can implement this interface and register their implementations with the addPlayerListener method of class Player.

A number of standard Player events are defined in the PlayerListener interface. Event types are defined as Strings in order to support extensibility because different implementations may introduce proprietary events by adding new event types.

Tone Generation Tone Generation

The minimal requirement for all MIDP 2.0 devices is to support the playback of monophonic single tones.

In its simplest form, tone generation is implemented as a single buzzer or simple monophonic tone generation. This feature is enabled by two different methods in the MIDP 2.0 API. The first possibility is to use the Manager class, which provides a

method for playing back simple tones, specified by a note and its duration. A note is given in the range of 0 to 127 inclusive. The frequency of the note can be calculated using the following formula:SEMITONE_CONST = 17.31234049066755 = 1/(ln(2^(1/12)))note = ln(freq/8.176)*SEMITONE_CONST // The musical note A = MIDI note 69 (0x45) = 440 Hz.

The second possibility to create sequences of single tones is to use the ToneControl API

Sample Code Sample Code

Example: Single tone generationtry {

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

Example: Creating a player from media stored in JARtry { InputStream is = getClass().getResourceAsStream("music.wav");

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

Example: Creating a player from media in HTTP locatortry {

Player p = Manager.createPlayer("http://webserver/music.mid"); p.start(); } catch (IOException ioe) { } catch (MediaException me) { }

Media Controls Media Controls

Control objects are used for controlling content-type-specific media processing operations. Control object provides a logical grouping of media-processing functions.

All Control classes implement the interface Controllable, and the Player interface is a subinterface of Controllable. For example, a Player can expose a VolumeControl to allow the volume level to be set.

The javax.microedition.media.control package specifies a set of predefined Controls classes. In MIDP 2.0, two controls are specified and required: ToneControl and VolumeControl.

The Controllable interface provides a mechanism for obtaining the Controls from an object such as a Player. It provides methods to get all the supported Controls and to obtain a particular Control based on its class name.

ToneControl ToneControl

ToneControl is an interface that enables the 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 for defining the sequence for the ToneControl

VolumeControl VolumeControl

VolumeControl is an interface for manipulating the audio volume of a Player object.

The volume settings interface allows the output volume to be specified using an integer value that varies between 0 and 100.

The mapping for producing a linear multiplicative value is implementation-dependent.

Setting mute on or off does not change the volume level returned by method getLevel.

If mute is true, no audio signal is produced by the Player; if mute is false, an audio signal is produced and the volume is restored.

When the state of the VolumeControl changes, a VOLUME_CHANGED event is delivered to the Player through its PlayerListener.

Sample CodeSample Code

The sample application below defines a simple media player for sampled audio with an attached volume control.

The Player is created from an InputStream. A Gauge is used for visualizing and controlling the

volume of the player. Simple player functions including start, stop, and

rewind are supported. Furthermore, PlayerListener events are defined for

printing the player states during the execution of the program.

Enhanced Media Support Enhanced Media Support Using the Mobile Media API Using the Mobile Media API

As discussed earlier in this chapter, MIDP Sound API is a subset of the Mobile Media API (MMAPI) defined by the Java Community Process effort JSR 135.

MMAPI includes a lot of additional functionality that is not present in the MIDP 2.0 Sound API.

The additional features introduced by the Mobile Media API include the following: Custom protocols through the DataSource Synchronization of multiple Players using the TimeBase

interface Interactive synthetic audio Video and camera functionality Capture and recording Metadata

DataSource DataSource

Class DataSource encapsulates protocol handling. It hides the details of how the data is read from its source, and whether the data is coming from a file, streaming server, or a proprietary delivery mechanism. Class DataSource provides a set of methods to allow a Player to read data.

Advanced Controls Advanced Controls

MMAPI Controls Overview

FramePositioningControl Interface to control precise positioning to a video frame for Players.

GUIControl Extends Control and is defined for controls that provide GUI functionality.

MetaDataControl Used to retrieve metadata information included within the media streams.

MIDIControl Provides access to MIDI rendering and transmitting devices.

PitchControl Raises or lowers the playback pitch of audio without changing the playback speed.

RateControl Controls the playback rate of a Player.

RecordControl Controls the recording of media from a Player. This control records what is currently being played by the Player.

StopTimeControl Specifies a preset stop time for a Player.

TempoControl Controls the tempo, in musical terms, of a song.

ToneControl Interface to enable playback of a user-defined monotonic tone sequence.

VideoControl Controls the display of video and provides a method for taking snapshots.

VolumeControl Interface for manipulating the audio volume of a Player.

MMAPI defines a total of 12 Control classes

In future releases of the API, new controls may be introduced

SummarySummary

In the MIDP Specification version 1.0, sound support was minimal. With the release of the MIDP Specification version 2.0, sound support has been significantly extended.

A well-defined, scalable Sound API has been created for devices supporting the Mobile Information Device Profile.

A diverse set of applications—including games and media applications—will benefit from the MIDP 2.0 Sound API.

LabsLabs

Write an OrganMIDlet