1 /*
2  * Copyright 2015 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.FloatRange;
20 
21 /**
22  * An immutable object that represents the linear correlation between the media time
23  * and the system time. It contains the media clock rate, together with the media timestamp
24  * of an anchor frame and the system time when that frame was presented or is committed
25  * to be presented.
26  * <p>
27  * The phrase "present" means that audio/video produced on device is detectable by an external
28  * observer off device.
29  * The time is based on the implementation's best effort, using whatever knowledge
30  * is available to the system, but cannot account for any delay unknown to the implementation.
31  * The anchor frame could be any frame, including a just-rendered frame, or even a theoretical
32  * or in-between frame, based on the source of the MediaTimestamp.
33  * When the anchor frame is a just-rendered one, the media time stands for
34  * current position of the playback or recording.
35  *
36  * @see MediaSync#getTimestamp
37  * @see MediaPlayer#getTimestamp
38  */
39 public final class MediaTimestamp
40 {
41     /**
42      * An unknown media timestamp value
43      */
44     public static final MediaTimestamp TIMESTAMP_UNKNOWN = new MediaTimestamp(-1, -1, 0.0f);
45 
46     /**
47      * Get the media time of the anchor in microseconds.
48      */
getAnchorMediaTimeUs()49     public long getAnchorMediaTimeUs() {
50         return mediaTimeUs;
51     }
52 
53     /**
54      * Get the {@link java.lang.System#nanoTime system time} corresponding to the media time
55      * in nanoseconds.
56      * @deprecated use {@link #getAnchorSystemNanoTime} instead.
57      */
58     @Deprecated
getAnchorSytemNanoTime()59     public long getAnchorSytemNanoTime() {
60         return getAnchorSystemNanoTime();
61     }
62 
63     /**
64      * Get the {@link java.lang.System#nanoTime system time} corresponding to the media time
65      * in nanoseconds.
66      */
getAnchorSystemNanoTime()67     public long getAnchorSystemNanoTime() {
68         return nanoTime;
69     }
70 
71     /**
72      * Get the rate of the media clock in relation to the system time.
73      * <p>
74      * It is 1.0 if media clock advances in sync with the system clock;
75      * greater than 1.0 if media clock is faster than the system clock;
76      * less than 1.0 if media clock is slower than the system clock.
77      */
78     @FloatRange(from = 0.0f, to = Float.MAX_VALUE)
getMediaClockRate()79     public float getMediaClockRate() {
80         return clockRate;
81     }
82 
83     /** @hide - accessor shorthand */
84     public final long mediaTimeUs;
85     /** @hide - accessor shorthand */
86     public final long nanoTime;
87     /** @hide - accessor shorthand */
88     public final float clockRate;
89 
90     /**
91      * Constructor.
92      *
93      * @param mediaTimeUs the media time of the anchor in microseconds
94      * @param nanoTimeNs the {@link java.lang.System#nanoTime system time} corresponding to the
95      *                  media time in nanoseconds.
96      * @param clockRate the rate of the media clock in relation to the system time.
97      */
MediaTimestamp(long mediaTimeUs, long nanoTimeNs, @FloatRange(from = 0.0f, to = Float.MAX_VALUE) float clockRate)98     public MediaTimestamp(long mediaTimeUs, long nanoTimeNs,
99             @FloatRange(from = 0.0f, to = Float.MAX_VALUE) float clockRate) {
100         this.mediaTimeUs = mediaTimeUs;
101         this.nanoTime = nanoTimeNs;
102         this.clockRate = clockRate;
103     }
104 
105     /** @hide */
MediaTimestamp()106     MediaTimestamp() {
107         mediaTimeUs = 0;
108         nanoTime = 0;
109         clockRate = 1.0f;
110     }
111 
112     @Override
equals(Object obj)113     public boolean equals(Object obj) {
114         if (this == obj) return true;
115         if (obj == null || getClass() != obj.getClass()) return false;
116 
117         final MediaTimestamp that = (MediaTimestamp) obj;
118         return (this.mediaTimeUs == that.mediaTimeUs)
119                 && (this.nanoTime == that.nanoTime)
120                 && (this.clockRate == that.clockRate);
121     }
122 
123     @Override
toString()124     public String toString() {
125         return getClass().getName()
126                 + "{AnchorMediaTimeUs=" + mediaTimeUs
127                 + " AnchorSystemNanoTime=" + nanoTime
128                 + " clockRate=" + clockRate
129                 + "}";
130     }
131 }
132