com.siemens.mp.media
Class Manager

java.lang.Object
  com.siemens.mp.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:

• Create from a media locator.
• Create from an InputStream.

The Player returned can be used to control the presentation of the media. Connections created by createPlayer follow the Generic Connection framework rules and policies.

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/x-mid
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.

See Also:

Player

Field Summary

static String	MIDI_DEVICE_LOCATOR
static String	TONE_DEVICE_LOCATOR The locator to create a tone Player to play back tone sequences. i.e.

Method Summary

static Player	createPlayer(com.siemens.mp.media.protocol.DataSource source) Create a Player for a DataSource.
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 the input locator.
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. i.e.
Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR); Value "device://tone" is assigned to TONE_DEVICE_LOCATOR.

See Also:

Constant Field Values

MIDI_DEVICE_LOCATOR

public static final String MIDI_DEVICE_LOCATOR

See Also:

Constant Field Values

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.

If the given protocol is an invalid or unsupported protocol, then an empty array will be returned.

Returns:

The list of supported content types.

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.

If the given content_type is an invalid or unsupported content type, then an empty array will be returned.

Returns:

The list of supported protocols.

createPlayer

public static Player createPlayer(String locator)
                           throws IOException,
                                  MediaException

Create a Player from the input locator.

Parameters:

locator - A locator string in URI syntax that describes the media content. If locator is null, createPlayer will throw a MediaException.

Returns:

A new Player.

Throws:

MediaException - Thrown if a Player cannot be created for the given locator.

IOException - Thrown if there was a problem opening the media.

SecurityException - Thrown if the caller does not have security permission to create the Player.

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, the 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. In those cases, the Manager may throw a MediaException to indicate that it cannot create a suitable Player for that.

Parameters:

stream - The InputStream that delivers the input media. If stream is null, createPlayer will throw a MediaException.

type - The ContentType of the media. If null is given, the Manager will attempt to determine the type.

Returns:

A new Player.

Throws:

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.

createPlayer

public static Player createPlayer(com.siemens.mp.media.protocol.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:

IllegalArgumentException - 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.

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. 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 non-negative.

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.

getSystemTimeBase

public static TimeBase getSystemTimeBase()

Get the time-base object for the system.

Returns:

The system time base.