|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjavax.microedition.media.Manager
public final class Manager
Manager is the access point for obtaining
system dependent resources such as Players
for multimedia processing.
A Player is an object used to control and render media that is specific to the content type of the data.
Manager provides access to an implementation specific
mechanism for constructing Players.
For convenience, Manager also provides a simplified
method to generate simple tones.
The
playTone
function is defined to generate
tones. Given the note and duration, the function will
produce the specified tone.
Managerprovides two methods to create aPlayerfor playing back media:The
- Create from a media locator.
- Create from an
InputStream.Playerreturned can be used to control the presentation of the media.
Content types identify the type of media data. They are defined to be the registered MIME types ( http://www.iana.org/assignments/media-types/); plus some user-defined types that generally follow the MIME syntax (RFC 2045, RFC 2046).For example, here are a few common content types:
- Wave audio files:
audio/x-wav- AU audio files:
audio/basic- MP3 audio files:
audio/mpeg- MIDI files:
audio/midi- Tone sequences:
audio/x-tone-seq
Media locators are specified in URI syntax which is defined in the form:<scheme>:<scheme-specific-part>
The "scheme" part of the locator string identifies the name of the protocol being used to deliver the data.
Some media specific locator syntax are defined below:
1. Locators for Live-media Capture
The locators for capturing live media are defined by the following syntax in Augmented BNF notations:
"capture://" device [ "?" media_encodings ]2. Locators for RTSP streaming
RTSP is a public standard for streaming media. The locator syntax for specifying RTSP sessions is:"rtsp://" host [ ":" port ] [ filename ]
Example:
rtsp://224.1.2.3:12344/streaming_video.3gp
There are a few places where media encodings are specified as strings, e.g. in the capture media locator. Sections A to E define the encoding syntax. Section F defines the rules for how they should be handled. Section G describes custom RIM implementation parameters.A. Describing media encodings:
media_encodings = audio_encodings / video_encodings / mixed_encodings / custom_encodingsB. Describing the audio encodings:
audio_encodings = audio_enc_param *( "&" audio_param ) audio_enc_param = "encoding=" audio_enc audio_enc = "pcm" / "ulaw" / "gsm" / content_type audio_param = "rate=" rate / "bits=" bits / "channels=" channels / "endian=" endian / "signed=" signed / "type=" audio_type rate = "96000" / "48000" / "44100" / "22050" / "16000" / "11025" / "8000" / other_rate other_rate = pos_integer bits = "8" / "16" / "24" / other_bits other_bits = pos_integer channels = pos_integer endian = "little" / "big" signed = "signed" / "unsigned" audio_type = bitrate_variable / other_type other_type = alphanumeric pos_integer = 1*DIGIT and content type is given in the MIME syntax.
Example:
encoding=pcm&rate=11025&bits=16&channels=1C. Describing the video or image encodings:
video_encodings = video_enc_param *( "&" video_param ) video_enc_param = "encoding=" video_enc video_enc = "gray8" / "rgb888" / "bgr888" / "rgb565" / "rgb555" / "yuv444" / "yuv422" / "yuv420" / "jpeg" / "png" / content_type video_param = "width=" width / "height=" height / "fps=" fps / "colors=" colors / "progressive=" progressive / "interlaced=" interlaced / "type=" video_type width = pos_integer height = pos_integer fps = pos_number quality = pos_integer colors = "p" colors_in_palette / = "rgb" r_bits g_bits b_bits / = "gray" gray_bits colors_in_palette = pos_integer r_bits = pos_integer g_bits = pos_integer b_bits = pos_integer gray_bits = pos_integer progressive = boolean video_type = jfif / exif / other_type other_type = alphanumeric interlaced = boolean pos_number = 1*DIGIT [ "." 1*DIGIT ] boolean = "true" / "false" and content type is given in the MIME syntax.
Examples:
encoding=gray8&width=160&height=120 encoding=jpeg&quality=80&progressive=true&type=jfif (progressive JPEG with quality 80 in jfif format) encoding=jpeg&type=exif (JPEG in exif format) encoding=png&colors=rgb888 (24 bits/pixel PNG) encoding=rgb888 (raw 24-bit rgb image) encoding=rgb&colors=rgb888 (raw 24-bit rgb image)D. Describing mixed audio and video encodings:
mixed_encodings = audio_encodings "&" video_encodings
Example:
encoding=pcm&encoding=gray8&width=160&height=160E. Describing custom media encodings:
custom_encodings = custom_enc_param *( "&" param ) custom_enc_param = "encoding=" value param = key "=" value key = alphanumeric value = alphanumericF. Rules for handling the encodings strings:
- If a given parameter is a custom parameter and is not recognizable by the implementation, the parameter is treated as an illegal parameter and the method must throw an appropriate Exception to denote that.
- If the value for a given parameter is incorrect because it is syntactically wrong or illegal (e.g. out of range), the method must throw an appropriate Exception to denote that.
RIM implements some custom parameters for locator strings which can be used to further customize
Playercreation.On some BlackBerry devices,
Playerscreated for audio recording("capture://audio")support the following parameters:update_method = "updateMethod=" method method = "time" / "size" update_threshold = "updateThreshold=" threshold threshold = pos_integerThese parameters together specify when data is written from the
Playerto the recording location.If
"time"is specified as the update method thenthresholdwill be interpreted as a value in milliseconds. Valid values are from 20 - 1580 and will be rounded to the nearest 20 ms value.If
"size"is specified as the update method thenthresholdwill be interpreted as a number of bytes. Valid values are from 32 - 2528.If these parameters are not specified or are not valid values they will be ignored, and the recording update method will remain set to the default: data will be written every 1024 bytes.
Player| Field Summary | ||
|---|---|---|
static String |
MIDI_DEVICE_LOCATOR
The locater to create a MIDI Player which gives access to
the MIDI device by making MIDIControl available. |
|
static String |
TONE_DEVICE_LOCATOR
The locator to create a tone Player
to play back tone sequences. e.g. |
|
| Method Summary | ||
|---|---|---|
static Player |
createPlayer(InputStream stream,
String type)
Create a Player to play back media from an
InputStream. |
|
static Player |
createPlayer(String locator)
Create a Player from an input locator. |
|
static Player |
createPlayer(DataSource source)
Create a Player for a DataSource. |
|
static String[] |
getSupportedContentTypes(String protocol)
Return the list of supported content types for the given protocol. |
|
static String[] |
getSupportedProtocols(String content_type)
Return the list of supported protocols given the content type. |
|
static TimeBase |
getSystemTimeBase()
Get the time-base object for the system. |
|
static void |
playTone(int note,
int duration,
int volume)
Play back a tone as specified by a note and its duration. |
|
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final String TONE_DEVICE_LOCATOR
Player
to play back tone sequences. e.g.
try {
Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR);
p.realize();
ToneControl tc = (ToneControl)p.getControl("ToneControl");
tc.setSequence(mySequence);
p.start();
} catch (IOException ioe) {
} catch (MediaException me) {}
If a tone sequence is not set on the tone
Player via its ToneControl,
the Player does not carry any
sequence. getDuration returns 0 for this
Player.
The content type of the Player created from this
locator is audio/x-tone-seq.
A Player for this locator may not be supported
for all implementations.
Value "device://tone" is assigned to TONE_DEVICE_LOCATOR.
public static final String MIDI_DEVICE_LOCATOR
Player which gives access to
the MIDI device by making MIDIControl available. For example,
try {
Player p = Manager.createPlayer(Manager.MIDI_DEVICE_LOCATOR};
p.prefetch(); // opens the MIDI device
MIDIControl m = (MIDIControl)p.getControl("MIDIControl");
} catch (IOException ioe) {
} catch (MediaException me) {}
The MIDI Player returned does not carry an media
data. getDuration returns 0 for the Player.
The content type of the Player created from this
locator is audio/midi.
A Player for this locator may not be supported for all
implementations.
Value "device://midi" is assigned to MIDI_DEVICE_LOCATOR.
| Method Detail |
|---|
public static String[] getSupportedContentTypes(String protocol)
See content types for the syntax of the content types returned. See protocol name for the syntax of the protocol used.
For example, if the given protocol
is "http",
then the supported content types that can be played back
with the http protocol will be returned.
If null is passed in as the protocol,
all the supported content types for this implementation
will be returned. The returned array must be non-empty.
If the given protocol is an invalid or
unsupported protocol, then an empty array will be returned.
protocol - The input protocol for the supported content types.
public static String[] getSupportedProtocols(String content_type)
Player's.
See protocol name for the syntax of the protocols returned. See content types for the syntax of the content type used.
For example, if the given content_type
is "audio/x-wav", then the supported protocols
that can be used to play back audio/x-wav
will be returned.
If null is passed in as the
content_type,
all the supported protocols for this implementation
will be returned. The returned array must be non-empty.
If the given content_type is an invalid or
unsupported content type, then an empty array will be returned.
content_type - The content type for the supported protocols.
public static Player createPlayer(String locator)
throws IOException,
MediaException
Player from an input locator.
locator - A locator string in URI syntax that describes
the media content.
Player.
IllegalArgumentException - Thrown if locator
is null.
MediaException - Thrown if a Player cannot
be created for the given locator.
IOException - Thrown if there was a problem connecting
with the source pointed to by the locator.
SecurityException - Thrown if the caller does not
have security permission to create the Player.
public static Player createPlayer(DataSource source)
throws IOException,
MediaException
Player for a DataSource.
source - The DataSource that provides the media
content.
Player.
IllegalArugmentException - Thrown if source
is null.
MediaException - Thrown if a Player cannot be created
for the given DataSource.
IOException - Thrown if there was a problem connecting with the
source.
SecurityException - Thrown if the caller does not have security
permission to create the Player.
public static Player createPlayer(InputStream stream,
String type)
throws IOException,
MediaException
Player to play back media from an
InputStream.
The type argument
specifies the content-type of the input media. If
null is given, Manager will
attempt to determine the type. However, since determining
the media type is non-trivial for some media types, it
may not be feasible in some cases. The
Manager may throw a MediaException
to indicate that.
stream - The InputStream that delivers the
input media.type - The ContentType of the media.
Player.
IllegalArgumentException - Thrown if stream
is null.
MediaException - Thrown if a Player cannot
be created for the given stream and type.
IOException - Thrown if there was a problem reading data
from the InputStream.
SecurityException - Thrown if the caller does not
have security permission to create the Player.
public static void playTone(int note,
int duration,
int volume)
throws MediaException
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.
This call is a non-blocking call. Notice that this method may
utilize CPU resources significantly on devices that don't
have hardware support for tone generation.
note - Defines the tone of the note as specified by the
above formula.duration - The duration of the tone in milli-seconds.
Duration must be positive.volume - Audio volume range from 0 to 100. 100 represents
the maximum
volume at the current hardware level. Setting the volume to a
value less
than 0 will set the volume to 0. Setting the volume to greater than
100 will set the volume to 100.
IllegalArgumentException - Thrown if the given note or
duration is out of range.
MediaException - Thrown if the tone cannot be played
due to a device-related problem.public static TimeBase getSystemTimeBase()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.