From 486918b41584cd2589c46c5217b3fba1e7d18874 Mon Sep 17 00:00:00 2001 From: Glenn Kasten Date: Tue, 20 May 2014 15:48:53 -0700 Subject: Update android.media.AudioTrack.getTimestamp API documentation Change-Id: I0928c73c147ce843ae46565883da209b278fb3b4 --- media/java/android/media/AudioTrack.java | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'media') diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java index 1baaaa4..8eb83e4 100644 --- a/media/java/android/media/AudioTrack.java +++ b/media/java/android/media/AudioTrack.java @@ -791,11 +791,17 @@ public class AudioTrack /** * Poll for a timestamp on demand. - * - * Use if you need to get the most recent timestamp outside of the event callback handler. - * Calling this method too often may be inefficient; - * if you need a high-resolution mapping between frame position and presentation time, + *

+ * If you need to track timestamps during initial warmup or after a routing or mode change, + * you should request a new timestamp once per second until the reported timestamps + * show that the audio clock is stable. + * Thereafter, query for a new timestamp approximately once every 10 seconds to once per minute. + * Calling this method more often is inefficient. + * It is also counter-productive to call this method more often than recommended, + * because the short-term differences between successive timestamp reports are not meaningful. + * If you need a high-resolution mapping between frame position and presentation time, * consider implementing that at application level, based on low-resolution timestamps. + *

* The audio data at the returned position may either already have been * presented, or may have not yet been presented but is committed to be presented. * It is not possible to request the time corresponding to a particular position, @@ -811,6 +817,8 @@ public class AudioTrack * be presented. * In the case that no timestamp is available, any supplied instance is left unaltered. */ + // Add this text when the "on new timestamp" API is added: + // Use if you need to get the most recent timestamp outside of the event callback handler. public boolean getTimestamp(AudioTimestamp timestamp) { if (timestamp == null) { -- cgit v1.1