media/libstagefright/include/media/stagefright/VideoRenderQualityTracker.h - platform/frameworks/av - Git at Google

 /*
  * Copyright 2023, The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef VIDEO_RENDER_QUALITY_TRACKER_H_

 #define VIDEO_RENDER_QUALITY_TRACKER_H_

 #include <assert.h>
 #include <list>
 #include <queue>

 #include <media/stagefright/MediaHistogram.h>

 namespace android {

 // A variety of video rendering quality metrics.
 struct VideoRenderQualityMetrics {
     static constexpr float FRAME_RATE_UNDETERMINED = -1.0f;
     static constexpr float FRAME_RATE_24_3_2_PULLDOWN = -2.0f;

     VideoRenderQualityMetrics();

     void clear();

     // The render time of the first video frame.
     int64_t firstRenderTimeUs;

     // The render time of the last video frame.
     int64_t lastRenderTimeUs;

     // The number of frames released to be rendered.
     int64_t frameReleasedCount;

     // The number of frames actually rendered.
     int64_t frameRenderedCount;

     // The number of frames dropped - frames that were released but never rendered.
     int64_t frameDroppedCount;

     // The number of frames that were intentionally dropped/skipped by the app.
     int64_t frameSkippedCount;

     // The frame rate as detected by looking at the position timestamp from the content stream.
     float contentFrameRate;

     // The frame rate as detected by looking at the desired render time passed in by the app.
     float desiredFrameRate;

     // The frame rate as detected by looking at the actual render time, as returned by the system
     // post-render.
     float actualFrameRate;

     // The amount of content duration skipped by the app after a pause when video was trying to
     // resume. This sometimes happen when catching up to the audio position which continued playing
     // after video pauses.
     int32_t maxContentDroppedAfterPauseMs;

     // A histogram of the durations of freezes due to dropped/skipped frames.
     MediaHistogram<int32_t> freezeDurationMsHistogram;
     // The computed overall freeze score using the above histogram and score conversion table. The
     // score is based on counts in the histogram bucket, multiplied by the value in the score
     // conversion table for that bucket. For example, the impact of a short freeze may be minimal,
     // but the impact of long freeze may be disproportionally worse. Therefore, the score
     // multipliers for each bucket might increase exponentially instead of linearly. A score
     // multiplier of zero would reflect that small freeze durations have near-zero impact to the
     // user experience.
     int32_t freezeScore;
     // The computed percentage of total playback duration that was frozen.
     float freezeRate;
     // The number of freeze events.
     int32_t freezeEventCount;

     // A histogram of the durations between each freeze.
     MediaHistogram<int32_t> freezeDistanceMsHistogram;

     // A histogram of the judder scores - based on the error tolerance between actual render
     // duration of each frame and the ideal render duration.
     MediaHistogram<int32_t> judderScoreHistogram;
     // The computed overall judder score using the above histogram and score conversion table. The
     // score is based on counts in the histogram bucket, multiplied by the value in the score
     // conversion table for that bucket. For example, the impact of minimal judder may be small,
     // but the impact of large judder may be disproportionally worse. Therefore, the score
     // multipliers for each bucket might increase exponentially instead of linearly. A score
     // multiplier of zero would reflect that small judder errors have near-zero impact to the user
     // experience.
     int32_t judderScore;
     // The computed percentage of total frames that had judder.
     float judderRate;
     // The number of judder events.
     int32_t judderEventCount;
 };

 ///////////////////////////////////////////////////////
 // This class analyzes various timestamps related to video rendering to compute a set of metrics
 // that attempt to capture the quality of the user experience during video playback.
 //
 // The following timestamps (in microseconds) are analyzed to compute these metrics:
 //   * The content timestamp found in the content stream, indicating the position of each video
 //     frame.
 //   * The desired timestamp passed in by the app, indicating at what point in time in the future
 //     the app would like the frame to be rendered.
 //   * The actual timestamp passed in by the display subsystem, indicating the point in time at
 //     which the frame was actually rendered.
 //
 // Core to the algorithms are deriving frame durations based on these timestamps and determining
 // the result of each video frame in the content stream:
 //   * skipped: the app didn't want to render the frame
 //   * dropped: the display subsystem could not render the frame in time
 //   * rendered: the display subsystem rendered the frame
 //
 class VideoRenderQualityTracker {
 public:
     // Configurable elements of the metrics algorithms
     class Configuration {
     public:
         // system/server_configurable_flags/libflags/include/get_flags.h:GetServerConfigurableFlag
         typedef std::string (*GetServerConfigurableFlagFn)(
                 const std::string& experiment_category_name,
                 const std::string& experiment_flag_name,
                 const std::string& default_value);

         static Configuration getFromServerConfigurableFlags(
                 GetServerConfigurableFlagFn getServerConfigurableFlagFn);

         Configuration();

         // Whether or not frame render quality is tracked.
         bool enabled;

         // Whether or not frames that are intentionally not rendered by the app should be considered
         // as dropped.
         bool areSkippedFramesDropped;

         // How large of a jump forward in content time is allowed before it is considered a
         // discontinuity (seek/playlist) and various internal states are reset.
         int32_t maxExpectedContentFrameDurationUs;

         // How much tolerance in frame duration when considering whether or not two frames have the
         // same frame rate.
         int32_t frameRateDetectionToleranceUs;

         // A skip forward in content time could occur during frame drops of live content. Therefore
         // the content frame duration and the app-desired frame duration are compared using this
         // tolerance to determine whether the app is intentionally seeking forward or whether the
         // skip forward in content time is due to frame drops. If the app-desired frame duration is
         // short, but the content frame duration is large, it is assumed the app is intentionally
         // seeking forward.
         int32_t liveContentFrameDropToleranceUs;

         // The amount of time it takes for audio to stop playback after a pause is initiated. Used
         // for providing some allowance of dropped video frames to catch back up to the audio
         // position when resuming playback.
         int32_t pauseAudioLatencyUs;

         // Freeze configuration
         //
         // The values used to distribute freeze durations across a histogram.
         std::vector<int32_t> freezeDurationMsHistogramBuckets;
         //
         // The values used to multiply the counts in the histogram buckets above to compute an
         // overall score. This allows the score to reflect disproportionate impact as freeze
         // durations increase.
         std::vector<int64_t> freezeDurationMsHistogramToScore;
         //
         // The values used to distribute distances between freezes across a histogram.
         std::vector<int32_t> freezeDistanceMsHistogramBuckets;
         //
         // The maximum number of freeze events to send back to the caller.
         int32_t freezeEventMax;
         //
         // The maximum number of detail entries tracked per freeze event.
         int32_t freezeEventDetailsMax;
         //
         // The maximum distance in time between two freeze occurrences such that both will be
         // lumped into the same freeze event.
         int32_t freezeEventDistanceToleranceMs;

         // Judder configuration
         //
         // A judder error lower than this value is not scored as judder.
         int32_t judderErrorToleranceUs;
         //
         // The values used to distribute judder scores across a histogram.
         std::vector<int32_t> judderScoreHistogramBuckets;
         //
         // The values used to multiply the counts in the histogram buckets above to compute an
         // overall score. This allows the score to reflect disproportionate impact as judder scores
         // increase.
         std::vector<int64_t> judderScoreHistogramToScore;
         //
         // The maximum number of judder events to send back to the caller.
         int32_t judderEventMax;
         //
         // The maximum number of detail entries tracked per judder event.
         int32_t judderEventDetailsMax;
         //
         // The maximum distance in time between two judder occurrences such that both will be
         // lumped into the same judder event.
         int32_t judderEventDistanceToleranceMs;
         //
         // Whether or not Perfetto trace trigger is enabled.
         bool traceTriggerEnabled;
         //
         // The throttle time for Perfetto trace trigger to avoid triggering multiple traces for
         // the same event in a short time.
         int32_t traceTriggerThrottleMs;
         //
         // The minimum frame render duration to recognize video freeze event to collect trace.
         int32_t traceMinFreezeDurationMs;
     };

     struct FreezeEvent {
         // Details are captured for each freeze up to a limited number. The arrays are guaranteed to
         // have the same size.
         struct Details {
             /// The duration of the freeze.
             std::vector<int32_t> durationMs;
             // The distance between the beginning of this freeze and the end of the previous freeze.
             std::vector<int32_t> distanceMs;
         };
         // Whether or not the data in this structure is valid.
         bool valid = false;
         // The time at which the first freeze for this event was detected.
         int64_t initialTimeUs;
         // The total duration from the beginning of the first freeze to the end of the last freeze
         // in this event.
         int32_t durationMs;
         // The number of freezes in this event.
         int64_t count;
         // The sum of all durations of all freezes in this event.
         int64_t sumDurationMs;
         // The sum of all distances between each freeze in this event.
         int64_t sumDistanceMs;
         // Detailed information for the first N freezes in this event.
         Details details;
     };

     struct JudderEvent {
         // Details are captured for each frame judder up to a limited number. The arrays are
         // guaranteed to have the same size.
         struct Details {
             // The actual render duration of the frame for this judder occurrence.
             std::vector<int32_t> actualRenderDurationUs;
             // The content render duration of the frame for this judder occurrence.
             std::vector<int32_t> contentRenderDurationUs;
             // The distance from this judder occurrence and the previous judder occurrence.
             std::vector<int32_t> distanceMs;
         };
         // Whether or not the data in this structure is valid.
         bool valid = false;
         // The time at which the first judder occurrence for this event was detected.
         int64_t initialTimeUs;
         // The total duration from the first judder occurrence to the last judder occurrence in this
         // event.
         int32_t durationMs;
         // The number of judder occurrences in this event.
         int64_t count;
         // The sum of all judder scores in this event.
         int64_t sumScore;
         // The sum of all distances between each judder occurrence in this event.
         int64_t sumDistanceMs;
         // Detailed information for the first N judder occurrences in this event.
         Details details;
     };

     typedef void (*TraceTriggerFn)();

     VideoRenderQualityTracker();
     VideoRenderQualityTracker(const Configuration &configuration,
                               const TraceTriggerFn traceTriggerFn = nullptr);

     // Called when a tunnel mode frame has been queued.
     void onTunnelFrameQueued(int64_t contentTimeUs);

     // Called when the app has intentionally decided not to render this frame.
     void onFrameSkipped(int64_t contentTimeUs);

     // Called when the app has requested the frame to be rendered as soon as possible.
     void onFrameReleased(int64_t contentTimeUs);

     // Called when the app has requested the frame to be rendered at a specific point in time in the
     // future.
     void onFrameReleased(int64_t contentTimeUs, int64_t desiredRenderTimeNs);

     // Called when the system has detected that the frame has actually been rendered to the display.
     // Returns any freeze events or judder events that were detected.
     void onFrameRendered(int64_t contentTimeUs, int64_t actualRenderTimeNs,
                          FreezeEvent *freezeEventOut = nullptr,
                          JudderEvent *judderEventOut = nullptr);

     // Gets and resets data for the current freeze event.
     FreezeEvent getAndResetFreezeEvent();

     // Gets and resets data for the current judder event.
     JudderEvent getAndResetJudderEvent();

     // Retrieve the metrics.
     const VideoRenderQualityMetrics &getMetrics();

     // Called when a change in codec state will result in a content discontinuity - e.g. flush.
     void resetForDiscontinuity();

     // Clear out all metrics and tracking - e.g. codec reconfigured.
     void clear();

 private:
     // Tracking of frames that are pending to be rendered to the display.
     struct FrameInfo {
         int64_t contentTimeUs;
         int64_t desiredRenderTimeUs;
     };

     // Historic tracking of frame durations
     struct FrameDurationUs {
         static const int SIZE = 5;

         FrameDurationUs() {
             for (int i = 0; i < SIZE; ++i) {
                 durationUs[i] = -1;
             }
             priorTimestampUs = -1;
         }

         int32_t &operator[](int index) {
             assert(index < SIZE);
             return durationUs[index];
         }

         const int32_t &operator[](int index) const {
             assert(index < SIZE);
             return durationUs[index];
         }

         // The duration of the past N frames.
         int32_t durationUs[SIZE];

         // The timestamp of the previous frame.
         int64_t priorTimestampUs;
     };

     // Configure histograms for the metrics.
     static void configureHistograms(VideoRenderQualityMetrics &m, const Configuration &c);

     // The current time in microseconds.
     static int64_t nowUs();

     // A new frame has been processed, so update the frame durations based on the new frame
     // timestamp.
     static void updateFrameDurations(FrameDurationUs &durationUs, int64_t newTimestampUs);

     // Update a frame rate if, and only if, one can be detected.
     static void updateFrameRate(float &frameRate, const FrameDurationUs &durationUs,
                                 const Configuration &c);

     // Examine the past few frames to detect the frame rate based on each frame's render duration.
     static float detectFrameRate(const FrameDurationUs &durationUs, const Configuration &c);

     // Determine whether or not 3:2 pulldowng for displaying 24fps content on 60Hz displays is
     // occurring.
     static bool is32pulldown(const FrameDurationUs &durationUs, const Configuration &c);

     // Process a frame freeze.
     static void processFreeze(int64_t actualRenderTimeUs, int64_t lastRenderTimeUs,
                               int64_t lastFreezeEndTimeUs, FreezeEvent &e,
                               VideoRenderQualityMetrics &m, const Configuration &c,
                               const TraceTriggerFn traceTriggerFn);

     // Retrieve a freeze event if an event just finished.
     static void maybeCaptureFreezeEvent(int64_t actualRenderTimeUs, int64_t lastFreezeEndTimeUs,
                                         FreezeEvent &e, const VideoRenderQualityMetrics & m,
                                         const Configuration &c, FreezeEvent *freezeEventOut);

     // Compute a judder score for the previously-rendered frame.
     static int64_t computePreviousJudderScore(const FrameDurationUs &actualRenderDurationUs,
                                               const FrameDurationUs &contentRenderDurationUs,
                                               const Configuration &c);

     // Process a frame judder.
     static void processJudder(int32_t judderScore, int64_t judderTimeUs,
                               int64_t lastJudderEndTimeUs,
                               const FrameDurationUs &contentDurationUs,
                               const FrameDurationUs &actualDurationUs, JudderEvent &e,
                               VideoRenderQualityMetrics &m, const Configuration &c);

     // Retrieve a judder event if an event just finished.
     static void maybeCaptureJudderEvent(int64_t actualRenderTimeUs, int64_t lastJudderEndTimeUs,
                                         JudderEvent &e, const VideoRenderQualityMetrics & m,
                                         const Configuration &c, JudderEvent *judderEventOut);

     // Trigger trace collection for video freeze.
     static void triggerTrace();

     // Trigger collection of a Perfetto Always-On-Tracing (AOT) trace file for video freeze,
     // triggerTimeUs is used as a throttle to avoid triggering multiple traces in a short time.
     static void triggerTraceWithThrottle(TraceTriggerFn traceTriggerFn,
                                          const Configuration &c, const int64_t triggerTimeUs);

     // Check to see if a discontinuity has occurred by examining the content time and the
     // app-desired render time. If so, reset some internal state.
     bool resetIfDiscontinuity(int64_t contentTimeUs, int64_t desiredRenderTimeUs);

     // Update the metrics because a skipped frame was detected.
     void processMetricsForSkippedFrame(int64_t contentTimeUs);

     // Update the metrics because a dropped frame was detected.
     void processMetricsForDroppedFrame(int64_t contentTimeUs, int64_t desiredRenderTimeUs);

     // Update the metrics because a rendered frame was detected.
     void processMetricsForRenderedFrame(int64_t contentTimeUs, int64_t desiredRenderTimeUs,
                                         int64_t actualRenderTimeUs,
                                         FreezeEvent *freezeEventOut, JudderEvent *judderEventOut);

     // Configurable elements of the metrics algorithms.
     const Configuration mConfiguration;

     // The function for triggering trace collection for video freeze.
     const TraceTriggerFn mTraceTriggerFn;

     // Metrics are updated every time a frame event occurs - skipped, dropped, rendered.
     VideoRenderQualityMetrics mMetrics;

     // The most recently processed timestamp referring to the position in the content stream.
     int64_t mLastContentTimeUs;

     // The most recently processed timestamp referring to the wall clock time a frame was rendered.
     int64_t mLastRenderTimeUs;

     // The most recent timestamp of the first frame rendered after the freeze.
     int64_t mLastFreezeEndTimeUs;

     // The most recent timestamp of frame judder.
     int64_t mLastJudderEndTimeUs;

     // The render duration of the playback.
     int64_t mRenderDurationMs;

     // The duration of the content that was dropped.
     int64_t mDroppedContentDurationUs;

     // The freeze event that's currently being tracked.
     FreezeEvent mFreezeEvent;

     // The judder event that's currently being tracked.
     JudderEvent mJudderEvent;

     // Frames skipped at the end of playback shouldn't really be considered skipped, therefore keep
     // a list of the frames, and process them as skipped frames the next time a frame is rendered.
     std::list<int64_t> mPendingSkippedFrameContentTimeUsList;

     // Since the system only signals when a frame is rendered, dropped frames are detected by
     // checking to see if the next expected frame is rendered. If not, it is considered dropped.
     std::queue<FrameInfo> mNextExpectedRenderedFrameQueue;

     // When B-frames are present in the stream, a P-frame will be queued before the B-frame even
     // though it is rendered after. Therefore, the P-frame is held here and not inserted into
     // mNextExpectedRenderedFrameQueue until it should be inserted to maintain render order.
     int64_t mTunnelFrameQueuedContentTimeUs;

     // Frame durations derived from timestamps encoded into the content stream. These are the
     // durations that each frame is supposed to be rendered for.
     FrameDurationUs mContentFrameDurationUs;

     // Frame durations derived from timestamps passed in by the app, indicating the wall clock time
     // at which the app would like to have the frame rendered.
     FrameDurationUs mDesiredFrameDurationUs;

     // Frame durations derived from timestamps captured by the display subsystem, indicating the
     // wall clock atime at which the frame is actually rendered.
     FrameDurationUs mActualFrameDurationUs;

     // Token of async atrace for video frame dropped/skipped by the app.
     int64_t mTraceFrameSkippedToken= -1;
 };

 }  // namespace android

 #endif  // VIDEO_RENDER_QUALITY_TRACKER_H_
	/*
	* Copyright 2023, The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef VIDEO_RENDER_QUALITY_TRACKER_H_

	#define VIDEO_RENDER_QUALITY_TRACKER_H_

	#include <assert.h>
	#include <list>
	#include <queue>

	#include <media/stagefright/MediaHistogram.h>

	namespace android {

	// A variety of video rendering quality metrics.
	struct VideoRenderQualityMetrics {
	static constexpr float FRAME_RATE_UNDETERMINED = -1.0f;
	static constexpr float FRAME_RATE_24_3_2_PULLDOWN = -2.0f;

	VideoRenderQualityMetrics();

	void clear();

	// The render time of the first video frame.
	int64_t firstRenderTimeUs;

	// The render time of the last video frame.
	int64_t lastRenderTimeUs;

	// The number of frames released to be rendered.
	int64_t frameReleasedCount;

	// The number of frames actually rendered.
	int64_t frameRenderedCount;

	// The number of frames dropped - frames that were released but never rendered.
	int64_t frameDroppedCount;

	// The number of frames that were intentionally dropped/skipped by the app.
	int64_t frameSkippedCount;

	// The frame rate as detected by looking at the position timestamp from the content stream.
	float contentFrameRate;

	// The frame rate as detected by looking at the desired render time passed in by the app.
	float desiredFrameRate;

	// The frame rate as detected by looking at the actual render time, as returned by the system
	// post-render.
	float actualFrameRate;

	// The amount of content duration skipped by the app after a pause when video was trying to
	// resume. This sometimes happen when catching up to the audio position which continued playing
	// after video pauses.
	int32_t maxContentDroppedAfterPauseMs;

	// A histogram of the durations of freezes due to dropped/skipped frames.
	MediaHistogram<int32_t> freezeDurationMsHistogram;
	// The computed overall freeze score using the above histogram and score conversion table. The
	// score is based on counts in the histogram bucket, multiplied by the value in the score
	// conversion table for that bucket. For example, the impact of a short freeze may be minimal,
	// but the impact of long freeze may be disproportionally worse. Therefore, the score
	// multipliers for each bucket might increase exponentially instead of linearly. A score
	// multiplier of zero would reflect that small freeze durations have near-zero impact to the
	// user experience.
	int32_t freezeScore;
	// The computed percentage of total playback duration that was frozen.
	float freezeRate;
	// The number of freeze events.
	int32_t freezeEventCount;

	// A histogram of the durations between each freeze.
	MediaHistogram<int32_t> freezeDistanceMsHistogram;

	// A histogram of the judder scores - based on the error tolerance between actual render
	// duration of each frame and the ideal render duration.
	MediaHistogram<int32_t> judderScoreHistogram;
	// The computed overall judder score using the above histogram and score conversion table. The
	// score is based on counts in the histogram bucket, multiplied by the value in the score
	// conversion table for that bucket. For example, the impact of minimal judder may be small,
	// but the impact of large judder may be disproportionally worse. Therefore, the score
	// multipliers for each bucket might increase exponentially instead of linearly. A score
	// multiplier of zero would reflect that small judder errors have near-zero impact to the user
	// experience.
	int32_t judderScore;
	// The computed percentage of total frames that had judder.
	float judderRate;
	// The number of judder events.
	int32_t judderEventCount;
	};

	///////////////////////////////////////////////////////
	// This class analyzes various timestamps related to video rendering to compute a set of metrics
	// that attempt to capture the quality of the user experience during video playback.
	//
	// The following timestamps (in microseconds) are analyzed to compute these metrics:
	// * The content timestamp found in the content stream, indicating the position of each video
	// frame.
	// * The desired timestamp passed in by the app, indicating at what point in time in the future
	// the app would like the frame to be rendered.
	// * The actual timestamp passed in by the display subsystem, indicating the point in time at
	// which the frame was actually rendered.
	//
	// Core to the algorithms are deriving frame durations based on these timestamps and determining
	// the result of each video frame in the content stream:
	// * skipped: the app didn't want to render the frame
	// * dropped: the display subsystem could not render the frame in time
	// * rendered: the display subsystem rendered the frame
	//
	class VideoRenderQualityTracker {
	public:
	// Configurable elements of the metrics algorithms
	class Configuration {
	public:
	// system/server_configurable_flags/libflags/include/get_flags.h:GetServerConfigurableFlag
	typedef std::string (*GetServerConfigurableFlagFn)(
	const std::string& experiment_category_name,
	const std::string& experiment_flag_name,
	const std::string& default_value);

	static Configuration getFromServerConfigurableFlags(
	GetServerConfigurableFlagFn getServerConfigurableFlagFn);

	Configuration();

	// Whether or not frame render quality is tracked.
	bool enabled;

	// Whether or not frames that are intentionally not rendered by the app should be considered
	// as dropped.
	bool areSkippedFramesDropped;

	// How large of a jump forward in content time is allowed before it is considered a
	// discontinuity (seek/playlist) and various internal states are reset.
	int32_t maxExpectedContentFrameDurationUs;

	// How much tolerance in frame duration when considering whether or not two frames have the
	// same frame rate.
	int32_t frameRateDetectionToleranceUs;

	// A skip forward in content time could occur during frame drops of live content. Therefore
	// the content frame duration and the app-desired frame duration are compared using this
	// tolerance to determine whether the app is intentionally seeking forward or whether the
	// skip forward in content time is due to frame drops. If the app-desired frame duration is
	// short, but the content frame duration is large, it is assumed the app is intentionally
	// seeking forward.
	int32_t liveContentFrameDropToleranceUs;

	// The amount of time it takes for audio to stop playback after a pause is initiated. Used
	// for providing some allowance of dropped video frames to catch back up to the audio
	// position when resuming playback.
	int32_t pauseAudioLatencyUs;

	// Freeze configuration
	//
	// The values used to distribute freeze durations across a histogram.
	std::vector<int32_t> freezeDurationMsHistogramBuckets;
	//
	// The values used to multiply the counts in the histogram buckets above to compute an
	// overall score. This allows the score to reflect disproportionate impact as freeze
	// durations increase.
	std::vector<int64_t> freezeDurationMsHistogramToScore;
	//
	// The values used to distribute distances between freezes across a histogram.
	std::vector<int32_t> freezeDistanceMsHistogramBuckets;
	//
	// The maximum number of freeze events to send back to the caller.
	int32_t freezeEventMax;
	//
	// The maximum number of detail entries tracked per freeze event.
	int32_t freezeEventDetailsMax;
	//
	// The maximum distance in time between two freeze occurrences such that both will be
	// lumped into the same freeze event.
	int32_t freezeEventDistanceToleranceMs;

	// Judder configuration
	//
	// A judder error lower than this value is not scored as judder.
	int32_t judderErrorToleranceUs;
	//
	// The values used to distribute judder scores across a histogram.
	std::vector<int32_t> judderScoreHistogramBuckets;
	//
	// The values used to multiply the counts in the histogram buckets above to compute an
	// overall score. This allows the score to reflect disproportionate impact as judder scores
	// increase.
	std::vector<int64_t> judderScoreHistogramToScore;
	//
	// The maximum number of judder events to send back to the caller.
	int32_t judderEventMax;
	//
	// The maximum number of detail entries tracked per judder event.
	int32_t judderEventDetailsMax;
	//
	// The maximum distance in time between two judder occurrences such that both will be
	// lumped into the same judder event.
	int32_t judderEventDistanceToleranceMs;
	//
	// Whether or not Perfetto trace trigger is enabled.
	bool traceTriggerEnabled;
	//
	// The throttle time for Perfetto trace trigger to avoid triggering multiple traces for
	// the same event in a short time.
	int32_t traceTriggerThrottleMs;
	//
	// The minimum frame render duration to recognize video freeze event to collect trace.
	int32_t traceMinFreezeDurationMs;
	};

	struct FreezeEvent {
	// Details are captured for each freeze up to a limited number. The arrays are guaranteed to
	// have the same size.
	struct Details {
	/// The duration of the freeze.
	std::vector<int32_t> durationMs;
	// The distance between the beginning of this freeze and the end of the previous freeze.
	std::vector<int32_t> distanceMs;
	};
	// Whether or not the data in this structure is valid.
	bool valid = false;
	// The time at which the first freeze for this event was detected.
	int64_t initialTimeUs;
	// The total duration from the beginning of the first freeze to the end of the last freeze
	// in this event.
	int32_t durationMs;
	// The number of freezes in this event.
	int64_t count;
	// The sum of all durations of all freezes in this event.
	int64_t sumDurationMs;
	// The sum of all distances between each freeze in this event.
	int64_t sumDistanceMs;
	// Detailed information for the first N freezes in this event.
	Details details;
	};

	struct JudderEvent {
	// Details are captured for each frame judder up to a limited number. The arrays are
	// guaranteed to have the same size.
	struct Details {
	// The actual render duration of the frame for this judder occurrence.
	std::vector<int32_t> actualRenderDurationUs;
	// The content render duration of the frame for this judder occurrence.
	std::vector<int32_t> contentRenderDurationUs;
	// The distance from this judder occurrence and the previous judder occurrence.
	std::vector<int32_t> distanceMs;
	};
	// Whether or not the data in this structure is valid.
	bool valid = false;
	// The time at which the first judder occurrence for this event was detected.
	int64_t initialTimeUs;
	// The total duration from the first judder occurrence to the last judder occurrence in this
	// event.
	int32_t durationMs;
	// The number of judder occurrences in this event.
	int64_t count;
	// The sum of all judder scores in this event.
	int64_t sumScore;
	// The sum of all distances between each judder occurrence in this event.
	int64_t sumDistanceMs;
	// Detailed information for the first N judder occurrences in this event.
	Details details;
	};

	typedef void (*TraceTriggerFn)();

	VideoRenderQualityTracker();
	VideoRenderQualityTracker(const Configuration &configuration,
	const TraceTriggerFn traceTriggerFn = nullptr);

	// Called when a tunnel mode frame has been queued.
	void onTunnelFrameQueued(int64_t contentTimeUs);

	// Called when the app has intentionally decided not to render this frame.
	void onFrameSkipped(int64_t contentTimeUs);

	// Called when the app has requested the frame to be rendered as soon as possible.
	void onFrameReleased(int64_t contentTimeUs);

	// Called when the app has requested the frame to be rendered at a specific point in time in the
	// future.
	void onFrameReleased(int64_t contentTimeUs, int64_t desiredRenderTimeNs);

	// Called when the system has detected that the frame has actually been rendered to the display.
	// Returns any freeze events or judder events that were detected.
	void onFrameRendered(int64_t contentTimeUs, int64_t actualRenderTimeNs,
	FreezeEvent *freezeEventOut = nullptr,
	JudderEvent *judderEventOut = nullptr);

	// Gets and resets data for the current freeze event.
	FreezeEvent getAndResetFreezeEvent();

	// Gets and resets data for the current judder event.
	JudderEvent getAndResetJudderEvent();

	// Retrieve the metrics.
	const VideoRenderQualityMetrics &getMetrics();

	// Called when a change in codec state will result in a content discontinuity - e.g. flush.
	void resetForDiscontinuity();

	// Clear out all metrics and tracking - e.g. codec reconfigured.
	void clear();

	private:
	// Tracking of frames that are pending to be rendered to the display.
	struct FrameInfo {
	int64_t contentTimeUs;
	int64_t desiredRenderTimeUs;
	};

	// Historic tracking of frame durations
	struct FrameDurationUs {
	static const int SIZE = 5;

	FrameDurationUs() {
	for (int i = 0; i < SIZE; ++i) {
	durationUs[i] = -1;
	}
	priorTimestampUs = -1;
	}

	int32_t &operator[](int index) {
	assert(index < SIZE);
	return durationUs[index];
	}

	const int32_t &operator[](int index) const {
	assert(index < SIZE);
	return durationUs[index];
	}

	// The duration of the past N frames.
	int32_t durationUs[SIZE];

	// The timestamp of the previous frame.
	int64_t priorTimestampUs;
	};

	// Configure histograms for the metrics.
	static void configureHistograms(VideoRenderQualityMetrics &m, const Configuration &c);

	// The current time in microseconds.
	static int64_t nowUs();

	// A new frame has been processed, so update the frame durations based on the new frame
	// timestamp.
	static void updateFrameDurations(FrameDurationUs &durationUs, int64_t newTimestampUs);

	// Update a frame rate if, and only if, one can be detected.
	static void updateFrameRate(float &frameRate, const FrameDurationUs &durationUs,
	const Configuration &c);

	// Examine the past few frames to detect the frame rate based on each frame's render duration.
	static float detectFrameRate(const FrameDurationUs &durationUs, const Configuration &c);

	// Determine whether or not 3:2 pulldowng for displaying 24fps content on 60Hz displays is
	// occurring.
	static bool is32pulldown(const FrameDurationUs &durationUs, const Configuration &c);

	// Process a frame freeze.
	static void processFreeze(int64_t actualRenderTimeUs, int64_t lastRenderTimeUs,
	int64_t lastFreezeEndTimeUs, FreezeEvent &e,
	VideoRenderQualityMetrics &m, const Configuration &c,
	const TraceTriggerFn traceTriggerFn);

	// Retrieve a freeze event if an event just finished.
	static void maybeCaptureFreezeEvent(int64_t actualRenderTimeUs, int64_t lastFreezeEndTimeUs,
	FreezeEvent &e, const VideoRenderQualityMetrics & m,
	const Configuration &c, FreezeEvent *freezeEventOut);

	// Compute a judder score for the previously-rendered frame.
	static int64_t computePreviousJudderScore(const FrameDurationUs &actualRenderDurationUs,
	const FrameDurationUs &contentRenderDurationUs,
	const Configuration &c);

	// Process a frame judder.
	static void processJudder(int32_t judderScore, int64_t judderTimeUs,
	int64_t lastJudderEndTimeUs,
	const FrameDurationUs &contentDurationUs,
	const FrameDurationUs &actualDurationUs, JudderEvent &e,
	VideoRenderQualityMetrics &m, const Configuration &c);

	// Retrieve a judder event if an event just finished.
	static void maybeCaptureJudderEvent(int64_t actualRenderTimeUs, int64_t lastJudderEndTimeUs,
	JudderEvent &e, const VideoRenderQualityMetrics & m,
	const Configuration &c, JudderEvent *judderEventOut);

	// Trigger trace collection for video freeze.
	static void triggerTrace();

	// Trigger collection of a Perfetto Always-On-Tracing (AOT) trace file for video freeze,
	// triggerTimeUs is used as a throttle to avoid triggering multiple traces in a short time.
	static void triggerTraceWithThrottle(TraceTriggerFn traceTriggerFn,
	const Configuration &c, const int64_t triggerTimeUs);

	// Check to see if a discontinuity has occurred by examining the content time and the
	// app-desired render time. If so, reset some internal state.
	bool resetIfDiscontinuity(int64_t contentTimeUs, int64_t desiredRenderTimeUs);

	// Update the metrics because a skipped frame was detected.
	void processMetricsForSkippedFrame(int64_t contentTimeUs);

	// Update the metrics because a dropped frame was detected.
	void processMetricsForDroppedFrame(int64_t contentTimeUs, int64_t desiredRenderTimeUs);

	// Update the metrics because a rendered frame was detected.
	void processMetricsForRenderedFrame(int64_t contentTimeUs, int64_t desiredRenderTimeUs,
	int64_t actualRenderTimeUs,
	FreezeEvent freezeEventOut, JudderEvent judderEventOut);

	// Configurable elements of the metrics algorithms.
	const Configuration mConfiguration;

	// The function for triggering trace collection for video freeze.
	const TraceTriggerFn mTraceTriggerFn;

	// Metrics are updated every time a frame event occurs - skipped, dropped, rendered.
	VideoRenderQualityMetrics mMetrics;

	// The most recently processed timestamp referring to the position in the content stream.
	int64_t mLastContentTimeUs;

	// The most recently processed timestamp referring to the wall clock time a frame was rendered.
	int64_t mLastRenderTimeUs;

	// The most recent timestamp of the first frame rendered after the freeze.
	int64_t mLastFreezeEndTimeUs;

	// The most recent timestamp of frame judder.
	int64_t mLastJudderEndTimeUs;

	// The render duration of the playback.
	int64_t mRenderDurationMs;

	// The duration of the content that was dropped.
	int64_t mDroppedContentDurationUs;

	// The freeze event that's currently being tracked.
	FreezeEvent mFreezeEvent;

	// The judder event that's currently being tracked.
	JudderEvent mJudderEvent;

	// Frames skipped at the end of playback shouldn't really be considered skipped, therefore keep
	// a list of the frames, and process them as skipped frames the next time a frame is rendered.
	std::list<int64_t> mPendingSkippedFrameContentTimeUsList;

	// Since the system only signals when a frame is rendered, dropped frames are detected by
	// checking to see if the next expected frame is rendered. If not, it is considered dropped.
	std::queue<FrameInfo> mNextExpectedRenderedFrameQueue;

	// When B-frames are present in the stream, a P-frame will be queued before the B-frame even
	// though it is rendered after. Therefore, the P-frame is held here and not inserted into
	// mNextExpectedRenderedFrameQueue until it should be inserted to maintain render order.
	int64_t mTunnelFrameQueuedContentTimeUs;

	// Frame durations derived from timestamps encoded into the content stream. These are the
	// durations that each frame is supposed to be rendered for.
	FrameDurationUs mContentFrameDurationUs;

	// Frame durations derived from timestamps passed in by the app, indicating the wall clock time
	// at which the app would like to have the frame rendered.
	FrameDurationUs mDesiredFrameDurationUs;

	// Frame durations derived from timestamps captured by the display subsystem, indicating the
	// wall clock atime at which the frame is actually rendered.
	FrameDurationUs mActualFrameDurationUs;

	// Token of async atrace for video frame dropped/skipped by the app.
	int64_t mTraceFrameSkippedToken= -1;
	};

	} // namespace android

	#endif // VIDEO_RENDER_QUALITY_TRACKER_H_