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 android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.os.Parcel;
22 import android.os.Parcelable;
23 
24 import java.lang.annotation.Retention;
25 import java.lang.annotation.RetentionPolicy;
26 
27 /**
28  * Structure that groups a position in frame units relative to an assumed audio stream,
29  * together with the estimated time when that frame enters or leaves the audio
30  * processing pipeline on that device. This can be used to coordinate events
31  * and interactions with the external environment.
32  * <p>
33  * The time is based on the implementation's best effort, using whatever knowledge
34  * is available to the system, but cannot account for any delay unknown to the implementation.
35  *
36  * @see AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp)
37  * @see AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)
38  */
39 public final class AudioTimestamp implements Parcelable {
40     /**
41      * Clock monotonic or its equivalent on the system,
42      * in the same units and timebase as {@link java.lang.System#nanoTime}.
43      */
44     public static final int TIMEBASE_MONOTONIC = 0;
45 
46     /**
47      * Clock monotonic including suspend time or its equivalent on the system,
48      * in the same units and timebase as {@link android.os.SystemClock#elapsedRealtimeNanos}.
49      */
50     public static final int TIMEBASE_BOOTTIME = 1;
51 
52     /** @hide */
53     @IntDef({
54         TIMEBASE_MONOTONIC,
55         TIMEBASE_BOOTTIME,
56     })
57     @Retention(RetentionPolicy.SOURCE)
58     public @interface Timebase {}
59 
60     /**
61      * Position in frames relative to start of an assumed audio stream.
62      * <p>
63      * When obtained through
64      * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)},
65      * all 64 bits of position are valid.
66      * <p>
67      * When obtained through
68      * {@link AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp)},
69      * the low-order 32 bits of position is in wrapping frame units similar to
70      * {@link AudioTrack#getPlaybackHeadPosition AudioTrack.getPlaybackHeadPosition()}.
71      */
72     public long framePosition;
73 
74     /**
75      * Time associated with the frame in the audio pipeline.
76      * <p>
77      * When obtained through
78      * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)},
79      * this is the estimated time in nanoseconds when the frame referred to by
80      * {@link #framePosition} was captured. The timebase is either
81      * {@link #TIMEBASE_MONOTONIC} or {@link #TIMEBASE_BOOTTIME}, depending
82      * on the timebase parameter used in
83      * {@link AudioRecord#getTimestamp AudioRecord.getTimestamp(AudioTimestamp, int)}.
84      * <p>
85      * When obtained through
86      * {@link AudioTrack#getTimestamp AudioTrack.getTimestamp(AudioTimestamp)},
87      * this is the estimated time when the frame was presented or is committed to be presented,
88      * with a timebase of {@link #TIMEBASE_MONOTONIC}.
89      */
90     public long nanoTime;
91 
AudioTimestamp()92     public AudioTimestamp() {
93     }
94 
AudioTimestamp(@onNull Parcel in)95     private AudioTimestamp(@NonNull Parcel in) {
96         framePosition = in.readLong();
97         nanoTime = in.readLong();
98     }
99 
100     @Override
toString()101     public String toString() {
102         return "AudioTimeStamp:"
103                 + " framePos=" + framePosition
104                 + " nanoTime=" + nanoTime;
105     }
106 
107     @Override
writeToParcel(@onNull Parcel dest, int flags)108     public void writeToParcel(@NonNull Parcel dest, int flags) {
109         dest.writeLong(framePosition);
110         dest.writeLong(nanoTime);
111     }
112 
113     @Override
describeContents()114     public int describeContents() {
115         return 0;
116     }
117 
118     /**
119      * Creates an instance from a {@link Parcel}.
120      */
121     @NonNull
122     public static final Creator<AudioTimestamp> CREATOR = new Creator<>() {
123         @Override
124         public AudioTimestamp createFromParcel(@NonNull Parcel in) {
125             return new AudioTimestamp(in);
126         }
127 
128         @Override
129         public AudioTimestamp[] newArray(int size) {
130             return new AudioTimestamp[size];
131         }
132     };
133 }
134 
135