package-summary.html

J2ME MIDP2.0 final specification

<tt>Players</tt> and to query properties,
supported content types and supported protocols. The manager also includes
a method to play simple tones.
<p>The<tt> Player</tt> plays the multimedia content. The application obtains
a <tt>Player</tt> by giving the locator string to <tt>Manager</tt>.
<p><tt>A Control</tt> is an interface that is used to implement all different
controls a <tt>Player</tt> might have. An application can query a <tt>Player</tt>
of controls it supports and then ask for a specific <tt>Control</tt> e.g.
<tt>VolumeControl</tt>
to control volume.</blockquote>

<blockquote>
<blockquote><img SRC="doc-files/plr-mgr-ctl.gif" ALT="DataSource, Player and Manager" height=130 width=251></blockquote>
</blockquote>

<h3>
API Details</h3>

<blockquote>The <tt>createPlayer</tt> method is the top-level entry point
to the API:
<blockquote>
<pre>Player Manager.createPlayer(String url)</pre>
</blockquote>
The <tt>url</tt> fully specifies the protocol and the content of the data:
<blockquote>
<pre>&lt;protocol&gt;:&lt;content location&gt;</pre>
</blockquote>
The <tt>Manager</tt> parses the URL, recognizes the content type and creates
a <tt>Player</tt> to handle the presentation of the data. The resulting
<tt>Player</tt>
is returned for use by the application.
Connections created by 
<code>createPlayer</code> follow the <code>Generic Connection</code>
framework rules and policies.
<p>The <tt>Player</tt> provides general methods to control the data flow
and presentation, for example:
<blockquote>
<pre>Player.realize()&nbsp;
Player.prefetch()&nbsp;
Player.start()</pre>
</blockquote>
Fine-grained control is an important feature of the API; therefore, each
<tt>Player</tt>
also provides type-specific controls with the <tt>getControls </tt>and<tt>
getControl</tt> methods:
<blockquote><tt>Control[] Player.getControls()</tt>
<br><tt>Control Player.getControl(int controlType)</tt></blockquote>
Since different types of media will yield different types of controls from
its corresponding <tt>Player</tt>, the <tt>getControls and getControl</tt>
methods can expose features that are unique to a particular media type.</blockquote>

<h3>
Tone Generation</h3>

<blockquote>Tone generation is important for games and other audio applications.&nbsp;
On very small devices, it is particularly important since that is likely
to be the only form of multimedia capabilities supported.&nbsp; In its
simplest form, tone generation reduces to a single buzzer or some simple
monophonic tone generation.&nbsp; The Manager class provides a top level
method to handle this simple form of single tone generation:
<blockquote>
<code>Manager.playTone(int note, int duration, int volume)</code>
</blockquote>
The implementation of this method can be mapped directly to the device's
hardware tone generator to provide the most responsive sound generation.
<p>In addition, the API also provides a way to create a specific type of
Player for synthesizing tone sequences:
<blockquote>
<tt>Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR)</tt>
</blockquote>
The Player created provides a special type of Control, ToneControl which
can be used for programming a tone sequence.&nbsp; This enables more sophisticated
applications written for slightly more powerful devices.</blockquote>

<h3>
Usage Scenarios</h3>

<blockquote>In this section we demonstrate how the API could be used in
four common scenarios.
<h4 STYLE="font-weight: medium">
<tt>Scenario 1: Single-Tone Generation</tt></h4>
<pre>
<blockquote>
try {
    Manager.playTone(ToneControl.C4, 5000 /* ms */, 100 /* max vol */);
} catch (MediaException e) { }
</blockquote>
</pre>

<h4 STYLE="font-weight: medium">
<tt>Scenario 2: Simple Media Playback with Looping</tt></h4>
<tt>Notice that in MIDP 2.0 the wav format is mandatory only in a case
the device supports sampled audio.</tt>

<pre>
<blockquote>
try {
    Player p = Manager.createPlayer("http://webserver/music.wav");
    p.setLoopCount(5);
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

<h4>
<tt>Scenario 3: Playing Back from Media Stored in JAR</tt></h4>
<tt>Notice that in MIDP 2.0 the wav format is mandatory only in a case
the device supports sampled audio.</tt>

<pre>
<blockquote>
try {
    InputStream is = getClass().getResourceAsStream("music.wav");
    Player p = Manager.createPlayer(is, "audio/X-wav");
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

<h4>
<tt>Scenario 4: Tone Sequence Generation</tt></h4>

<pre>
<blockquote>
/**
 * "Mary Had A Little Lamb" has "ABAC" structure.
 * Use block to repeat "A" section.
 */
byte tempo = 30; // set tempo to 120 bpm
byte d = 8;      // eighth-note

byte C4 = ToneControl.C4;;
byte D4 = (byte)(C4 + 2); // a whole step
byte E4 = (byte)(C4 + 4); // a major third
byte G4 = (byte)(C4 + 7); // a fifth
byte rest = ToneControl.SILENCE; // rest

byte[] mySequence = {
    ToneControl.VERSION, 1,   // version 1
    ToneControl.TEMPO, tempo, // set tempo
    ToneControl.BLOCK_START, 0,   // start define "A" section
    E4,d, D4,d, C4,d, E4,d,       // content of "A" section
    E4,d, E4,d, E4,d, rest,d,
    ToneControl.BLOCK_END, 0,     // end define "A" section
    ToneControl.PLAY_BLOCK, 0,    // play "A" section
    D4,d, D4,d, D4,d, rest,d,     // play "B" section
    E4,d, G4,d, G4,d, rest,d,
    ToneControl.PLAY_BLOCK, 0,    // repeat "A" section
    D4,d, D4,d, E4,d, D4,d, C4,d  // play "C" section
};

try{
    Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR);
    p.realize();
    ToneControl c = (ToneControl)p.getControl("ToneControl");
    c.setSequence(mySequence);
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

</blockquote>
<P>
<DL>
<DT><B>Since: </B><DD>MIDP 2.0</DD>
</DL>
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<strong>MIDP 2.0</strong></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/microedition/lcdui/game/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../javax/microedition/media/control/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<font size="-1"><a href="mailto:[e-mail]">Send a comment or suggestion</a> Version 2.0 of Mobile Information Device Profile Specification<br>Java is a trademark or registered trademark of Sun Microsystems,  Inc. in the US and other countries. Copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.</font>
</BODY>
</HTML>