PlaybackParams.java revision c9020aff3a3c45a52a234eae6e159a61af5811c5
1263b4c97823295c41900210515d0c769a236190cAndy Hung/* 2263b4c97823295c41900210515d0c769a236190cAndy Hung * Copyright 2015 The Android Open Source Project 3263b4c97823295c41900210515d0c769a236190cAndy Hung * 4263b4c97823295c41900210515d0c769a236190cAndy Hung * Licensed under the Apache License, Version 2.0 (the "License"); 5263b4c97823295c41900210515d0c769a236190cAndy Hung * you may not use this file except in compliance with the License. 6263b4c97823295c41900210515d0c769a236190cAndy Hung * You may obtain a copy of the License at 7263b4c97823295c41900210515d0c769a236190cAndy Hung * 8263b4c97823295c41900210515d0c769a236190cAndy Hung * http://www.apache.org/licenses/LICENSE-2.0 9263b4c97823295c41900210515d0c769a236190cAndy Hung * 10263b4c97823295c41900210515d0c769a236190cAndy Hung * Unless required by applicable law or agreed to in writing, software 11263b4c97823295c41900210515d0c769a236190cAndy Hung * distributed under the License is distributed on an "AS IS" BASIS, 12263b4c97823295c41900210515d0c769a236190cAndy Hung * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13263b4c97823295c41900210515d0c769a236190cAndy Hung * See the License for the specific language governing permissions and 14263b4c97823295c41900210515d0c769a236190cAndy Hung * limitations under the License. 15263b4c97823295c41900210515d0c769a236190cAndy Hung */ 16263b4c97823295c41900210515d0c769a236190cAndy Hung 17263b4c97823295c41900210515d0c769a236190cAndy Hungpackage android.media; 18263b4c97823295c41900210515d0c769a236190cAndy Hung 19263b4c97823295c41900210515d0c769a236190cAndy Hungimport java.lang.annotation.Retention; 20263b4c97823295c41900210515d0c769a236190cAndy Hungimport java.lang.annotation.RetentionPolicy; 21263b4c97823295c41900210515d0c769a236190cAndy Hung 22263b4c97823295c41900210515d0c769a236190cAndy Hungimport android.annotation.IntDef; 23263b4c97823295c41900210515d0c769a236190cAndy Hung 24263b4c97823295c41900210515d0c769a236190cAndy Hung/** 252d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * Structure for common playback params. 26263b4c97823295c41900210515d0c769a236190cAndy Hung * 272d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * Used by {@link AudioTrack} {@link AudioTrack#getPlaybackParams()} and 282d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * {@link AudioTrack#setPlaybackParams(PlaybackParams)} 29263b4c97823295c41900210515d0c769a236190cAndy Hung * to control playback behavior. 30263b4c97823295c41900210515d0c769a236190cAndy Hung * <p> <strong>audio fallback mode:</strong> 31263b4c97823295c41900210515d0c769a236190cAndy Hung * select out-of-range parameter handling. 32263b4c97823295c41900210515d0c769a236190cAndy Hung * <ul> 332d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_DEFAULT}: 34263b4c97823295c41900210515d0c769a236190cAndy Hung * System will determine best handling. </li> 352d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_MUTE}: 362d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * Play silence for params normally out of range.</li> 372d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_FAIL}: 38263b4c97823295c41900210515d0c769a236190cAndy Hung * Return {@link java.lang.IllegalArgumentException} from 392d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * <code>AudioTrack.setPlaybackParams(PlaybackParams)</code>.</li> 40263b4c97823295c41900210515d0c769a236190cAndy Hung * </ul> 41263b4c97823295c41900210515d0c769a236190cAndy Hung * <p> <strong>pitch:</strong> increases or decreases the tonal frequency of the audio content. 42263b4c97823295c41900210515d0c769a236190cAndy Hung * It is expressed as a multiplicative factor, where normal pitch is 1.0f. 43263b4c97823295c41900210515d0c769a236190cAndy Hung * <p> <strong>speed:</strong> increases or decreases the time to 44263b4c97823295c41900210515d0c769a236190cAndy Hung * play back a set of audio or video frames. 45263b4c97823295c41900210515d0c769a236190cAndy Hung * It is expressed as a multiplicative factor, where normal speed is 1.0f. 46263b4c97823295c41900210515d0c769a236190cAndy Hung * <p> Different combinations of speed and pitch may be used for audio playback; 47263b4c97823295c41900210515d0c769a236190cAndy Hung * some common ones: 48263b4c97823295c41900210515d0c769a236190cAndy Hung * <ul> 49263b4c97823295c41900210515d0c769a236190cAndy Hung * <li> <em>Pitch equals 1.0f.</em> Speed change will be done with pitch preserved, 50263b4c97823295c41900210515d0c769a236190cAndy Hung * often called <em>timestretching</em>.</li> 51263b4c97823295c41900210515d0c769a236190cAndy Hung * <li> <em>Pitch equals speed.</em> Speed change will be done by <em>resampling</em>, 52263b4c97823295c41900210515d0c769a236190cAndy Hung * similar to {@link AudioTrack#setPlaybackRate(int)}.</li> 53263b4c97823295c41900210515d0c769a236190cAndy Hung * </ul> 54263b4c97823295c41900210515d0c769a236190cAndy Hung */ 552d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jiapublic final class PlaybackParams { 56263b4c97823295c41900210515d0c769a236190cAndy Hung /** @hide */ 57263b4c97823295c41900210515d0c769a236190cAndy Hung @IntDef( 58263b4c97823295c41900210515d0c769a236190cAndy Hung value = { 59263b4c97823295c41900210515d0c769a236190cAndy Hung AUDIO_FALLBACK_MODE_DEFAULT, 60263b4c97823295c41900210515d0c769a236190cAndy Hung AUDIO_FALLBACK_MODE_MUTE, 61263b4c97823295c41900210515d0c769a236190cAndy Hung AUDIO_FALLBACK_MODE_FAIL, 62263b4c97823295c41900210515d0c769a236190cAndy Hung } 63263b4c97823295c41900210515d0c769a236190cAndy Hung ) 64263b4c97823295c41900210515d0c769a236190cAndy Hung @Retention(RetentionPolicy.SOURCE) 65263b4c97823295c41900210515d0c769a236190cAndy Hung public @interface AudioFallbackMode {} 66263b4c97823295c41900210515d0c769a236190cAndy Hung public static final int AUDIO_FALLBACK_MODE_DEFAULT = 0; 67263b4c97823295c41900210515d0c769a236190cAndy Hung public static final int AUDIO_FALLBACK_MODE_MUTE = 1; 68263b4c97823295c41900210515d0c769a236190cAndy Hung public static final int AUDIO_FALLBACK_MODE_FAIL = 2; 69263b4c97823295c41900210515d0c769a236190cAndy Hung 70263b4c97823295c41900210515d0c769a236190cAndy Hung /** @hide */ 71263b4c97823295c41900210515d0c769a236190cAndy Hung @IntDef( 72263b4c97823295c41900210515d0c769a236190cAndy Hung value = { 73263b4c97823295c41900210515d0c769a236190cAndy Hung AUDIO_STRETCH_MODE_DEFAULT, 74263b4c97823295c41900210515d0c769a236190cAndy Hung AUDIO_STRETCH_MODE_VOICE, 75263b4c97823295c41900210515d0c769a236190cAndy Hung } 76263b4c97823295c41900210515d0c769a236190cAndy Hung ) 77263b4c97823295c41900210515d0c769a236190cAndy Hung @Retention(RetentionPolicy.SOURCE) 78263b4c97823295c41900210515d0c769a236190cAndy Hung public @interface AudioStretchMode {} 7918cb3b5a27148c7d4556db4a55e8c2bafafef32cAndy Hung /** @hide */ 80263b4c97823295c41900210515d0c769a236190cAndy Hung public static final int AUDIO_STRETCH_MODE_DEFAULT = 0; 8118cb3b5a27148c7d4556db4a55e8c2bafafef32cAndy Hung /** @hide */ 82263b4c97823295c41900210515d0c769a236190cAndy Hung public static final int AUDIO_STRETCH_MODE_VOICE = 1; 83263b4c97823295c41900210515d0c769a236190cAndy Hung 842d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia // flags to indicate which params are actually set 85263b4c97823295c41900210515d0c769a236190cAndy Hung private static final int SET_SPEED = 1 << 0; 86263b4c97823295c41900210515d0c769a236190cAndy Hung private static final int SET_PITCH = 1 << 1; 87263b4c97823295c41900210515d0c769a236190cAndy Hung private static final int SET_AUDIO_FALLBACK_MODE = 1 << 2; 88263b4c97823295c41900210515d0c769a236190cAndy Hung private static final int SET_AUDIO_STRETCH_MODE = 1 << 3; 89263b4c97823295c41900210515d0c769a236190cAndy Hung private int mSet = 0; 90263b4c97823295c41900210515d0c769a236190cAndy Hung 912d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia // params 92263b4c97823295c41900210515d0c769a236190cAndy Hung private int mAudioFallbackMode = AUDIO_FALLBACK_MODE_DEFAULT; 93263b4c97823295c41900210515d0c769a236190cAndy Hung private int mAudioStretchMode = AUDIO_STRETCH_MODE_DEFAULT; 94263b4c97823295c41900210515d0c769a236190cAndy Hung private float mPitch = 1.0f; 95263b4c97823295c41900210515d0c769a236190cAndy Hung private float mSpeed = 1.0f; 96263b4c97823295c41900210515d0c769a236190cAndy Hung 97263b4c97823295c41900210515d0c769a236190cAndy Hung /** 98263b4c97823295c41900210515d0c769a236190cAndy Hung * Allows defaults to be returned for properties not set. 99263b4c97823295c41900210515d0c769a236190cAndy Hung * Otherwise a {@link java.lang.IllegalArgumentException} exception 100263b4c97823295c41900210515d0c769a236190cAndy Hung * is raised when getting those properties 101263b4c97823295c41900210515d0c769a236190cAndy Hung * which have defaults but have never been set. 1022d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * @return this <code>PlaybackParams</code> instance. 103263b4c97823295c41900210515d0c769a236190cAndy Hung */ 1042d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia public PlaybackParams allowDefaults() { 105263b4c97823295c41900210515d0c769a236190cAndy Hung mSet |= SET_AUDIO_FALLBACK_MODE | SET_AUDIO_STRETCH_MODE | SET_PITCH | SET_SPEED; 106263b4c97823295c41900210515d0c769a236190cAndy Hung return this; 107263b4c97823295c41900210515d0c769a236190cAndy Hung } 108263b4c97823295c41900210515d0c769a236190cAndy Hung 109263b4c97823295c41900210515d0c769a236190cAndy Hung /** 110263b4c97823295c41900210515d0c769a236190cAndy Hung * Sets the audio fallback mode. 111263b4c97823295c41900210515d0c769a236190cAndy Hung * @param audioFallbackMode 1122d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * @return this <code>PlaybackParams</code> instance. 113263b4c97823295c41900210515d0c769a236190cAndy Hung */ 1142d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia public PlaybackParams setAudioFallbackMode(@AudioFallbackMode int audioFallbackMode) { 115263b4c97823295c41900210515d0c769a236190cAndy Hung mAudioFallbackMode = audioFallbackMode; 116263b4c97823295c41900210515d0c769a236190cAndy Hung mSet |= SET_AUDIO_FALLBACK_MODE; 117263b4c97823295c41900210515d0c769a236190cAndy Hung return this; 118263b4c97823295c41900210515d0c769a236190cAndy Hung } 119263b4c97823295c41900210515d0c769a236190cAndy Hung 120263b4c97823295c41900210515d0c769a236190cAndy Hung /** 121263b4c97823295c41900210515d0c769a236190cAndy Hung * Retrieves the audio fallback mode. 122263b4c97823295c41900210515d0c769a236190cAndy Hung * @return audio fallback mode 123263b4c97823295c41900210515d0c769a236190cAndy Hung * @throws IllegalStateException if the audio fallback mode is not set. 124263b4c97823295c41900210515d0c769a236190cAndy Hung */ 125263b4c97823295c41900210515d0c769a236190cAndy Hung public @AudioFallbackMode int getAudioFallbackMode() { 126263b4c97823295c41900210515d0c769a236190cAndy Hung if ((mSet & SET_AUDIO_FALLBACK_MODE) == 0) { 127263b4c97823295c41900210515d0c769a236190cAndy Hung throw new IllegalStateException("audio fallback mode not set"); 128263b4c97823295c41900210515d0c769a236190cAndy Hung } 129263b4c97823295c41900210515d0c769a236190cAndy Hung return mAudioFallbackMode; 130263b4c97823295c41900210515d0c769a236190cAndy Hung } 131263b4c97823295c41900210515d0c769a236190cAndy Hung 132263b4c97823295c41900210515d0c769a236190cAndy Hung /** 13318cb3b5a27148c7d4556db4a55e8c2bafafef32cAndy Hung * @hide 134263b4c97823295c41900210515d0c769a236190cAndy Hung * Sets the audio stretch mode. 135263b4c97823295c41900210515d0c769a236190cAndy Hung * @param audioStretchMode 1362d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * @return this <code>PlaybackParams</code> instance. 137263b4c97823295c41900210515d0c769a236190cAndy Hung */ 1382d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia public PlaybackParams setAudioStretchMode(@AudioStretchMode int audioStretchMode) { 139263b4c97823295c41900210515d0c769a236190cAndy Hung mAudioStretchMode = audioStretchMode; 140263b4c97823295c41900210515d0c769a236190cAndy Hung mSet |= SET_AUDIO_STRETCH_MODE; 141263b4c97823295c41900210515d0c769a236190cAndy Hung return this; 142263b4c97823295c41900210515d0c769a236190cAndy Hung } 143263b4c97823295c41900210515d0c769a236190cAndy Hung 144263b4c97823295c41900210515d0c769a236190cAndy Hung /** 14518cb3b5a27148c7d4556db4a55e8c2bafafef32cAndy Hung * @hide 146263b4c97823295c41900210515d0c769a236190cAndy Hung * Retrieves the audio stretch mode. 147263b4c97823295c41900210515d0c769a236190cAndy Hung * @return audio stretch mode 148263b4c97823295c41900210515d0c769a236190cAndy Hung * @throws IllegalStateException if the audio stretch mode is not set. 149263b4c97823295c41900210515d0c769a236190cAndy Hung */ 150263b4c97823295c41900210515d0c769a236190cAndy Hung public @AudioStretchMode int getAudioStretchMode() { 151263b4c97823295c41900210515d0c769a236190cAndy Hung if ((mSet & SET_AUDIO_STRETCH_MODE) == 0) { 152263b4c97823295c41900210515d0c769a236190cAndy Hung throw new IllegalStateException("audio stretch mode not set"); 153263b4c97823295c41900210515d0c769a236190cAndy Hung } 154263b4c97823295c41900210515d0c769a236190cAndy Hung return mAudioStretchMode; 155263b4c97823295c41900210515d0c769a236190cAndy Hung } 156263b4c97823295c41900210515d0c769a236190cAndy Hung 157263b4c97823295c41900210515d0c769a236190cAndy Hung /** 158263b4c97823295c41900210515d0c769a236190cAndy Hung * Sets the pitch factor. 159263b4c97823295c41900210515d0c769a236190cAndy Hung * @param pitch 1602d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * @return this <code>PlaybackParams</code> instance. 161c9020aff3a3c45a52a234eae6e159a61af5811c5Lajos Molnar * @throws InvalidArgumentException if the pitch is negative 162263b4c97823295c41900210515d0c769a236190cAndy Hung */ 1632d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia public PlaybackParams setPitch(float pitch) { 164c9020aff3a3c45a52a234eae6e159a61af5811c5Lajos Molnar if (pitch < 0.f) { 165c9020aff3a3c45a52a234eae6e159a61af5811c5Lajos Molnar throw new IllegalArgumentException("pitch must not be negative"); 166c9020aff3a3c45a52a234eae6e159a61af5811c5Lajos Molnar } 167263b4c97823295c41900210515d0c769a236190cAndy Hung mPitch = pitch; 168263b4c97823295c41900210515d0c769a236190cAndy Hung mSet |= SET_PITCH; 169263b4c97823295c41900210515d0c769a236190cAndy Hung return this; 170263b4c97823295c41900210515d0c769a236190cAndy Hung } 171263b4c97823295c41900210515d0c769a236190cAndy Hung 172263b4c97823295c41900210515d0c769a236190cAndy Hung /** 173263b4c97823295c41900210515d0c769a236190cAndy Hung * Retrieves the pitch factor. 174263b4c97823295c41900210515d0c769a236190cAndy Hung * @return pitch 175263b4c97823295c41900210515d0c769a236190cAndy Hung * @throws IllegalStateException if pitch is not set. 176263b4c97823295c41900210515d0c769a236190cAndy Hung */ 177263b4c97823295c41900210515d0c769a236190cAndy Hung public float getPitch() { 178263b4c97823295c41900210515d0c769a236190cAndy Hung if ((mSet & SET_PITCH) == 0) { 179263b4c97823295c41900210515d0c769a236190cAndy Hung throw new IllegalStateException("pitch not set"); 180263b4c97823295c41900210515d0c769a236190cAndy Hung } 181263b4c97823295c41900210515d0c769a236190cAndy Hung return mPitch; 182263b4c97823295c41900210515d0c769a236190cAndy Hung } 183263b4c97823295c41900210515d0c769a236190cAndy Hung 184263b4c97823295c41900210515d0c769a236190cAndy Hung /** 185263b4c97823295c41900210515d0c769a236190cAndy Hung * Sets the speed factor. 186263b4c97823295c41900210515d0c769a236190cAndy Hung * @param speed 1872d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia * @return this <code>PlaybackParams</code> instance. 188263b4c97823295c41900210515d0c769a236190cAndy Hung */ 1892d61e2b97c92ac2de80ebb3782b728ae5cdf5306Wei Jia public PlaybackParams setSpeed(float speed) { 190263b4c97823295c41900210515d0c769a236190cAndy Hung mSpeed = speed; 191263b4c97823295c41900210515d0c769a236190cAndy Hung mSet |= SET_SPEED; 192263b4c97823295c41900210515d0c769a236190cAndy Hung return this; 193263b4c97823295c41900210515d0c769a236190cAndy Hung } 194263b4c97823295c41900210515d0c769a236190cAndy Hung 195263b4c97823295c41900210515d0c769a236190cAndy Hung /** 196263b4c97823295c41900210515d0c769a236190cAndy Hung * Retrieves the speed factor. 197263b4c97823295c41900210515d0c769a236190cAndy Hung * @return speed 198263b4c97823295c41900210515d0c769a236190cAndy Hung * @throws IllegalStateException if speed is not set. 199263b4c97823295c41900210515d0c769a236190cAndy Hung */ 200263b4c97823295c41900210515d0c769a236190cAndy Hung public float getSpeed() { 201263b4c97823295c41900210515d0c769a236190cAndy Hung if ((mSet & SET_SPEED) == 0) { 202263b4c97823295c41900210515d0c769a236190cAndy Hung throw new IllegalStateException("speed not set"); 203263b4c97823295c41900210515d0c769a236190cAndy Hung } 204263b4c97823295c41900210515d0c769a236190cAndy Hung return mSpeed; 205263b4c97823295c41900210515d0c769a236190cAndy Hung } 206263b4c97823295c41900210515d0c769a236190cAndy Hung} 207