class SetPtsContinuityThreshold

Sets the maximum threshold (in seconds) between explicit user-provided PTS

and expected PTS (determined using interpolation). Beyond this threshold,

a stream is no longer considered 'continuous' by the renderer.

Defaults to an interval of half a PTS 'tick', using the currently-defined PTS units.

Most users should not need to change this value from its default.

Example:

A user is playing back 48KHz audio from a container, which also contains

video and needs to be synchronized with the audio. The timestamps are

provided explicitly per packet by the container, and expressed in mSec

units. This means that a single tick of the media timeline (1 mSec)

represents exactly 48 frames of audio. The application in this scenario

delivers packets of audio to the AudioRenderer, each with exactly 470

frames of audio, and each with an explicit timestamp set to the best

possible representation of the presentation time (given this media

clock's resolution). So, starting from zero, the timestamps would be..

[ 0, 10, 20, 29, 39, 49, 59, 69, 78, 88, ... ]

In this example, attempting to use the presentation time to compute the

starting frame number of the audio in the packet would be wrong the

majority of the time. The first timestamp is correct (by definition), but

it will be 24 packets before the timestamps and frame numbers come back

into alignment (the 24th packet would start with the 11280th audio frame

and have a PTS of exactly 235).

One way to fix this situation is to set the PTS continuity threshold

(henceforth, CT) for the stream to be equal to 1/2 of the time taken by

the number of frames contained within a single tick of the media clock,

rounded up. In this scenario, that would be 24.0 frames of audio, or 500

uSec. Any packets whose expected PTS was within +/-CT frames of the

explicitly provided PTS would be considered to be a continuation of the

previous frame of audio. For this example, calling 'SetPtsContinuityThreshold(0.0005)'

would work well.

Other possible uses:

Users who are scheduling audio explicitly, relative to a clock which has

not been configured as the reference clock, can use this value to control

the maximum acceptable synchronization error before a discontinuity is

introduced. E.g., if a user is scheduling audio based on a recovered

common media clock, and has not published that clock as the reference

clock, and they set the CT to 20mSec, then up to 20mSec of drift error

can accumulate before the AudioRenderer deliberately inserts a

presentation discontinuity to account for the error.

Users whose need to deal with a container where their timestamps may be

even less correct than +/- 1/2 of a PTS tick may set this value to

something larger. This should be the maximum level of inaccuracy present

in the container timestamps, if known. Failing that, it could be set to

the maximum tolerable level of drift error before absolute timestamps are

explicitly obeyed. Finally, a user could set this number to a very large

value (86400.0 seconds, for example) to effectively cause *all*

timestamps to be ignored after the first, thus treating all audio as

continuous with previously delivered packets. Conversely, users who wish

to *always* explicitly schedule their audio packets exactly may specify

a CT of 0.

Note: explicitly specifying high-frequency PTS units reduces the default

continuity threshold accordingly. Internally, this threshold is stored as an

integer of 1/8192 subframes. The default threshold is computed as follows:

RoundUp((AudioFPS/PTSTicksPerSec) * 4096) / (AudioFPS * 8192)

For this reason, specifying PTS units with a frequency greater than 8192x

the frame rate (or NOT calling SetPtsUnits, which accepts the default PTS

unit of 1 nanosec) will result in a default continuity threshold of zero.