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.
The playTone
function is
defined to generate tones. Given the note and duration, the function will
produce the specified tone.
Manager
provides two methods to create aPlayer
for playing back media:The
- Create from a media locator.
- Create from an
InputStream
.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 aPlayer
suitable to handle the media identified by the locator.A second version of
createPlayer
creates aPlayer
from anInputStream
. This can be used to interface with other Java APIs which useInputStreams
such as thejava.io
package. It should be noted thatInputStream
does not provide the necessary random seeking functionality. So aPlayer
created from anInputStream
may not support random seeking (alaPlayer.setMediaTime
).
AllPlayers
need aTimeBase
. Many use a system-wideTimeBase
, often based on a time-of-day clock.Manager
provides access to the systemTimeBase
throughgetSystemTimeBase
.
Content types identify the type of media data. They are defined to be the registered MIME types (see [IANAMEDIA]); plus some user-defined types that generally follow the MIME syntax ([RFC2045], [RFC2046]).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
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 locators are specified in URL 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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
TONE_DEVICE_LOCATOR
The locator to create a tone
Player to play back tone sequences. |
Modifier and Type | Method and Description |
---|---|
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.
|
public static final java.lang.String TONE_DEVICE_LOCATOR
Player
to play back tone sequences.
For example,
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 Player createPlayer(java.io.InputStream stream, java.lang.String type) throws java.io.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 mediatype
- the content type of the mediaPlayer
java.lang.IllegalArgumentException
- if stream
is null
java.lang.SecurityException
- if the caller does not have security permission
to create the Player
java.io.IOException
- if there was a problem reading data from the
InputStream
{@link
- MediaException} if a Player
cannot be created
for the given stream
and type
MediaException
public static Player createPlayer(java.lang.String locator) throws java.io.IOException, MediaException
Player
from an input locator.locator
- A locator string in URI syntax that describes the media content.Player
.java.lang.IllegalArgumentException
- if locator
is null
.java.lang.SecurityException
- if the caller does not have security permission
to create the Player
java.io.IOException
- if there was a problem connecting with the source
pointed to by the locator
{@link
- MediaException} if a Player
cannot be created
for the given locator
MediaException
public static java.lang.String[] getSupportedContentTypes(java.lang.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 typespublic static java.lang.String[] getSupportedProtocols(java.lang.String content_type)
Players
.
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 protocolspublic static TimeBase getSystemTimeBase()
public static void playTone(int note, int duration, int volume) throws MediaException
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.
note
- defines the tone of the note as specified by the above formuladuration
- 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
.{@link
- MediaException} if the tone cannot be played due to a
device-related problemjava.lang.IllegalStateException
- if the given note or duration is out of rangeMediaException
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.