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 17 package android.media; 18 19 import android.annotation.IntDef; 20 import android.os.Parcel; 21 import android.os.Parcelable; 22 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.RetentionPolicy; 25 26 /** 27 * Structure for common playback params. 28 * 29 * Used by {@link AudioTrack} {@link AudioTrack#getPlaybackParams()} and 30 * {@link AudioTrack#setPlaybackParams(PlaybackParams)} 31 * to control playback behavior. 32 * <p> <strong>audio fallback mode:</strong> 33 * select out-of-range parameter handling. 34 * <ul> 35 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_DEFAULT}: 36 * System will determine best handling. </li> 37 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_MUTE}: 38 * Play silence for params normally out of range.</li> 39 * <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_FAIL}: 40 * Return {@link java.lang.IllegalArgumentException} from 41 * <code>AudioTrack.setPlaybackParams(PlaybackParams)</code>.</li> 42 * </ul> 43 * <p> <strong>pitch:</strong> increases or decreases the tonal frequency of the audio content. 44 * It is expressed as a multiplicative factor, where normal pitch is 1.0f. 45 * <p> <strong>speed:</strong> increases or decreases the time to 46 * play back a set of audio or video frames. 47 * It is expressed as a multiplicative factor, where normal speed is 1.0f. 48 * <p> Different combinations of speed and pitch may be used for audio playback; 49 * some common ones: 50 * <ul> 51 * <li> <em>Pitch equals 1.0f.</em> Speed change will be done with pitch preserved, 52 * often called <em>timestretching</em>.</li> 53 * <li> <em>Pitch equals speed.</em> Speed change will be done by <em>resampling</em>, 54 * similar to {@link AudioTrack#setPlaybackRate(int)}.</li> 55 * </ul> 56 */ 57 public final class PlaybackParams implements Parcelable { 58 /** @hide */ 59 @IntDef( 60 value = { 61 AUDIO_FALLBACK_MODE_DEFAULT, 62 AUDIO_FALLBACK_MODE_MUTE, 63 AUDIO_FALLBACK_MODE_FAIL, 64 } 65 ) 66 @Retention(RetentionPolicy.SOURCE) 67 public @interface AudioFallbackMode {} 68 public static final int AUDIO_FALLBACK_MODE_DEFAULT = 0; 69 public static final int AUDIO_FALLBACK_MODE_MUTE = 1; 70 public static final int AUDIO_FALLBACK_MODE_FAIL = 2; 71 72 /** @hide */ 73 @IntDef( 74 value = { 75 AUDIO_STRETCH_MODE_DEFAULT, 76 AUDIO_STRETCH_MODE_VOICE, 77 } 78 ) 79 @Retention(RetentionPolicy.SOURCE) 80 public @interface AudioStretchMode {} 81 /** @hide */ 82 public static final int AUDIO_STRETCH_MODE_DEFAULT = 0; 83 /** @hide */ 84 public static final int AUDIO_STRETCH_MODE_VOICE = 1; 85 86 // flags to indicate which params are actually set 87 private static final int SET_SPEED = 1 << 0; 88 private static final int SET_PITCH = 1 << 1; 89 private static final int SET_AUDIO_FALLBACK_MODE = 1 << 2; 90 private static final int SET_AUDIO_STRETCH_MODE = 1 << 3; 91 private int mSet = 0; 92 93 // params 94 private int mAudioFallbackMode = AUDIO_FALLBACK_MODE_DEFAULT; 95 private int mAudioStretchMode = AUDIO_STRETCH_MODE_DEFAULT; 96 private float mPitch = 1.0f; 97 private float mSpeed = 1.0f; 98 PlaybackParams()99 public PlaybackParams() { 100 } 101 PlaybackParams(Parcel in)102 private PlaybackParams(Parcel in) { 103 mSet = in.readInt(); 104 mAudioFallbackMode = in.readInt(); 105 mAudioStretchMode = in.readInt(); 106 mPitch = in.readFloat(); 107 if (mPitch < 0.f) { 108 mPitch = 0.f; 109 } 110 mSpeed = in.readFloat(); 111 } 112 113 /** 114 * Allows defaults to be returned for properties not set. 115 * Otherwise a {@link java.lang.IllegalArgumentException} exception 116 * is raised when getting those properties 117 * which have defaults but have never been set. 118 * @return this <code>PlaybackParams</code> instance. 119 */ allowDefaults()120 public PlaybackParams allowDefaults() { 121 mSet |= SET_AUDIO_FALLBACK_MODE | SET_AUDIO_STRETCH_MODE | SET_PITCH | SET_SPEED; 122 return this; 123 } 124 125 /** 126 * Sets the audio fallback mode. 127 * @param audioFallbackMode 128 * @return this <code>PlaybackParams</code> instance. 129 */ setAudioFallbackMode(@udioFallbackMode int audioFallbackMode)130 public PlaybackParams setAudioFallbackMode(@AudioFallbackMode int audioFallbackMode) { 131 mAudioFallbackMode = audioFallbackMode; 132 mSet |= SET_AUDIO_FALLBACK_MODE; 133 return this; 134 } 135 136 /** 137 * Retrieves the audio fallback mode. 138 * @return audio fallback mode 139 * @throws IllegalStateException if the audio fallback mode is not set. 140 */ getAudioFallbackMode()141 public @AudioFallbackMode int getAudioFallbackMode() { 142 if ((mSet & SET_AUDIO_FALLBACK_MODE) == 0) { 143 throw new IllegalStateException("audio fallback mode not set"); 144 } 145 return mAudioFallbackMode; 146 } 147 148 /** 149 * @hide 150 * Sets the audio stretch mode. 151 * @param audioStretchMode 152 * @return this <code>PlaybackParams</code> instance. 153 */ setAudioStretchMode(@udioStretchMode int audioStretchMode)154 public PlaybackParams setAudioStretchMode(@AudioStretchMode int audioStretchMode) { 155 mAudioStretchMode = audioStretchMode; 156 mSet |= SET_AUDIO_STRETCH_MODE; 157 return this; 158 } 159 160 /** 161 * @hide 162 * Retrieves the audio stretch mode. 163 * @return audio stretch mode 164 * @throws IllegalStateException if the audio stretch mode is not set. 165 */ getAudioStretchMode()166 public @AudioStretchMode int getAudioStretchMode() { 167 if ((mSet & SET_AUDIO_STRETCH_MODE) == 0) { 168 throw new IllegalStateException("audio stretch mode not set"); 169 } 170 return mAudioStretchMode; 171 } 172 173 /** 174 * Sets the pitch factor. 175 * @param pitch 176 * @return this <code>PlaybackParams</code> instance. 177 * @throws IllegalArgumentException if the pitch is negative. 178 */ setPitch(float pitch)179 public PlaybackParams setPitch(float pitch) { 180 if (pitch < 0.f) { 181 throw new IllegalArgumentException("pitch must not be negative"); 182 } 183 mPitch = pitch; 184 mSet |= SET_PITCH; 185 return this; 186 } 187 188 /** 189 * Retrieves the pitch factor. 190 * @return pitch 191 * @throws IllegalStateException if pitch is not set. 192 */ getPitch()193 public float getPitch() { 194 if ((mSet & SET_PITCH) == 0) { 195 throw new IllegalStateException("pitch not set"); 196 } 197 return mPitch; 198 } 199 200 /** 201 * Sets the speed factor. 202 * @param speed 203 * @return this <code>PlaybackParams</code> instance. 204 */ setSpeed(float speed)205 public PlaybackParams setSpeed(float speed) { 206 mSpeed = speed; 207 mSet |= SET_SPEED; 208 return this; 209 } 210 211 /** 212 * Retrieves the speed factor. 213 * @return speed 214 * @throws IllegalStateException if speed is not set. 215 */ getSpeed()216 public float getSpeed() { 217 if ((mSet & SET_SPEED) == 0) { 218 throw new IllegalStateException("speed not set"); 219 } 220 return mSpeed; 221 } 222 223 public static final Parcelable.Creator<PlaybackParams> CREATOR = 224 new Parcelable.Creator<PlaybackParams>() { 225 @Override 226 public PlaybackParams createFromParcel(Parcel in) { 227 return new PlaybackParams(in); 228 } 229 230 @Override 231 public PlaybackParams[] newArray(int size) { 232 return new PlaybackParams[size]; 233 } 234 }; 235 236 237 @Override describeContents()238 public int describeContents() { 239 return 0; 240 } 241 242 @Override writeToParcel(Parcel dest, int flags)243 public void writeToParcel(Parcel dest, int flags) { 244 dest.writeInt(mSet); 245 dest.writeInt(mAudioFallbackMode); 246 dest.writeInt(mAudioStretchMode); 247 dest.writeFloat(mPitch); 248 dest.writeFloat(mSpeed); 249 } 250 } 251