public final class

PlaybackParams

extends java.lang.Object

 java.lang.Object

↳androidx.media2.PlaybackParams

Gradle dependencies

compile group: 'androidx.media2', name: 'media2', version: '1.0.0-alpha04'

  • groupId: androidx.media2
  • artifactId: media2
  • version: 1.0.0-alpha04

Artifact androidx.media2:media2:1.0.0-alpha04 it located at Google repository (https://maven.google.com/)

Androidx artifact mapping:

androidx.media2:media2 com.android.support:media2

Overview

Structure for common playback params. Used by MediaPlayer MediaPlayer.getPlaybackParams() and MediaPlayer.setPlaybackParams(PlaybackParams) to control playback behavior.

audio fallback mode: select out-of-range parameter handling.

pitch: increases or decreases the tonal frequency of the audio content. It is expressed as a multiplicative factor, where normal pitch is 1.0f.

speed: 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.

Different combinations of speed and pitch may be used for audio playback; some common ones:

  • Pitch equals 1.0f. Speed change will be done with pitch preserved, often called timestretching.
  • Pitch equals speed. Speed change will be done by resampling, similar to AudioTrack.

Summary

Fields
public static final intAUDIO_FALLBACK_MODE_DEFAULT

public static final intAUDIO_FALLBACK_MODE_FAIL

public static final intAUDIO_FALLBACK_MODE_MUTE

Methods
public java.lang.IntegergetAudioFallbackMode()

Returns the audio fallback mode.

public java.lang.FloatgetPitch()

Returns the pitch factor.

public android.media.PlaybackParamsgetPlaybackParams()

Returns the underlying framework object.

public java.lang.FloatgetSpeed()

Returns the speed factor.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Fields

public static final int AUDIO_FALLBACK_MODE_DEFAULT

public static final int AUDIO_FALLBACK_MODE_MUTE

public static final int AUDIO_FALLBACK_MODE_FAIL

Methods

public java.lang.Integer getAudioFallbackMode()

Returns the audio fallback mode. null if a value is not set.

public java.lang.Float getPitch()

Returns the pitch factor. null if a value is not set.

public java.lang.Float getSpeed()

Returns the speed factor. null if a value is not set.

public android.media.PlaybackParams getPlaybackParams()

Returns the underlying framework object. null if it is not available.

This method is only supported on and later.

Source

/*
 * Copyright 2018 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 androidx.media2;

import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;

import android.media.AudioTrack;
import android.os.Build;

import androidx.annotation.IntDef;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
import androidx.annotation.RestrictTo;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
 * Structure for common playback params.
 *
 * Used by {@link MediaPlayer} {@link MediaPlayer#getPlaybackParams()} and
 * {@link MediaPlayer#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 {
    /** @hide */
    @RestrictTo(LIBRARY_GROUP)
    @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;

    // params
    private Integer mAudioFallbackMode;
    private Float mPitch;
    private Float mSpeed;
    private android.media.PlaybackParams mPlaybackParams;

    PlaybackParams(Integer audioFallbackMode, Float pitch, Float speed) {
        mAudioFallbackMode = audioFallbackMode;
        mPitch = pitch;
        mSpeed = speed;
    }

    @RequiresApi(Build.VERSION_CODES.M)
    PlaybackParams(android.media.PlaybackParams playbackParams) {
        mPlaybackParams = playbackParams;
    }

    /**
     * Returns the audio fallback mode. {@code null} if a value is not set.
     */
    public @AudioFallbackMode @Nullable Integer getAudioFallbackMode() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            try {
                return mPlaybackParams.getAudioFallbackMode();
            } catch (IllegalStateException e) {
                return null;
            }
        } else {
            return mAudioFallbackMode;
        }
    }

    /**
     * Returns the pitch factor. {@code null} if a value is not set.
     */
    public @Nullable Float getPitch() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            try {
                return mPlaybackParams.getPitch();
            } catch (IllegalStateException e) {
                return null;
            }
        } else {
            return mPitch;
        }
    }

    /**
     * Returns the speed factor. {@code null} if a value is not set.
     */
    public @Nullable Float getSpeed() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            try {
                return mPlaybackParams.getSpeed();
            } catch (IllegalStateException e) {
                return null;
            }
        } else {
            return mSpeed;
        }
    }

    /**
     * Returns the underlying framework {@link android.media.PlaybackParams} object. {@code null}
     * if it is not available.
     * <p>
     * This method is only supported on {@link android.os.Build.VERSION_CODES#M} and later.
     * </p>
     *
     * @hide
     */
    @RestrictTo(LIBRARY_GROUP)
    @RequiresApi(Build.VERSION_CODES.M)
    public android.media.PlaybackParams getPlaybackParams() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            return mPlaybackParams;
        } else {
            return null;
        }
    }

    /**
     * The builder class that makes it easy to chain setters to create a {@link PlaybackParams}
     * object.
     */
    public static final class Builder {
        private Integer mAudioFallbackMode;
        private Float mPitch;
        private Float mSpeed;
        private android.media.PlaybackParams mPlaybackParams;

        public Builder() {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                mPlaybackParams = new android.media.PlaybackParams();
            }
        }

        /** @hide */
        @RestrictTo(LIBRARY_GROUP)
        @RequiresApi(Build.VERSION_CODES.M)
        public Builder(android.media.PlaybackParams playbackParams) {
            mPlaybackParams = playbackParams;
        }

        /**
         * Sets the audio fallback mode.
         *
         * @return this <code>Builder</code> instance.
         */
        public @NonNull Builder setAudioFallbackMode(@AudioFallbackMode int audioFallbackMode) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                mPlaybackParams.setAudioFallbackMode(audioFallbackMode);
            } else {
                mAudioFallbackMode = audioFallbackMode;
            }
            return this;
        }

        /**
         * Sets the pitch factor.
         *
         * @return this <code>Builder</code> instance.
         * @throws IllegalArgumentException if the pitch is negative.
         */
        public @NonNull Builder setPitch(float pitch) {
            if (pitch < 0.f) {
                throw new IllegalArgumentException("pitch must not be negative");
            }
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                mPlaybackParams.setPitch(pitch);
            } else {
                mPitch = pitch;
            }
            return this;
        }

        /**
         * Sets the speed factor.
         *
         * @return this <code>Builder</code> instance.
         */
        public @NonNull Builder setSpeed(float speed) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                mPlaybackParams.setSpeed(speed);
            } else {
                mSpeed = speed;
            }
            return this;
        }

        /**
         * Takes the values of the Builder object and creates a PlaybackParams object.
         * @return PlaybackParams object with values from the Builder.
         */
        public @NonNull PlaybackParams build() {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                return new PlaybackParams(mPlaybackParams);
            } else {
                return new PlaybackParams(mAudioFallbackMode, mPitch, mSpeed);
            }
        }
    }
}