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:
030: * PitchControl raises or lowers the playback pitch of audio without
031: * changing the playback speed.
032: * <p>
033: *
034: * PitchControl can be implemented in Players for MIDI media or
035: * sampled audio. It is not possible to set audible output to
036: * an absolute pitch value. This control raises or lowers pitch
037: * relative to the original.<p>
038: *
039: * The pitch change is specified in number of "milli-
040: * semitones" to raise the pitch. As an example,
041: * specifying a pitch of 12'000 results in playback one octave
042: * higher. For MIDI that means that all MIDI notes are raised
043: * by 12 (semitones). For sampled audio playback, it means doubling the
044: * frequency of perceived sounds (i.e. a 440Hz sound will become a 880Hz
045: * sound.).
046: * Negative values are used to lower the pitch.
047: * <p>
048: * All <code>Players</code> by default support 0, or no pitch change.
049: * A <code>Player</code> which supports only 0 pitch change
050: * must not implement <code>PitchControl</code>.
051: * <p>
052: *
053: * PitchControl does not influence playback volume in any way.
054: *
055: * @see javax.microedition.media.Player
056: * @see javax.microedition.media.control.RateControl
057: * @see javax.microedition.media.control.TempoControl
058: */
059:
060: public interface PitchControl extends javax.microedition.media.Control {
061:
062: /**
063: * Sets the relative pitch raise.
064: *
065: * The pitch change is specified in "milli-
066: * semitones", i.e. 1000 times the number of
067: * semitones to raise the pitch. Negative values
068: * lower the pitch by the number of milli-semitones.<p>
069: *
070: * The <code>setPitch()</code> method returns the actual pitch
071: * change set by the {@link javax.microedition.media.Player Player}.
072: * <code>Players</code>
073: * should set their pitch raise as close to the requested value
074: * as possible, but are not required to set it to the exact
075: * value of any argument other than 0. A <code>Player</code> is
076: * only guaranteed to set its pitch change exactly to 0.
077: * If the given pitch raise is less than the value returned by
078: * <code>getMinPitch</code>
079: * or greater than the value returned by <code>getMaxPitch</code>,
080: * it will be adjusted to the minimum or maximum
081: * supported pitch raise respectively.
082: *
083: * @param millisemitones The number of semi tones to raise the playback pitch.
084: * It is specified in "milli-semitones".
085: * @return The actual pitch raise set in "milli-semitones".
086: * @see #getPitch
087: */
088: int setPitch(int millisemitones);
089:
090: /**
091: * Gets the current playback pitch raise.
092: *
093: * @return the current playback pitch raise in "milli-semitones".
094: * @see #setPitch
095: */
096: int getPitch();
097:
098: /**
099: * Gets the maximum playback pitch raise supported by the <code>Player</code>.
100: *
101: * @return the maximum pitch raise in "milli-semitones".
102: */
103: int getMaxPitch();
104:
105: /**
106: * Gets the minimum playback pitch raise supported by the <code>Player</code>.
107: *
108: * @return the minimum pitch raise in "milli-semitones".
109: */
110: int getMinPitch();
111:
112: }
|