001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.control;
027:
028: /**
029: * TempoControl controls the tempo, in musical terms, of a song.
030: * <p>
031: *
032: * TempoControl is typically implemented in Players for MIDI
033: * media, i.e. playback of a Standard MIDI File (SMF).<p>
034: *
035: * TempoControl is basic functionality for a MIDI playback
036: * application. This is in contrast to {@link MIDIControl MIDIControl},
037: * which targets advanced applications. Moreover, TempoControl
038: * needs a sequence - e.g. a MIDI file - to operate. MIDIControl
039: * does not require a sequence.<p>
040: *
041: * Musical tempo is usually specified in beats per minute. To
042: * provide a means to access tempos with fractional beats per
043: * minute, the methods to set and get the tempo work on
044: * "milli-beat" per minute. A simple division by
045: * 1000 is sufficient to get the actual beats per minute.<p>
046: *
047: * As a MIDI file can contain any number of tempo changes
048: * during playback, the absolute tempo is a state of the
049: * sequencer. During playback of a MIDI file, setting the tempo
050: * in response to a user interaction will not always yield the
051: * desired result: the user's tempo can be overridden by the
052: * playing MIDI file to another tempo just moments later.<br>
053: * In order to overcome this problem, a relative tempo rate is
054: * used (in Java Sound terms: tempo factor). This rate is
055: * applied to all tempo settings. The tempo rate is specified
056: * in "milli-percent", i.e. a value of 100'000 means
057: * playback at original tempo. The tempo rate is set with the
058: * <code>setRate()</code> method of the super class,
059: * {@link RateControl RateControl}.<p>
060: *
061: * The concept of tempo rate allows one to play back a MIDI sequence
062: * at a different tempo without losing the relative tempo changes
063: * in it.<p>
064: *
065: * The <code>setTempo()</code> and <code>getTempo()</code> methods
066: * do <b>not</b> affect or reflect the playback rate. This means that
067: * changing the
068: * rate will not result in a change of the value returned by
069: * <code>getTempo()</code>. Similarly, setting the tempo with
070: * <code>setTempo()</code> does not change the rate, i.e.
071: * the return value of <code>getRate()</code> is not changed. The
072: * effective playback tempo is always the product of tempo and rate:<br>
073: * <br>
074: * <code>
075: * effectiveBeatsPerMinute = getTempo()
076: * getRate() / 1000 / 100000</code>
077: * <p>
078: *
079: * @see javax.microedition.media.Player
080: * @see javax.microedition.media.control.RateControl
081: * @see javax.microedition.media.control.PitchControl
082: * @see javax.microedition.media.control.MIDIControl
083: */
084:
085: public interface TempoControl extends RateControl {
086:
087: /**
088: * Sets the current playback tempo.
089: *
090: * Tempo is a volatile state of the sequencer. As MIDI sequences
091: * may contain META tempo events, tempo may change during
092: * playback of the sequence. Setting the tempo with
093: * <code>setTempo()</code> does not prevent the tempo from
094: * being changed subsequently by tempo events in the MIDI
095: * sequence. Example: during playback of a sequence,
096: * the user changes the tempo. But just moments later, the
097: * MIDI sequence changes the tempo to another value, so
098: * effectively the user interaction is ignored.
099: * To overcome this, and to allow consistent user interaction,
100: * use <code>{@link RateControl#setRate(int) setRate()}</code>
101: * inherited from <code>RateControl</code>.<p>
102: *
103: * The <code>setTempo()</code> method returns the actual tempo
104: * set by the <code>Player</code>'s implementation. It
105: * sets the tempo as close to the requested value as possible,
106: * but is not required to set it to the exact value. Specifically,
107: * implementations may have a lower or upper limit, which will
108: * be used as tempo if the requested tempo is out of limits.
109: * 0 or negative tempo does not exist and will always result
110: * in the lower tempo limit of the implementation. Implementations
111: * are guaranteed to support 10'000 to 300'000 milli-beats per minute.<p>
112: *
113: * Setting tempo to a stopped sequence will force the
114: * sequence to start with that tempo, even if the sequence has a tempo
115: * event at the start position. Any subsequent tempo events in
116: * the sequence will be considered, though. Rewinding back to
117: * a position with a tempo event will result in a
118: * tempo change caused by the tempo event, too. Example: a sequence
119: * with initial tempo of 120bpm has not been started yet. The
120: * user sets the tempo to 140bpm and starts playback. When the
121: * playback position is then reset to the beginning, the tempo will be
122: * set to 120bpm due to the tempo event at the beginning of the sequence.<p>
123: *
124: * Playback rate (see <code>{@link RateControl#setRate(int) setRate()}</code>)
125: * and tempo are independent factors of the effective tempo. Modifying
126: * tempo with <code>setTempo()</code> does not affect the playback
127: * rate and vice versa. The effective tempo is the product of tempo and rate.
128: *
129: * @param millitempo The tempo specified in milli-beats
130: * per minute (must be > 0, e.g. 120'000 for 120 beats per minute)
131: * @return tempo that was actually set, expressed in milli-beats per minute
132: * @see #getTempo
133: */
134:
135: int setTempo(int millitempo);
136:
137: /**
138: * Gets the current playback tempo.
139: * This represents the current state of the sequencer:
140: * <ul>
141: * <li>A sequencer may not be initialized before the
142: * <code>Player</code> is prefetched. An uninitialized
143: * sequencer in this case returns
144: * a default tempo of 120 beats per minute.</li>
145: * <li>After prefetching has finished, the tempo is
146: * set to the start tempo of the MIDI sequence (if any).</li>
147: * <li>During playback, the return value is the current tempo and
148: * varies with tempo events in the MIDI file</li>
149: * <li>A stopped sequence retains the last tempo it had
150: * before it was stopped.</li>
151: * <li>A call to <code>setTempo()</code> changes current tempo
152: * until a tempo event in the MIDI file is encountered.</li>
153: * </ul>
154: * @return current tempo, expressed in milli-beats per minute
155: * @see #setTempo
156: */
157: int getTempo();
158:
159: }
|