Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.microedition.media
Class Manager

java.lang.Object
  extended by javax.microedition.media.Manager

public final class Manager
extends Object

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.

Simple Tone Generation

The playTone function is defined to generate tones. Given the note and duration, the function will produce the specified tone.

Creating Players

Manager provides two methods to create a Player for playing back media: The Player returned can be used to control the presentation of the media.

Content Types

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:

  1. Wave audio files: audio/x-wav
  2. AU audio files: audio/basic
  3. MP3 audio files: audio/mpeg
  4. MIDI files: audio/midi
  5. Tone sequences: audio/x-tone-seq

Media Locator

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

Media Encoding Strings

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_encodings
B. 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=1
C. 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=160
E. Describing custom media encodings:

     custom_encodings = custom_enc_param *( "&" param )
     custom_enc_param = "encoding=" value
     param            = key "=" value
     key              = alphanumeric
     value            = alphanumeric
F. Rules for handling the encodings strings:

G. Custom RIM parameters:

RIM implements some custom parameters for locator strings which can be used to further customize Player creation.

Custom Audio Recording Parameters

On some BlackBerry devices, Players created for audio recording ("capture://audio") support the following parameters: 

     update_method    = "updateMethod=" method
     method           = "time" / "size"
     update_threshold = "updateThreshold=" threshold
     threshold        = pos_integer

These parameters together specify when data is written from the Player to the recording location.

If "time" is specified as the update method then threshold will be interpreted as a value in milliseconds. Valid values are from 100 - 1580 and will be rounded to the nearest 20 ms value.

If "size" is specified as the update method then threshold will be interpreted as a number of bytes. Valid values are from 160 - 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.

Custom Video Recording Parameters

BlackBerry devices support the following parameters to further customize the Player created for video recording ("capture://video") 

     codec_param      = "audio_codec=" audio_codec /
                        "video_codec=" video_codec
     audio_codec      = "AMR" / "AAC" / "QCELP" / "NONE"
     video_codec      = "H263" / "H264" / "MPEG-4"
     bitrate_param    = "video_rate=" video_rate /
                        "rate=" audio_rate
     video_rate       = pos_integer
     audio_rate       = pos_integer
     mode             = "mode=" recording_mode
     recording_mode   = "mms" / "standard"

Example 

  capture://video?encoding=video/3gpp&audio_codec=AAC&video_codec=H264&rate=32000&video_rate=282000

This will create a player configured to record video using AAC audio encoding at a bitrate of 32kbps and H264 video encoding at a bitrate of 282kbps

If mode=mms is specified, the Player that is created is optimized for Multimedia Messaging.

If audio_codec=none is specified, the player created will be configured to record video without any audio.

Some codecs may not be supported on all devices. Ensure that the codec used is supported on the specific device by calling System.getProperty("video.encodings")

When any parameter is unspecified, default value is used.

Enabling a Recording Player in VOIP Mode

When creating a Player for audio recording ("capture://audio") it is possible to set the Player to a 'VOIP mode' to maximize compatibility with various device hardware. When used with CDMA-based devices this will allow Players to be able to simultaneously record and playback voice data. This property is not specifically required when using a GSM-based device (and is in fact ignored) but it is recommended that applications always specify it regardless since it allows these VOIP applications be hardware-agnostic and work on both platforms seamlessly.

To signal that a recording Player be created in 'VOIP mode' add this parameter: 

     voipMode         = "true" / "false"

The default value if unspecified is false, when the parameter is present with any value other than true or false the parameter is ignored. When this parameter is set to true then the rate audio parameter must also be specified as described above, and it must correspond to a valid bitrate for the content-type specified in the Locator string. Note that this parameter will be ignored on GSM-based devices, regardless of the presence or value of the voipMode parameter. Also note that not all content-types that are supported for audio recording can be used for this mode. See the chart below for a list of valid content-type and bitrate combinations for this mode.

A new Player for audio playback can then be created, and if it is created by the same application using the same content-type, then it will be able to function correctly while the first Player is recording thus enabling VOIP capability while maximizing compatibility across differing devices. 

 Content-Type    Bitrates Available (bits/s)
 
  audio/amr      4750 / 5150 / 5900 / 6700 / 7400 / 7950 / 10200 / 12200
                 These values correspond to AMR-NB Modes 0-7 respectively
 
  audio/qcelp    1000 / 2700 / 6200 / 13300
                 These values correspond to 1/8 Rate, 1/4 Rate, 1/2 Rate, and
                 Full-Rate respectively

See Also:
Player
Since:
BlackBerry API 4.0.0

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

TONE_DEVICE_LOCATOR

public static final String TONE_DEVICE_LOCATOR
The locator to create a tone 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.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

MIDI_DEVICE_LOCATOR

public static final String MIDI_DEVICE_LOCATOR
The locater to create a MIDI 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.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0


Method Detail

getSupportedContentTypes

public static String[] getSupportedContentTypes(String protocol)
Return the list of supported content types for the given 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.

Parameters:
protocol - The input protocol for the supported content types.
Returns:
The list of supported content types for the given protocol.
Since:
BlackBerry API 4.0.0

getSupportedProtocols

public static String[] getSupportedProtocols(String content_type)
Return the list of supported protocols given the content type. The protocols are returned as strings which identify what locators can be used for creating 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.

Parameters:
content_type - The content type for the supported protocols.
Returns:
The list of supported protocols for the given content type.
Since:
BlackBerry API 4.0.0

createPlayer

public static Player createPlayer(String locator)
                           throws IOException,
                                  MediaException
Create a Player from an input locator.

Parameters:
locator - A locator string in URI syntax that describes the media content.
Returns:
A new Player.
Throws:
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.
Since:
BlackBerry API 4.0.0

createPlayer

public static Player createPlayer(DataSource source)
                           throws IOException,
                                  MediaException
Create a Player for a DataSource.

Parameters:
source - The DataSource that provides the media content.
Returns:
A new Player.
Throws:
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.
Since:
BlackBerry API 4.0.0

createPlayer

public static Player createPlayer(InputStream stream,
                                  String type)
                           throws IOException,
                                  MediaException
Create a 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.

Parameters:
stream - The InputStream that delivers the input media.
type - The ContentType of the media.
Returns:
A new Player.
Throws:
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.
Since:
BlackBerry API 4.0.0

playTone

public static void playTone(int note,
                            int duration,
                            int volume)
                     throws MediaException
Play back a tone as 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 from 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.
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.

Parameters:
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.
Throws:
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.
Since:
BlackBerry API 4.0.0

getSystemTimeBase

public static TimeBase getSystemTimeBase()
Get the time-base object for the system.

Returns:
The system time base.
Since:
BlackBerry API 4.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal