/*
*
* Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
package javax.microedition.media.control;
/**
* <code>RateControl</code> controls the playback rate of a
* <code>Player</code>.<p>
*
* The rate defines the relationship between the
* <code>Player's</code> <i>media time</i> and its
* <code>TimeBase</code>. Rates are specified in "milli-
* percentage".<p>
*
* For example, a rate of 200'000 indicates that <i>media
* time</i> will pass twice as fast as the
* <code>TimeBase</code> time once the <code>Player</code>
* starts. Similarly, a negative rate indicates that the
* <code>Player</code> runs in the opposite direction of its
* <code>TimeBase</code>, i.e. playing in reverse.<p>
*
* All <code>Player</code> must support the default rate
* 100'000. <code>Player</code>s that support only the default
* rate must not implement this interface.
* <code>Player</code>s that support other rates besides
* 100'000, should implement this interface and specify the
* appropriate minimum and maximum playback rates.<p>
*
* For audio, specific implementations may change the playback
* pitch when changing the playback rate. This may be viewed as an
* undesirable side-effect. See <code>PitchControl</code> for
* changing pitch without changing playback rate.
*
* @see javax.microedition.media.Player
* @see javax.microedition.media.control.TempoControl
* @see javax.microedition.media.control.PitchControl
*/
public interface RateControl extends javax.microedition.media.Control {
/**
* Sets the playback rate.
*
* The specified rate is 1000 times the percentage of the
* actual rate. For example, to play back at twice the speed, specify
* a rate of 200'000.<p>
*
* The <code>setRate</code> method returns the actual rate set by the
* <code>Player</code>. <code>Player</code> should set their rate
* as close to the requested
* value as possible, but are not required to set the rate to the exact
* value of any argument other than 100'000. A <code>Player</code>
* is only guaranteed to set
* its rate exactly to 100'000.
* If the given rate is less than <code>getMinRate</code>
* or greater than <code>getMaxRate</code>,
* the rate will be adjusted to the minimum or maximum
* supported rate respectively.
* <p>
* If the <code>Player</code> is already
* started, <code>setRate</code> will immediately take effect.
*
* @param millirate The playback rate to set. The rate is given in
* a "milli-percentage" value.
* @return The actual rate set in "milli-percentage".
* @see #getRate
*/
int setRate(int millirate);
/**
* Gets the current playback rate.
*
* @return the current playback rate in "milli-percentage".
* @see #setRate
*/
int getRate();
/**
* Gets the maximum playback rate supported by the <code>Player</code>.
*
* @return the maximum rate in "milli-percentage".
*/
int getMaxRate();
/**
* Gets the minimum playback rate supported by the <code>Player</code>.
*
* @return the minimum rate in "milli-percentage".
*/
int getMinRate();
}
|