Scmad Chapter12

By Marcel Caraciolo

http://mobideia.blogspot.com

Chapter 12– MIDP Sound API

SCMAD Certification 45mm

61m

m

Agenda•MIDP – Sound API•Sound API•Manager•Player•Control•Controllable•PlayerListener•Controls

MIDP Sound API

•MIDP defines a basic sound API. MMAPI (Mobile Media API) provides support to more sophisticated media devices, an its API extends MIDP’s. It will be descrived on the next chapter.•Devices must at least be able to generate monophonic tones.•Allows playing recorded media (independently of the encoding), tone generation and controls (e.g. volume).•Video is not supported. MMAPI is required for handling video.•Media files may be downloaded from the network or packaged on the JAR.

MIDP Sound API

•Minimum requirements:•Tone generation•If recorded media is supported, PCM wav 8 bit, 8 KHZ format must be supported. Additional formats may be supported•MIDI may be supported

•Like network operations, media operations must also be executed on separate threads, because resource loading and infrastructure access may consume time. A resource execution (start method) is not blocking ONLY when all resources are already loaded.•Classes at javax.microedition.media package.•API is based on three main classes: Manager, Player and Control.

M Manager

•Factory to create Players, which execute media operations•All methods are static•Factory methods: Manager.createPlayer()

M Manager

•Players may be created from:•A media locator: URL that defines origin and content type to be processed. There are three types of media locator:

•An URL referencing a resource to be executed (e.g. http://server/music.mid or rtp://host/type). The content type is part of the response header and the content is part of the response body.

•A device to generate sound programmatically. (e.g. device://tone or device:// midi) . An “empty” player is created, and sound is created programmatically.

•An URL accessing a media capture device (e.g. capture:// audio, capture:// video, capture://radio)

M Manager

•Players may be created from:• An input stream: For instance, the stream can be from a JAR resource or from the network. The content type may be discovered from the content.

•A DataSource (MMAPI only): Class that handles “fetching” data, decoupling data from its source and access protocol.

M Manager: methods

•Players may be created from:• playTone(note,duration,volume): Convenience method to play a tone. Plays a tone (integer from 0 to 127), during the specified time (milliseconds) using the specified volume ( 0 – 100). This method is non-blocking.

•getSupportedContentTypes(protocol): Gets all supported content types for a specific protocol. If protocol is null, all supported content types are returned. Content types examples:•audio/x-wav (PCM wav)•audio/midi (MIDI)•audio/x-tone-seq (Tone sequencing)•audio/mpeg (MP3)•video / mpeg (MPEG video)

M Manager: methods

•Players may be created from:• getSupportedProtocols(content_type): Gets all protocols that can be used to access some content type (e.g. HTTP RTP). If null is informed, all protocols that can be used to access media are returned.

•createPlayer(locator): Creates a player from a specified locator.

•createPlayer(stream,type): Creates a player from stream, to execute the specified content type. If the type is null, the device will try to find out the content based on the stream’s content.

•createPlayer(dataSource): Creates a player using dataSource. (Available only at MMAPI).

MP Player Interface

•Controls media execution

•Players are created using Manager’s factory methods, and the media executions begins calling start() method. If all data is already loaded, this call is not blocking. If not interrupted, the execution proceeds until the end of the media.

MP Player: Life cycle

•These are the player’s states:•UNREALIZED: Right after its creation. No data is loaded, hence the following methods cannot be called:•getContentType•setTimeBase/ getTimeBase•setMediaTime•getControl/ getControls

•REALIZED: Resources were fetched. Resource information is available and its content is possibly loaded.

MP Player: Life cycle

•These are the player’s states (Continuing):•PREFETCHED: Resources were loaded and are available to execution, probably already on the output buffers. When the execution is finished, the player returns to this state.

•STARTED: Execution has started and has not finished.

•CLOSED: Player is closed. Resources are freed and the player cannot be reused.

MP Player: Life cycle

•When you create, start, wait for the media end and close a player , the life cycle is:

•UNREALIZED•REALIZED•PREFETCHED•STARTED•PREFETCHED•CLOSED

MP Player: Methods

•getDuration(): Media duration. If it’s undefined (e.g. for live transmission streams) TIME_UNKNOWN is returned.

•getContentType(): Media’s content type.

•getState(): Current state (UNREALIZED, REALIZED, PREFETCHED, STARTED or CLOSED).

•realize(), prefetch() : Requests a start change. If it’s in a more advanced state (e.g. calling realize on PREFETCHED player) the call is ignored. These methods ARE blocking.

MP Player: Methods

•start(): Starts the media execution. If the player is not at PREFETCHED state, it will be prefetched before the execution starts. If it’s already executing, the call is ignored. If it’s called on a interrupted player (interrupted by stop or media end) the execution continues from the point where it stopped. It’s not blocking if the player is PREFETCHED.

•stop(): Stops the execution at the current point.

•deallocate(): Deallocate all player’s resources and it returns it to REALIZED state. Useful for devices that do not support mixing and the buffers must be freed if another resource is to be executed.

•close(): Finishes a player and deallocates all the resources it consumes.

MP Player: Methods

•setMediaTime(now): Sets the execution on a specific time. If it’s a negative value, the media returns at the beginning. If it’s bigger than the resource duration, it goes to the end. Some resources may not support this operation (e.g. live transmissions).

•setLoopCount(count): Repeats the media execution. By default it’s 1. Setting 0 is not valid and setting -1 repeats indefinitely. It cannot be called by a STARTED player.

•addPlayerListener(playerlistener), removePlayerListener(playerListener): Adds/Removes an event listener, which is notified everytime a player changes its state. Event ordering is kept.

MP Control

•Marker interface (define no methods)•Controls the execution of processing of some media type. Examples:•VolumeControl•FramePositioningControl•RecordControl

•A player may have several controls

MP Controllable

•Controllable: Object that “has controls”. Player implements Controllable.

•Methods:•getControls(): All controls supported by the object•getControl(controlType): Gets a control from its class name. If this control is not supported, null is returned. If the package name is omitted, it’s assumed that it belongs to javax.microedition.media package.

MP Controllable

•PlayerListener: Receives player’s events notifications. Events are represented as strings so that new events may be added without changing the interface.•Event samples:•STARTED•STOPPED•END_OF_MEDIA•VOLUME_CHANGED•ERROR•CLOSED

•Method: playerUpdate(player,event,eventData): An event has happened on this player with the parameter data.

MP Controls: VolumeControl

•Volume handling control. Volume value goes from 0 to 100 (inclusive). Mute may be set, which silents the media output but does not change the value returned by getLevel().•Must be implemented by player that execute sample audio (e.g. wav), generated audio (e.g. MIDI or tones) and video with sound.•Methods:

•setMute(boolean)•isMuted()•setLevel(level)•getLevel()

MP Controls: ToneControl

•Plays a monophonic media sequence. A player is obtained by Manager.TONE_DEVICE_LOCATOR locator. It’s an important control because this might be the only way to produce music on rudimentary devices.

•Defines the setSequence(byte[]) method to set the media sequence. A sequence is defined by pairs that specify, on this order:•Version•Tempo•Resolution•Blocks•Events

To Tone Control: Sample Example

Example Codes

• Some examples and MIDlets samples are available for reference and studying at this link:•http://www.dsc.upe.br/~mpc/chapter12.rar

•The source codes include:•SoundPlayerMIDlet

Future Work

• Next Chapter:

• MIDP – MMAPI

References

• ALVES F. Eduardo. SCMAD Study Guide, 27/04/2008.

• JAKL Andreas, Java Platform, Micro Edition Part 01 slides, 12/2007.

• Sun Certification Mobile Application Developer Website: [http://www.sun.com/training/certification/java/scmad.xml].