/*
* Copyright 2015 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.media;
import android.annotation.IntDef;
import android.os.Parcel;
import android.os.Parcelable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Structure for common playback params.
*
* Used by {@link AudioTrack} {@link AudioTrack#getPlaybackParams()} and
* {@link AudioTrack#setPlaybackParams(PlaybackParams)}
* to control playback behavior.
* <p> <strong>audio fallback mode:</strong>
* select out-of-range parameter handling.
* <ul>
* <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_DEFAULT}:
* System will determine best handling. </li>
* <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_MUTE}:
* Play silence for params normally out of range.</li>
* <li> {@link PlaybackParams#AUDIO_FALLBACK_MODE_FAIL}:
* Return {@link java.lang.IllegalArgumentException} from
* <code>AudioTrack.setPlaybackParams(PlaybackParams)</code>.</li>
* </ul>
* <p> <strong>pitch:</strong> increases or decreases the tonal frequency of the audio content.
* It is expressed as a multiplicative factor, where normal pitch is 1.0f.
* <p> <strong>speed:</strong> increases or decreases the time to
* play back a set of audio or video frames.
* It is expressed as a multiplicative factor, where normal speed is 1.0f.
* <p> Different combinations of speed and pitch may be used for audio playback;
* some common ones:
* <ul>
* <li> <em>Pitch equals 1.0f.</em> Speed change will be done with pitch preserved,
* often called <em>timestretching</em>.</li>
* <li> <em>Pitch equals speed.</em> Speed change will be done by <em>resampling</em>,
* similar to {@link AudioTrack#setPlaybackRate(int)}.</li>
* </ul>
*/
public final class PlaybackParams implements Parcelable {
/** @hide */
@IntDef(
value = {
AUDIO_FALLBACK_MODE_DEFAULT,
AUDIO_FALLBACK_MODE_MUTE,
AUDIO_FALLBACK_MODE_FAIL,
}
)
@Retention(RetentionPolicy.SOURCE)
public @interface AudioFallbackMode {}
public static final int AUDIO_FALLBACK_MODE_DEFAULT = 0;
public static final int AUDIO_FALLBACK_MODE_MUTE = 1;
public static final int AUDIO_FALLBACK_MODE_FAIL = 2;
/** @hide */
@IntDef(
value = {
AUDIO_STRETCH_MODE_DEFAULT,
AUDIO_STRETCH_MODE_VOICE,
}
)
@Retention(RetentionPolicy.SOURCE)
public @interface AudioStretchMode {}
/** @hide */
public static final int AUDIO_STRETCH_MODE_DEFAULT = 0;
/** @hide */
public static final int AUDIO_STRETCH_MODE_VOICE = 1;
// flags to indicate which params are actually set
private static final int SET_SPEED = 1 << 0;
private static final int SET_PITCH = 1 << 1;
private static final int SET_AUDIO_FALLBACK_MODE = 1 << 2;
private static final int SET_AUDIO_STRETCH_MODE = 1 << 3;
private int mSet = 0;
// params
private int mAudioFallbackMode = AUDIO_FALLBACK_MODE_DEFAULT;
private int mAudioStretchMode = AUDIO_STRETCH_MODE_DEFAULT;
private float mPitch = 1.0f;
private float mSpeed = 1.0f;
public PlaybackParams() {
}
private PlaybackParams(Parcel in) {
mSet = in.readInt();
mAudioFallbackMode = in.readInt();
mAudioStretchMode = in.readInt();
mPitch = in.readFloat();
if (mPitch < 0.f) {
mPitch = 0.f;
}
mSpeed = in.readFloat();
}
/**
* Allows defaults to be returned for properties not set.
* Otherwise a {@link java.lang.IllegalArgumentException} exception
* is raised when getting those properties
* which have defaults but have never been set.
* @return this <code>PlaybackParams</code> instance.
*/
public PlaybackParams allowDefaults() {
mSet |= SET_AUDIO_FALLBACK_MODE | SET_AUDIO_STRETCH_MODE | SET_PITCH | SET_SPEED;
return this;
}
/**
* Sets the audio fallback mode.
* @param audioFallbackMode
* @return this <code>PlaybackParams</code> instance.
*/
public PlaybackParams setAudioFallbackMode(@AudioFallbackMode int audioFallbackMode) {
mAudioFallbackMode = audioFallbackMode;
mSet |= SET_AUDIO_FALLBACK_MODE;
return this;
}
/**
* Retrieves the audio fallback mode.
* @return audio fallback mode
* @throws IllegalStateException if the audio fallback mode is not set.
*/
public @AudioFallbackMode int getAudioFallbackMode() {
if ((mSet & SET_AUDIO_FALLBACK_MODE) == 0) {
throw new IllegalStateException("audio fallback mode not set");
}
return mAudioFallbackMode;
}
/**
* @hide
* Sets the audio stretch mode.
* @param audioStretchMode
* @return this <code>PlaybackParams</code> instance.
*/
public PlaybackParams setAudioStretchMode(@AudioStretchMode int audioStretchMode) {
mAudioStretchMode = audioStretchMode;
mSet |= SET_AUDIO_STRETCH_MODE;
return this;
}
/**
* @hide
* Retrieves the audio stretch mode.
* @return audio stretch mode
* @throws IllegalStateException if the audio stretch mode is not set.
*/
public @AudioStretchMode int getAudioStretchMode() {
if ((mSet & SET_AUDIO_STRETCH_MODE) == 0) {
throw new IllegalStateException("audio stretch mode not set");
}
return mAudioStretchMode;
}
/**
* Sets the pitch factor.
* @param pitch
* @return this <code>PlaybackParams</code> instance.
* @throws InvalidArgumentException if the pitch is negative
*/
public PlaybackParams setPitch(float pitch) {
if (pitch < 0.f) {
throw new IllegalArgumentException("pitch must not be negative");
}
mPitch = pitch;
mSet |= SET_PITCH;
return this;
}
/**
* Retrieves the pitch factor.
* @return pitch
* @throws IllegalStateException if pitch is not set.
*/
public float getPitch() {
if ((mSet & SET_PITCH) == 0) {
throw new IllegalStateException("pitch not set");
}
return mPitch;
}
/**
* Sets the speed factor.
* @param speed
* @return this <code>PlaybackParams</code> instance.
*/
public PlaybackParams setSpeed(float speed) {
mSpeed = speed;
mSet |= SET_SPEED;
return this;
}
/**
* Retrieves the speed factor.
* @return speed
* @throws IllegalStateException if speed is not set.
*/
public float getSpeed() {
if ((mSet & SET_SPEED) == 0) {
throw new IllegalStateException("speed not set");
}
return mSpeed;
}
public static final Parcelable.Creator<PlaybackParams> CREATOR =
new Parcelable.Creator<PlaybackParams>() {
@Override
public PlaybackParams createFromParcel(Parcel in) {
return new PlaybackParams(in);
}
@Override
public PlaybackParams[] newArray(int size) {
return new PlaybackParams[size];
}
};
@Override
public int describeContents() {
return 0;
}
@Override
public void writeToParcel(Parcel dest, int flags) {
dest.writeInt(mSet);
dest.writeInt(mAudioFallbackMode);
dest.writeInt(mAudioStretchMode);
dest.writeFloat(mPitch);
dest.writeFloat(mSpeed);
}
}