1 /* 2 * Copyright (C) 2013 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 java.lang.annotation.Retention; 20 import java.lang.annotation.RetentionPolicy; 21 22 import android.annotation.IntDef; 23 24 /** 25 * Structure that groups a position in frame units relative to an assumed audio stream, 26 * together with the estimated time when that frame enters or leaves the audio 27 * processing pipeline on that device. This can be used to coordinate events 28 * and interactions with the external environment. 29 * <p> 30 * The time is based on the implementation's best effort, using whatever knowledge 31 * is available to the system, but cannot account for any delay unknown to the implementation. 32 * 33 * @see AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp) 34 * @see AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int) 35 */ 36 public final class AudioTimestamp 37 { 38 /** 39 * Clock monotonic or its equivalent on the system, 40 * in the same units and timebase as {@link java.lang.System#nanoTime}. 41 */ 42 public static final int TIMEBASE_MONOTONIC = 0; 43 44 /** 45 * Clock monotonic including suspend time or its equivalent on the system, 46 * in the same units and timebase as {@link android.os.SystemClock#elapsedRealtimeNanos}. 47 */ 48 public static final int TIMEBASE_BOOTTIME = 1; 49 50 /** @hide */ 51 @IntDef({ 52 TIMEBASE_MONOTONIC, 53 TIMEBASE_BOOTTIME, 54 }) 55 @Retention(RetentionPolicy.SOURCE) 56 public @interface Timebase {} 57 58 /** 59 * Position in frames relative to start of an assumed audio stream. 60 * <p> 61 * When obtained through 62 * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)}, 63 * all 64 bits of position are valid. 64 * <p> 65 * When obtained through 66 * {@link AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp)}, 67 * the low-order 32 bits of position is in wrapping frame units similar to 68 * {@link AudioTrack#getPlaybackHeadPosition AudioTrack.getPlaybackHeadPosition()}. 69 */ 70 public long framePosition; 71 72 /** 73 * Time associated with the frame in the audio pipeline. 74 * <p> 75 * When obtained through 76 * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)}, 77 * this is the estimated time in nanoseconds when the frame referred to by 78 * {@link #framePosition} was captured. The timebase is either 79 * {@link #TIMEBASE_MONOTONIC} or {@link #TIMEBASE_BOOTTIME}, depending 80 * on the timebase parameter used in 81 * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)}. 82 * <p> 83 * When obtained through 84 * {@link AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp)}, 85 * this is the estimated time when the frame was presented or is committed to be presented, 86 * with a timebase of {@link #TIMEBASE_MONOTONIC}. 87 */ 88 public long nanoTime; 89 } 90
