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