| /* |
| * 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 java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| |
| import android.annotation.IntDef; |
| |
| /** |
| * Structure for common A/V sync params. |
| * |
| * Used by {@link MediaSync} {link MediaSync#getSyncParams()} and |
| * {link MediaSync#setSyncParams(SyncParams)} |
| * to control A/V sync behavior. |
| * <p> <strong>audio adjust mode:</strong> |
| * select handling of audio track when changing playback speed due to sync. |
| * <ul> |
| * <li> {@link SyncParams#AUDIO_ADJUST_MODE_DEFAULT}: |
| * System will determine best handling. </li> |
| * <li> {@link SyncParams#AUDIO_ADJUST_MODE_STRETCH}: |
| * Change the speed of audio playback without altering its pitch.</li> |
| * <li> {@link SyncParams#AUDIO_ADJUST_MODE_RESAMPLE}: |
| * Change the speed of audio playback by resampling the audio.</li> |
| * </ul> |
| * <p> <strong>sync source:</strong> select |
| * clock source for sync. |
| * <ul> |
| * <li> {@link SyncParams#SYNC_SOURCE_DEFAULT}: |
| * System will determine best selection.</li> |
| * <li> {@link SyncParams#SYNC_SOURCE_SYSTEM_CLOCK}: |
| * Use system clock for sync source.</li> |
| * <li> {@link SyncParams#SYNC_SOURCE_AUDIO}: |
| * Use audio track for sync source.</li> |
| * <li> {@link SyncParams#SYNC_SOURCE_VSYNC}: |
| * Syncronize media to vsync.</li> |
| * </ul> |
| * <p> <strong>tolerance:</strong> specifies the amount of allowed playback rate |
| * change to keep media in sync with the sync source. The handling of this depends |
| * on the sync source, but must not be negative, and must be less than one. |
| * <p> <strong>frameRate:</strong> initial hint for video frame rate. Used when |
| * sync source is vsync. Negative values can be used to clear a previous hint. |
| */ |
| public final class SyncParams { |
| /** @hide */ |
| @IntDef( |
| value = { |
| SYNC_SOURCE_DEFAULT, |
| SYNC_SOURCE_SYSTEM_CLOCK, |
| SYNC_SOURCE_AUDIO, |
| SYNC_SOURCE_VSYNC, |
| } |
| ) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface SyncSource {} |
| |
| /** |
| * Use the default sync source (default). If media has video, the sync renders to a |
| * surface that directly renders to a display, and tolerance is non zero (e.g. not |
| * less than 0.001) vsync source is used for clock source. Otherwise, if media has |
| * audio, audio track is used. Finally, if media has no audio, system clock is used. |
| */ |
| public static final int SYNC_SOURCE_DEFAULT = 0; |
| |
| /** |
| * Use system monotonic clock for sync source. |
| * |
| * @see System#nanoTime |
| */ |
| public static final int SYNC_SOURCE_SYSTEM_CLOCK = 1; |
| |
| /** |
| * Use audio track for sync source. This requires audio data and an audio track. |
| * |
| * @see android.media.AudioTrack#getTimestamp(android.media.AudioTimestamp) |
| */ |
| public static final int SYNC_SOURCE_AUDIO = 2; |
| |
| /** |
| * Use vsync as the sync source. This requires video data and an output surface that |
| * directly renders to the display, e.g. {@link android.view.SurfaceView} |
| * <p> |
| * This mode allows smoother playback experience by adjusting the playback speed |
| * to match the vsync rate, e.g. playing 30fps content on a 59.94Hz display. |
| * When using this mode, the tolerance should be set to greater than 0 (e.g. at least |
| * 1/1000), so that the playback speed can actually be adjusted. |
| * <p> |
| * This mode can also be used to play 25fps content on a 60Hz display using |
| * a 2:3 pulldown (basically playing the content at 24fps), which results on |
| * better playback experience on most devices. In this case the tolerance should be |
| * at least (1/24). |
| * |
| * @see android.view.Choreographer.FrameCallback#doFrame |
| * @see android.view.Display#getAppVsyncOffsetNanos |
| */ |
| public static final int SYNC_SOURCE_VSYNC = 3; |
| |
| /** @hide */ |
| @IntDef( |
| value = { |
| AUDIO_ADJUST_MODE_DEFAULT, |
| AUDIO_ADJUST_MODE_STRETCH, |
| AUDIO_ADJUST_MODE_RESAMPLE, |
| } |
| ) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface AudioAdjustMode {} |
| |
| /** |
| * System will determine best handling of audio for playback rate |
| * adjustments. |
| * <p> |
| * Used by default. This will make audio play faster or slower as required |
| * by the sync source without changing its pitch; however, system may fall |
| * back to some other method (e.g. change the pitch, or mute the audio) if |
| * time stretching is no longer supported for the playback rate. |
| */ |
| public static final int AUDIO_ADJUST_MODE_DEFAULT = 0; |
| |
| /** |
| * Time stretch audio when playback rate must be adjusted. |
| * <p> |
| * This will make audio play faster or slower as required by the sync source |
| * without changing its pitch, as long as it is supported for the playback |
| * rate. |
| */ |
| public static final int AUDIO_ADJUST_MODE_STRETCH = 1; |
| |
| /** |
| * Resample audio when playback rate must be adjusted. |
| * <p> |
| * This will make audio play faster or slower as required by the sync source |
| * by changing its pitch (making it lower to play slower, and higher to play |
| * faster.) |
| */ |
| public static final int AUDIO_ADJUST_MODE_RESAMPLE = 2; |
| |
| // flags to indicate which params are actually set |
| private static final int SET_SYNC_SOURCE = 1 << 0; |
| private static final int SET_AUDIO_ADJUST_MODE = 1 << 1; |
| private static final int SET_TOLERANCE = 1 << 2; |
| private static final int SET_FRAME_RATE = 1 << 3; |
| private int mSet = 0; |
| |
| // params |
| private int mAudioAdjustMode = AUDIO_ADJUST_MODE_DEFAULT; |
| private int mSyncSource = SYNC_SOURCE_DEFAULT; |
| private float mTolerance = 0.f; |
| private float mFrameRate = 0.f; |
| |
| /** |
| * 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>SyncParams</code> instance. |
| */ |
| public SyncParams allowDefaults() { |
| mSet |= SET_SYNC_SOURCE | SET_AUDIO_ADJUST_MODE | SET_TOLERANCE; |
| return this; |
| } |
| |
| /** |
| * Sets the audio adjust mode. |
| * @param audioAdjustMode |
| * @return this <code>SyncParams</code> instance. |
| */ |
| public SyncParams setAudioAdjustMode(@AudioAdjustMode int audioAdjustMode) { |
| mAudioAdjustMode = audioAdjustMode; |
| mSet |= SET_AUDIO_ADJUST_MODE; |
| return this; |
| } |
| |
| /** |
| * Retrieves the audio adjust mode. |
| * @return audio adjust mode |
| * @throws IllegalStateException if the audio adjust mode is not set. |
| */ |
| public @AudioAdjustMode int getAudioAdjustMode() { |
| if ((mSet & SET_AUDIO_ADJUST_MODE) == 0) { |
| throw new IllegalStateException("audio adjust mode not set"); |
| } |
| return mAudioAdjustMode; |
| } |
| |
| /** |
| * Sets the sync source. |
| * @param syncSource |
| * @return this <code>SyncParams</code> instance. |
| */ |
| public SyncParams setSyncSource(@SyncSource int syncSource) { |
| mSyncSource = syncSource; |
| mSet |= SET_SYNC_SOURCE; |
| return this; |
| } |
| |
| /** |
| * Retrieves the sync source. |
| * @return sync source |
| * @throws IllegalStateException if the sync source is not set. |
| */ |
| public @SyncSource int getSyncSource() { |
| if ((mSet & SET_SYNC_SOURCE) == 0) { |
| throw new IllegalStateException("sync source not set"); |
| } |
| return mSyncSource; |
| } |
| |
| /** |
| * Sets the tolerance. The default tolerance is platform specific, but is never more than 1/24. |
| * @param tolerance A non-negative number representing |
| * the maximum deviation of the playback rate from the playback rate |
| * set. ({@code abs(actual_rate - set_rate) / set_rate}) |
| * @return this <code>SyncParams</code> instance. |
| * @throws IllegalArgumentException if the tolerance is negative, or not less than one. |
| */ |
| public SyncParams setTolerance(float tolerance) { |
| if (tolerance < 0.f || tolerance >= 1.f) { |
| throw new IllegalArgumentException("tolerance must be less than one and non-negative"); |
| } |
| mTolerance = tolerance; |
| mSet |= SET_TOLERANCE; |
| return this; |
| } |
| |
| /** |
| * Retrieves the tolerance factor. |
| * @return tolerance factor. A non-negative number representing |
| * the maximum deviation of the playback rate from the playback rate |
| * set. ({@code abs(actual_rate - set_rate) / set_rate}) |
| * @throws IllegalStateException if tolerance is not set. |
| */ |
| public float getTolerance() { |
| if ((mSet & SET_TOLERANCE) == 0) { |
| throw new IllegalStateException("tolerance not set"); |
| } |
| return mTolerance; |
| } |
| |
| /** |
| * Sets the video frame rate hint to be used. By default the frame rate is unspecified. |
| * @param frameRate A non-negative number used as an initial hint on |
| * the video frame rate to be used when using vsync as the sync source. A negative |
| * number is used to clear a previous hint. |
| * @return this <code>SyncParams</code> instance. |
| */ |
| public SyncParams setFrameRate(float frameRate) { |
| mFrameRate = frameRate; |
| mSet |= SET_FRAME_RATE; |
| return this; |
| } |
| |
| /** |
| * Retrieves the video frame rate hint. |
| * @return frame rate factor. A non-negative number representing |
| * the maximum deviation of the playback rate from the playback rate |
| * set. ({@code abs(actual_rate - set_rate) / set_rate}), or a negative |
| * number representing the desire to clear a previous hint using these params. |
| * @throws IllegalStateException if frame rate is not set. |
| */ |
| public float getFrameRate() { |
| if ((mSet & SET_FRAME_RATE) == 0) { |
| throw new IllegalStateException("frame rate not set"); |
| } |
| return mFrameRate; |
| } |
| |
| } |
