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