See: Description
Interface | Description |
---|---|
Control |
A
Control object is used to control some media processing
functions. |
Controllable | |
Player |
Player controls the rendering of time based media data. |
PlayerListener |
PlayerListener is the interface for receiving asynchronous events
generated by Players . |
TimeBase |
A
TimeBase is a constantly ticking source of time. |
Class | Description |
---|---|
Manager |
Manager is the access point for obtaining system dependent
resources such as Players for multimedia processing. |
Exception | Description |
---|---|
MediaException |
A
MediaException indicates an unexpected error condition in a method. |
Of course, implementers of MEEP 8 profile on embedded devices can feel free
to implement the
Mobile Media API (JSR-135) on a device. In this case, media
and media.control
package are implemented as part of this JSR
and cannot be implemented as part of MEEP 8 at the same time (see the
Media section in the "Optionality and Dependencies" chapter
for details).
javax.microedition.media.protocol
package (Data Source)
is excluded.
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.
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()
Player
also provides type-specific controls with the
getControls
and getControl
methods:
Control[] Player.getControls()
Control Player.getControl(int controlType)
Player
, the getControls
and
getControl
methods can expose features that are unique to a
particular media type.
Security issues may appear when this API is used. Those issues are related to
accessing resources either locally or over the network.
A Player
can be initialized by a locator
A pointing
to a content that can reside on a network server or it could be on some local
storage. Reading data over the network requires use of the network connection
that may have security policy in place. An access to a local data storage may
have security policies in place as well.
Implementation of this package must follow the
security practices
(if supported by the implementation) that are in place for accessing those
resources. For example, when a Player
is created to play content
on a HTTP server, the implementation must follow the security practices for
network access. When a locator is used to access media the implementation of
this package must throw a SecurityException under the same conditions
as would an access by the Generic Connection Framework.
Below is a list of methods which can throw a SecurityException
due to security violations.
API call |
Manager.createPlayer(String locator) Manager.createPlayer(InputStream stream, String type) Player.realize() Player.prefetch() Player.start() |
When playback is started one of the methods Manager.createPlayer
,
Player.realize
, Player.prefetch
and Player.start
must throw the SecurityException
if there′s no permission
to open the connection. Because of the multi-stage initialization of
Players
it is not possible to specify which method exactly must
do that.
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.
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 MEEP 8 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 MEEP 8 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) { } |
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.