PlaybackParams.java revision c9020aff3a3c45a52a234eae6e159a61af5811c5 
1/*
2 * Copyright 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.media;
18
19import java.lang.annotation.Retention;
20import java.lang.annotation.RetentionPolicy;
21
22import android.annotation.IntDef;
23
24/**
25 * Structure for common playback params.
26 *
27 * Used by {@link AudioTrack} {@link AudioTrack#getPlaybackParams()} and
28 * {@link AudioTrack#setPlaybackParams(PlaybackParams)}
29 * to control playback behavior.
30 * <p> <strong>audio fallback mode:</strong>
31 * select out-of-range parameter handling.
32 * <ul>
33 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_DEFAULT}:
34 *   System will determine best handling. </li>
35 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_MUTE}:
36 *   Play silence for params normally out of range.</li>
37 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_FAIL}:
38 *   Return {@link java.lang.IllegalArgumentException} from
39 *   <code>AudioTrack.setPlaybackParams(PlaybackParams)</code>.</li>
40 * </ul>
41 * <p> <strong>pitch:</strong> increases or decreases the tonal frequency of the audio content.
42 * It is expressed as a multiplicative factor, where normal pitch is 1.0f.
43 * <p> <strong>speed:</strong> increases or decreases the time to
44 * play back a set of audio or video frames.
45 * It is expressed as a multiplicative factor, where normal speed is 1.0f.
46 * <p> Different combinations of speed and pitch may be used for audio playback;
47 * some common ones:
48 * <ul>
49 * <li> <em>Pitch equals 1.0f.</em> Speed change will be done with pitch preserved,
50 * often called <em>timestretching</em>.</li>
51 * <li> <em>Pitch equals speed.</em> Speed change will be done by <em>resampling</em>,
52 * similar to {@link AudioTrack#setPlaybackRate(int)}.</li>
53 * </ul>
54 */
55public final class PlaybackParams {
56    /** @hide */
57    @IntDef(
58        value = {
59                AUDIO_FALLBACK_MODE_DEFAULT,
60                AUDIO_FALLBACK_MODE_MUTE,
61                AUDIO_FALLBACK_MODE_FAIL,
62        }
63    )
64    @Retention(RetentionPolicy.SOURCE)
65    public @interface AudioFallbackMode {}
66    public static final int AUDIO_FALLBACK_MODE_DEFAULT = 0;
67    public static final int AUDIO_FALLBACK_MODE_MUTE = 1;
68    public static final int AUDIO_FALLBACK_MODE_FAIL = 2;
69
70    /** @hide */
71    @IntDef(
72        value = {
73                AUDIO_STRETCH_MODE_DEFAULT,
74                AUDIO_STRETCH_MODE_VOICE,
75        }
76    )
77    @Retention(RetentionPolicy.SOURCE)
78    public @interface AudioStretchMode {}
79    /** @hide */
80    public static final int AUDIO_STRETCH_MODE_DEFAULT = 0;
81    /** @hide */
82    public static final int AUDIO_STRETCH_MODE_VOICE = 1;
83
84    // flags to indicate which params are actually set
85    private static final int SET_SPEED               = 1 << 0;
86    private static final int SET_PITCH               = 1 << 1;
87    private static final int SET_AUDIO_FALLBACK_MODE = 1 << 2;
88    private static final int SET_AUDIO_STRETCH_MODE  = 1 << 3;
89    private int mSet = 0;
90
91    // params
92    private int mAudioFallbackMode = AUDIO_FALLBACK_MODE_DEFAULT;
93    private int mAudioStretchMode = AUDIO_STRETCH_MODE_DEFAULT;
94    private float mPitch = 1.0f;
95    private float mSpeed = 1.0f;
96
97    /**
98     * Allows defaults to be returned for properties not set.
99     * Otherwise a {@link java.lang.IllegalArgumentException} exception
100     * is raised when getting those properties
101     * which have defaults but have never been set.
102     * @return this <code>PlaybackParams</code> instance.
103     */
104    public PlaybackParams allowDefaults() {
105        mSet |= SET_AUDIO_FALLBACK_MODE | SET_AUDIO_STRETCH_MODE | SET_PITCH | SET_SPEED;
106        return this;
107    }
108
109    /**
110     * Sets the audio fallback mode.
111     * @param audioFallbackMode
112     * @return this <code>PlaybackParams</code> instance.
113     */
114    public PlaybackParams setAudioFallbackMode(@AudioFallbackMode int audioFallbackMode) {
115        mAudioFallbackMode = audioFallbackMode;
116        mSet |= SET_AUDIO_FALLBACK_MODE;
117        return this;
118    }
119
120    /**
121     * Retrieves the audio fallback mode.
122     * @return audio fallback mode
123     * @throws IllegalStateException if the audio fallback mode is not set.
124     */
125    public @AudioFallbackMode int getAudioFallbackMode() {
126        if ((mSet & SET_AUDIO_FALLBACK_MODE) == 0) {
127            throw new IllegalStateException("audio fallback mode not set");
128        }
129        return mAudioFallbackMode;
130    }
131
132    /**
133     * @hide
134     * Sets the audio stretch mode.
135     * @param audioStretchMode
136     * @return this <code>PlaybackParams</code> instance.
137     */
138    public PlaybackParams setAudioStretchMode(@AudioStretchMode int audioStretchMode) {
139        mAudioStretchMode = audioStretchMode;
140        mSet |= SET_AUDIO_STRETCH_MODE;
141        return this;
142    }
143
144    /**
145     * @hide
146     * Retrieves the audio stretch mode.
147     * @return audio stretch mode
148     * @throws IllegalStateException if the audio stretch mode is not set.
149     */
150    public @AudioStretchMode int getAudioStretchMode() {
151        if ((mSet & SET_AUDIO_STRETCH_MODE) == 0) {
152            throw new IllegalStateException("audio stretch mode not set");
153        }
154        return mAudioStretchMode;
155    }
156
157    /**
158     * Sets the pitch factor.
159     * @param pitch
160     * @return this <code>PlaybackParams</code> instance.
161     * @throws InvalidArgumentException if the pitch is negative
162     */
163    public PlaybackParams setPitch(float pitch) {
164        if (pitch < 0.f) {
165            throw new IllegalArgumentException("pitch must not be negative");
166        }
167        mPitch = pitch;
168        mSet |= SET_PITCH;
169        return this;
170    }
171
172    /**
173     * Retrieves the pitch factor.
174     * @return pitch
175     * @throws IllegalStateException if pitch is not set.
176     */
177    public float getPitch() {
178        if ((mSet & SET_PITCH) == 0) {
179            throw new IllegalStateException("pitch not set");
180        }
181        return mPitch;
182    }
183
184    /**
185     * Sets the speed factor.
186     * @param speed
187     * @return this <code>PlaybackParams</code> instance.
188     */
189    public PlaybackParams setSpeed(float speed) {
190        mSpeed = speed;
191        mSet |= SET_SPEED;
192        return this;
193    }
194
195    /**
196     * Retrieves the speed factor.
197     * @return speed
198     * @throws IllegalStateException if speed is not set.
199     */
200    public float getSpeed() {
201        if ((mSet & SET_SPEED) == 0) {
202            throw new IllegalStateException("speed not set");
203        }
204        return mSpeed;
205    }
206}
207