blob: 23a832d09ba7118ddecea78593068c77cafa7e46 [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef COBALT_MEDIA_FILTERS_AUDIO_CLOCK_H_
#define COBALT_MEDIA_FILTERS_AUDIO_CLOCK_H_
#include <cmath>
#include <deque>
#include "base/basictypes.h"
#include "base/time.h"
#include "cobalt/media/base/media_export.h"
#include "starboard/types.h"
namespace cobalt {
namespace media {
// Models a queue of buffered audio in a playback pipeline for use with
// estimating the amount of delay in wall clock time. Takes changes in playback
// rate into account to handle scenarios where multiple rates may be present in
// a playback pipeline with large delay.
//
//
// USAGE
//
// Prior to starting audio playback, construct an AudioClock with an initial
// media timestamp and a sample rate matching the sample rate the audio device
// was opened at.
//
// Each time the audio rendering callback is executed, call WroteAudio() once
// (and only once!) containing information on what was written:
// 1) How many frames of audio data requested
// 2) How many frames of audio data provided
// 3) The playback rate of the audio data provided
// 4) The current amount of delay
//
// After a call to WroteAudio(), clients can inspect the resulting media
// timestamp. This can be used for UI purposes, synchronizing video, etc...
//
//
// DETAILS
//
// Silence (whether caused by the initial audio delay or failing to write the
// amount of requested frames due to underflow) is also modeled and will cause
// the media timestamp to stop increasing until all known silence has been
// played. AudioClock's model is initialized with silence during the first call
// to WroteAudio() using the delay value.
//
// Playback rates are tracked for translating frame durations into media
// durations. Since silence doesn't affect media timestamps, it also isn't
// affected by playback rates.
class MEDIA_EXPORT AudioClock {
public:
AudioClock(base::TimeDelta start_timestamp, int sample_rate);
~AudioClock();
// |frames_written| amount of audio data scaled to |playback_rate| written.
// |frames_requested| amount of audio data requested by hardware.
// |delay_frames| is the current amount of hardware delay.
void WroteAudio(int frames_written, int frames_requested, int delay_frames,
double playback_rate);
// If WroteAudio() calls are suspended (i.e. due to playback being paused) the
// AudioClock will not properly advance time (even though all data up until
// back_timestamp() will playout on the physical device).
//
// To compensate for this, when calls resume, before the next WroteAudio(),
// callers should call CompensateForSuspendedWrites() to advance the clock for
// audio which continued playing out while WroteAudio() calls were suspended.
//
// |delay_frames| must be provided to properly prime the clock to compensate
// for a new initial delay.
void CompensateForSuspendedWrites(base::TimeDelta elapsed, int delay_frames);
// Returns the bounds of media data currently buffered by the audio hardware,
// taking silence and changes in playback rate into account. Buffered audio
// structure and timestamps are updated with every call to WroteAudio().
//
// start_timestamp = 1000 ms sample_rate = 40 Hz
// +-----------------------+-----------------------+-----------------------+
// | 10 frames silence | 20 frames @ 1.0x | 20 frames @ 0.5x |
// | = 250 ms (wall) | = 500 ms (wall) | = 500 ms (wall) |
// | = 0 ms (media) | = 500 ms (media) | = 250 ms (media) |
// +-----------------------+-----------------------+-----------------------+
// ^ ^
// front_timestamp() is equal to back_timestamp() is equal to
// |start_timestamp| since no amount of media frames tracked
// media data has been played yet. by AudioClock, which would be
// 1000 + 500 + 250 = 1750 ms.
base::TimeDelta front_timestamp() const {
return base::TimeDelta::FromMicroseconds(
std::round(front_timestamp_micros_));
}
base::TimeDelta back_timestamp() const {
return base::TimeDelta::FromMicroseconds(
std::round(back_timestamp_micros_));
}
// Returns the amount of wall time until |timestamp| will be played by the
// audio hardware.
//
// |timestamp| must be within front_timestamp() and back_timestamp().
base::TimeDelta TimeUntilPlayback(base::TimeDelta timestamp) const;
void ContiguousAudioDataBufferedForTesting(
base::TimeDelta* total, base::TimeDelta* same_rate_total) const;
private:
// Even with a ridiculously high sample rate of 256kHz, using 64 bits will
// permit tracking up to 416999965 days worth of time (that's 1141 millenia).
//
// 32 bits on the other hand would top out at measly 2 hours and 20 minutes.
struct AudioData {
AudioData(int64_t frames, double playback_rate);
int64_t frames;
double playback_rate;
};
// Helpers for operating on |buffered_|.
void PushBufferedAudioData(int64_t frames, double playback_rate);
void PopBufferedAudioData(int64_t frames);
double ComputeBufferedMediaDurationMicros() const;
const base::TimeDelta start_timestamp_;
const double microseconds_per_frame_;
std::deque<AudioData> buffered_;
int64_t total_buffered_frames_;
// Use double rather than TimeDelta to avoid loss of partial microseconds when
// converting between frames-written/delayed and time-passed (see conversion
// in WroteAudio()). Particularly for |back_timestamp|, which accumulates more
// time with each call to WroteAudio(), the loss of precision can accumulate
// to create noticeable audio/video sync drift for longer (2-3 hr) videos.
// See http://crbug.com/564604.
double front_timestamp_micros_;
double back_timestamp_micros_;
DISALLOW_COPY_AND_ASSIGN(AudioClock);
};
} // namespace media
} // namespace cobalt
#endif // COBALT_MEDIA_FILTERS_AUDIO_CLOCK_H_