From c44c7dd85e9f689906dbe7275becce5b23f0cc55 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 14 Nov 2019 15:57:51 +1300 Subject: [PATCH 1/2] AudioStats JSDoc --- libraries/audio-client/src/AudioIOStats.h | 176 +++++++++++++++------- 1 file changed, 125 insertions(+), 51 deletions(-) diff --git a/libraries/audio-client/src/AudioIOStats.h b/libraries/audio-client/src/AudioIOStats.h index ffd7163586..d5a8cca27d 100644 --- a/libraries/audio-client/src/AudioIOStats.h +++ b/libraries/audio-client/src/AudioIOStats.h @@ -40,138 +40,181 @@ class AudioStreamStatsInterface : public QObject { Q_OBJECT /**jsdoc + * Statistics for an audio stream. + * + *

Provided in the {@link AudioStats} API.

+ * * @class AudioStats.AudioStreamStats * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} lossRate Read-only. - * @property {number} lossCount Read-only. - * @property {number} lossRateWindow Read-only. - * @property {number} lossCountWindow Read-only. - * @property {number} framesDesired Read-only. - * @property {number} framesAvailable Read-only. - * @property {number} framesAvailableAvg Read-only. - * @property {number} unplayedMsMax Read-only. - * @property {number} starveCount Read-only. - * @property {number} lastStarveDurationCount Read-only. - * @property {number} dropCount Read-only. - * @property {number} overflowCount Read-only. - * @property {number} timegapMsMax Read-only. - * @property {number} timegapMsAvg Read-only. - * @property {number} timegapMsMaxWindow Read-only. - * @property {number} timegapMsAvgWindow Read-only. + * @property {number} dropCount - The number of silent or old audio frames dropped. + * Read-only. + * @property {number} framesAvailable - The number of audio frames containing data available. + * Read-only. + * @property {number} framesAvailableAvg - The time-weighted average of audio frames containing data available. + * Read-only. + * @property {number} framesDesired - The desired number of audio frames for the jitter buffer. + * Read-only. + * @property {number} lastStarveDurationCount - The most recent number of consecutive times that audio frames have not been + * available for processing. + * Read-only. + * @property {number} lossCount - The total number of audio packets lost. + * Read-only. + * @property {number} lossCountWindow - The number of audio packets lost since the previous statistic. + * Read-only. + * @property {number} lossRate - The total number of audio packets lost divided by the total number of audio packets + * expected. + * Read-only. + * @property {number} lossRateWindow - The number of audio packets lost divided by the total number of audio packets + * expected since the previous statistic. + * Read-only. + * @property {number} overflowCount - The number of times that the audio ring buffer has overflowed. + * Read-only. + * @property {number} starveCount - The total number of times that audio frames have not been available for processing. + * Read-only. + * @property {number} timegapMsAvg - The overall average time between data packets, in ms. + * Read-only. + * @property {number} timegapMsAvgWindow - The recent average time between data packets, in ms. + * Read-only. + * @property {number} timegapMsMax - The overall maximum time between data packets, in ms. + * Read-only. + * @property {number} timegapMsMaxWindow - The recent maximum time between data packets, in ms. + * Read-only. + * @property {number} unplayedMsMax - The duration of audio waiting to be played, in ms. + * Read-only. */ /**jsdoc + * Triggered when the total number of audio packets lost divided by the total number of audio packets expected changes. * @function AudioStats.AudioStreamStats.lossRateChanged - * @param {number} lossRate + * @param {number} lossRate - The total number of audio packets lost divided by the total number of audio packets expected. * @returns {Signal} */ AUDIO_PROPERTY(float, lossRate) /**jsdoc + * Triggered when the total number of audio packets lost changes. * @function AudioStats.AudioStreamStats.lossCountChanged - * @param {number} lossCount + * @param {number} lossCount - The total number of audio packets lost. * @returns {Signal} */ AUDIO_PROPERTY(float, lossCount) /**jsdoc + * Triggered when the number of audio packets lost divided by the total number of audio packets expected since the previous + * statistic changes. * @function AudioStats.AudioStreamStats.lossRateWindowChanged - * @param {number} lossRateWindow + * @param {number} lossRateWindow - The number of audio packets lost divided by the total number of audio packets expected + * since the previous statistic. * @returns {Signal} */ AUDIO_PROPERTY(float, lossRateWindow) /**jsdoc + * Triggered when the number of audio packets lost since the previous statistic changes. * @function AudioStats.AudioStreamStats.lossCountWindowChanged - * @param {number} lossCountWindow + * @param {number} lossCountWindow - The number of audio packets lost since the previous statistic. * @returns {Signal} */ AUDIO_PROPERTY(float, lossCountWindow) /**jsdoc + * Triggered when the desired number of audio frames for the jitter buffer changes. * @function AudioStats.AudioStreamStats.framesDesiredChanged - * @param {number} framesDesired + * @param {number} framesDesired - The desired number of audio frames for the jitter buffer. * @returns {Signal} */ AUDIO_PROPERTY(int, framesDesired) /**jsdoc + * Triggered when the number of audio frames containing data available changes. * @function AudioStats.AudioStreamStats.framesAvailableChanged - * @param {number} framesAvailable + * @param {number} framesAvailable - The number of audio frames containing data available. * @returns {Signal} */ AUDIO_PROPERTY(int, framesAvailable) /**jsdoc + * Triggered when the time-weighted average of audio frames containing data available changes. * @function AudioStats.AudioStreamStats.framesAvailableAvgChanged - * @param {number} framesAvailableAvg + * @param {number} framesAvailableAvg - The time-weighted average of audio frames containing data available. * @returns {Signal} */ AUDIO_PROPERTY(int, framesAvailableAvg) /**jsdoc + * Triggered when the duration of audio waiting to be played changes. * @function AudioStats.AudioStreamStats.unplayedMsMaxChanged - * @param {number} unplayedMsMax + * @param {number} unplayedMsMax - The duration of audio waiting to be played, in ms. * @returns {Signal} */ AUDIO_PROPERTY(float, unplayedMsMax) /**jsdoc + * Triggered when the total number of times that audio frames have not been available for processing changes. * @function AudioStats.AudioStreamStats.starveCountChanged - * @param {number} starveCount + * @param {number} starveCount - The total number of times that audio frames have not been available for processing. * @returns {Signal} */ AUDIO_PROPERTY(int, starveCount) /**jsdoc + * Triggered when the most recenbernumber of consecutive times that audio frames have not been available for processing + * changes. * @function AudioStats.AudioStreamStats.lastStarveDurationCountChanged - * @param {number} lastStarveDurationCount + * @param {number} lastStarveDurationCount - The most recent number of consecutive times that audio frames have not been + * available for processing. * @returns {Signal} */ AUDIO_PROPERTY(int, lastStarveDurationCount) /**jsdoc + * Triggered when the number of silent or old audio frames dropped changes. * @function AudioStats.AudioStreamStats.dropCountChanged - * @param {number} dropCount + * @param {number} dropCount - The number of silent or old audio frames dropped. * @returns {Signal} */ AUDIO_PROPERTY(int, dropCount) /**jsdoc + * Triggered when the number of times that the audio ring buffer has overflowed changes. * @function AudioStats.AudioStreamStats.overflowCountChanged - * @param {number} overflowCount + * @param {number} overflowCount - The number of times that the audio ring buffer has overflowed. * @returns {Signal} */ AUDIO_PROPERTY(int, overflowCount) /**jsdoc + * Triggered when the overall maximum time between data packets changes. * @function AudioStats.AudioStreamStats.timegapMsMaxChanged - * @param {number} timegapMsMax + * @param {number} timegapMsMax - The overall maximum time between data packets, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, timegapMsMax) /**jsdoc + * Triggered when the overall average time between data packets changes. * @function AudioStats.AudioStreamStats.timegapMsAvgChanged - * @param {number} timegapMsAvg + * @param {number} timegapMsAvg - The overall average time between data packets, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, timegapMsAvg) /**jsdoc + * Triggered when the recent maximum time between data packets changes. * @function AudioStats.AudioStreamStats.timegapMsMaxWindowChanged - * @param {number} timegapMsMaxWindow + * @param {number} timegapMsMaxWindow - The recent maximum time between data packets, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, timegapMsMaxWindow) /**jsdoc + * Triggered when the recent average time between data packets changes. * @function AudioStats.AudioStreamStats.timegapMsAvgWindowChanged - * @param {number} timegapMsAvgWindow + * @param {number} timegapMsAvgWindow - The recent average time between data packets, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, timegapMsAvgWindow) @@ -188,79 +231,106 @@ class AudioStatsInterface : public QObject { Q_OBJECT /**jsdoc - * Audio stats from the client. + * The AudioStats API provides statistics of the client and mixer audio. + * * @namespace AudioStats * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} pingMs Read-only. - * @property {number} inputReadMsMax Read-only. - * @property {number} inputUnplayedMsMax Read-only. - * @property {number} outputUnplayedMsMax Read-only. - * @property {number} sentTimegapMsMax Read-only. - * @property {number} sentTimegapMsAvg Read-only. - * @property {number} sentTimegapMsMaxWindow Read-only. - * @property {number} sentTimegapMsAvgWindow Read-only. - * @property {AudioStats.AudioStreamStats} clientStream Read-only. - * @property {AudioStats.AudioStreamStats} mixerStream Read-only. + * @property {AudioStats.AudioStreamStats} clientStream - Statistics of the client's audio stream. + * Read-only. + * @property {number} inputReadMsMax - The maximum duration of a block of audio data recently read from the microphone, in + * ms. + * Read-only. + * @property {number} inputUnplayedMsMax - The maximum duration of microphone audio recently in the input buffer waiting to + * be played, in ms. + * Read-only. + * @property {AudioStats.AudioStreamStats} mixerStream - Statistics of the audio mixer's stream. + * Read-only. + * @property {number} outputUnplayedMsMax - The maximum duration of output audio recently in the output buffer waiting to + * be played, in ms. + * Read-only. + * @property {number} pingMs - The current ping time to the audio mixer, in ms. + * Read-only. + * @property {number} sentTimegapMsAvg - The overall average time between sending data packets to the audio mixer, in ms. + * Read-only. + * @property {number} sentTimegapMsAvgWindow - The recent average time between sending data packets to the audio mixer, in + * ms. + * Read-only. + * @property {number} sentTimegapMsMax - The overall maximum time between sending data packets to the audio mixer, in ms. + * Read-only. + * @property {number} sentTimegapMsMaxWindow - The recent maximum time between sending data packets to the audio mixer, in + * ms. + * Read-only. */ /**jsdoc + * Triggered when the ping time to the audio mixer changes. * @function AudioStats.pingMsChanged - * @param {number} pingMs + * @param {number} pingMs - The ping time to the audio mixer, in ms. * @returns {Signal} */ AUDIO_PROPERTY(float, pingMs); /**jsdoc + * Triggered when the maximum duration of a block of audio data recently read from the microphone changes. * @function AudioStats.inputReadMsMaxChanged - * @param {number} inputReadMsMax + * @param {number} inputReadMsMax - The maximum duration of a block of audio data recently read from the microphone, in ms. * @returns {Signal} */ AUDIO_PROPERTY(float, inputReadMsMax); /**jsdoc + * Triggered when the maximum duration of microphone audio recently in the input buffer waiting to be played changes. * @function AudioStats.inputUnplayedMsMaxChanged - * @param {number} inputUnplayedMsMax + * @param {number} inputUnplayedMsMax - The maximum duration of microphone audio recently in the input buffer waiting to be + * played, in ms. * @returns {Signal} */ AUDIO_PROPERTY(float, inputUnplayedMsMax); /**jsdoc + * Triggered when the maximum duration of output audio recently in the output buffer waiting to be played changes. * @function AudioStats.outputUnplayedMsMaxChanged - * @param {number} outputUnplayedMsMax + * @param {number} outputUnplayedMsMax - The maximum duration of output audio recently in the output buffer waiting to be + * played, in ms. * @returns {Signal} */ AUDIO_PROPERTY(float, outputUnplayedMsMax); /**jsdoc + * Triggered when the overall maximum time between sending data packets to the audio mixer changes. * @function AudioStats.sentTimegapMsMaxChanged - * @param {number} sentTimegapMsMax + * @param {number} sentTimegapMsMax - The overall maximum time between sending data packets to the audio mixer, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, sentTimegapMsMax); /**jsdoc + * Triggered when the overall average time between sending data packets to the audio mixer changes. * @function AudioStats.sentTimegapMsAvgChanged - * @param {number} sentTimegapMsAvg + * @param {number} sentTimegapMsAvg - The overall average time between sending data packets to the audio mixer, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, sentTimegapMsAvg); /**jsdoc + * Triggered when the recent maximum time between sending data packets to the audio mixer changes. * @function AudioStats.sentTimegapMsMaxWindowChanged - * @param {number} sentTimegapMsMaxWindow + * @param {number} sentTimegapMsMaxWindow - The recent maximum time between sending data packets to the audio mixer, in ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, sentTimegapMsMaxWindow); /**jsdoc + * Triggered when the recent average time between sending data packets to the audio mixer changes. * @function AudioStats.sentTimegapMsAvgWindowChanged - * @param {number} sentTimegapMsAvgWindow + * @param {number} sentTimegapMsAvgWindow - The recent average time between sending data packets to the audio mixer, in + * ms. * @returns {Signal} */ AUDIO_PROPERTY(quint64, sentTimegapMsAvgWindow); @@ -287,18 +357,22 @@ public: signals: /**jsdoc + * Triggered when the mixer's stream statistics have been updated. * @function AudioStats.mixerStreamChanged * @returns {Signal} */ void mixerStreamChanged(); /**jsdoc + * Triggered when the client's stream statisticss have been updated. * @function AudioStats.clientStreamChanged * @returns {Signal} */ void clientStreamChanged(); /**jsdoc + * Triggered when the injector streams' statistics have been updated. + *

Note: The injector streams' statistics are currently not provided.

* @function AudioStats.injectorStreamsChanged * @returns {Signal} */ From ef45a6092f93802022b761ad140d10ddd6bab13b Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 14 Nov 2019 16:07:00 +1300 Subject: [PATCH 2/2] Polishing --- libraries/audio-client/src/AudioIOStats.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/libraries/audio-client/src/AudioIOStats.h b/libraries/audio-client/src/AudioIOStats.h index d5a8cca27d..26ea301eaa 100644 --- a/libraries/audio-client/src/AudioIOStats.h +++ b/libraries/audio-client/src/AudioIOStats.h @@ -65,10 +65,10 @@ class AudioStreamStatsInterface : public QObject { * Read-only. * @property {number} lossCountWindow - The number of audio packets lost since the previous statistic. * Read-only. - * @property {number} lossRate - The total number of audio packets lost divided by the total number of audio packets + * @property {number} lossRate - The ratio of the total number of audio packets lost to the total number of audio packets * expected. * Read-only. - * @property {number} lossRateWindow - The number of audio packets lost divided by the total number of audio packets + * @property {number} lossRateWindow - The ratio of the number of audio packets lost to the number of audio packets * expected since the previous statistic. * Read-only. * @property {number} overflowCount - The number of times that the audio ring buffer has overflowed. @@ -88,9 +88,10 @@ class AudioStreamStatsInterface : public QObject { */ /**jsdoc - * Triggered when the total number of audio packets lost divided by the total number of audio packets expected changes. + * Triggered when the ratio of the total number of audio packets lost to the total number of audio packets expected changes. * @function AudioStats.AudioStreamStats.lossRateChanged - * @param {number} lossRate - The total number of audio packets lost divided by the total number of audio packets expected. + * @param {number} lossRate - The ratio of the total number of audio packets lost to the total number of audio packets + * expected. * @returns {Signal} */ AUDIO_PROPERTY(float, lossRate) @@ -104,10 +105,10 @@ class AudioStreamStatsInterface : public QObject { AUDIO_PROPERTY(float, lossCount) /**jsdoc - * Triggered when the number of audio packets lost divided by the total number of audio packets expected since the previous + * Triggered when the ratio of the number of audio packets lost to the number of audio packets expected since the previous * statistic changes. * @function AudioStats.AudioStreamStats.lossRateWindowChanged - * @param {number} lossRateWindow - The number of audio packets lost divided by the total number of audio packets expected + * @param {number} lossRateWindow - The ratio of the number of audio packets lost to the number of audio packets expected * since the previous statistic. * @returns {Signal} */