Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.media
Class Manager

    java.lang.Object
      |
      +--javax.microedition.media.Manager

public final class Manager
extends java.lang.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 three methods to create a `Player` for playing back media:
> - Create from a media locator.
> - Create from a `DataSource`.
> - Create from an `InputStream`.
> The `Player` returned can be used to control the presentation of the media.

> The simplest way to create a `Player` is from a locator in the URI syntax. Given a locator, `createPlayer` will create a `Player` suitable to handle the media identified by the locator.

> Users can also implement a custom `DataSource` to handle an application-defined protocol. The custom `DataSource` can be used to create a `Player` by using the `createPlayer` method.

> A third version of `createPlayer` creates a `Player` from an `InputStream`. This can be used to interface with other Java API's which use `InputStreams` such as the java.io package. It should be noted that `InputStream` does not provide the necessary random seeking functionality. So a `Player` created from an `InputStream` may not support random seeking (ala `Player.setMediaTime`).

## System Time Base

> All `Players` need a `TimeBase`. Many use a system-wide `TimeBase`, often based on a time-of-day clock. `Manager` provides access to the system `TimeBase` through `getSystemTimeBase`.

## 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`
> 6. MPEG video files: `video/mpeg`

## Data Delivery Protocol

> A data delivery protocol specifies how media data is delivered to the media processing systems. Some common protocols are: local file, disk I/O, HTTP, RTP streaming, live media capture etc.

> Media locators are used to identify the delivery protocol (as well as the identifier/name of the media).

## 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 [ "?" params]

> A. Identifying the type or the specific name of the device:

>          device       = "audio" / "video" / "audio_video" / dev_name
>          dev_name     = alphanumeric
>          alphanumeric = 1*( ALPHA / DIGIT )

> B. Describing the media and capture parameters:

>          params = audio_params / video_params /
>                   audio_video_params / custom_params

> C. Describing the audio media format:

>          audio_params = audio_param *( "&" audio_param )
>          audio_param  = 1*( "encoding=" audio_enc / "rate=" rate /
>                             "bits=" bits / "channels=" channels /
>                             "endian=" endian / "signed=" signed )
>          audio_enc    = "pcm" / "ulaw" / "gsm"
>          rate         = "96000" / "48000" / "44100" / "22050" / "16000" /
>                         "11025" / "8000"
>          bits         = "8" / "16" / "24"
>          channels     = pos_integer
>          endian       = "little" / "big"
>          signed       = "signed" / "unsigned"
>          pos_integer  = 1*DIGIT

>        Example:

>          encoding=pcm&rate=11025&bits=16&channels=1

> D. Describing the video or image format:

>          video_params = video_param *( "&" video_param )
>          video_param  = 1*( "encoding=" video_enc / "width=" width /
>                            "height=" height / "fps=" fps )
>          video_enc    = "gray8" / "rgb888" / "bgr888" / "rgb565" / "rgb555" /
>                         "yuv444" / "yuv422" / "yuv420" / "jpeg" / "png"
>          width        = pos_integer
>          height       = pos_integer
>          fps          = pos_number
>          pos_number   = 1*DIGIT [ "." 1*DIGIT ]

>        Example:

>          encoding=gray8&width=160&height=120

> E. Describing audio and video parameters:

>          audio_video_params = audio_params "&" video_params

>        Example:

>          encoding=pcm&encoding=gray8&width=160&height=160

> F. Describing some custom media parameters:

>          custom_params = param *( "&" param )
>          param         = key "=" value
>          key           = alphanumeric
>          value         = alphanumeric

>        Examples:

>          capture://audio  (default audio)
>          capture://audio?encoding=pcm   (default audio in PCM format)
>          capture://devmic0?encoding=pcm&rate=11025&bits=16&channels=1
>                  (audio from a specific device--devmic0)

>          capture://video  (default video)
>          capture://video?encoding=gray8&width=160&height=120
>          capture://devcam0?encoding=rgb888&width=160&height=120&fps=7

>          capture://mydev?myattr=123   (custom device with custom param)

> ### 2. Locators for RTP streaming

> RTP is a public standard for streaming media. The locator syntax for specifying RTP sessions is:

>          "rtp://" address [ ":" port ] [ "/" type ]

>        where:

>          address and port defines the RTP session.  The
>          address and port usage is similar to the host and port
>          usage as defined in the URI syntax.

>          type = "audio" / "video" / "text"

See Also:
  `DataSource`, `Player`, `TimeBase`

Field Summary
`static java.lang.String` | `MIDI_DEVICE_LOCATOR` The locator to create a MIDI `Player` which gives access to the MIDI device by making `MIDIControl` available.
`static java.lang.String` | `TONE_DEVICE_LOCATOR` The locator to create a tone `Player` to play back tone sequences.

Method Summary
`static Player` | `createPlayer(DataSource source)` Create a `Player` for a `DataSource`.
`static Player` | `createPlayer(java.io.InputStream stream, java.lang.String type)` Create a `Player` to play back media from an `InputStream`.
`static Player` | `createPlayer(java.lang.String locator)` Create a `Player` from an input locator.
`static java.lang.String[]` | `getSupportedContentTypes(java.lang.String protocol)` Return the list of supported content types for the given protocol.
`static java.lang.String[]` | `getSupportedProtocols(java.lang.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 java.lang.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`.

### MIDI_DEVICE_LOCATOR

    public static final java.lang.String MIDI_DEVICE_LOCATOR

  The locator to create a MIDI `Player` which gives access to the MIDI device by making `MIDIControl` available. e.g.

       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 any media data. `getDuration` returns 0 for this `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

### getSupportedContentTypes

    public static java.lang.String[] getSupportedContentTypes(java.lang.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.

### getSupportedProtocols

    public static java.lang.String[] getSupportedProtocols(java.lang.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.

### createPlayer

    public static Player createPlayer(java.lang.String locator)
                               throws java.io.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.
    `java.io.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`.

### createPlayer

    public static Player createPlayer(DataSource source)
                               throws java.io.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`.
    `java.io.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`.

### createPlayer

    public static Player createPlayer(java.io.InputStream stream,
                                      java.lang.String type)
                               throws java.io.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.
    `java.io.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`.

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

### getSystemTimeBase

    public static TimeBase getSystemTimeBase()

  Get the time-base object for the system.
  Returns:
    The system time base.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright 2002 Sun Microsystems, Inc.; Nokia Corporation. See the Copyright Notice and Specification License for more details.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD