TimestampAdjuster

Kotlin |Java

@UnstableApi
class TimestampAdjuster

Adjusts and offsets sample timestamps. MPEG-2 TS timestamps scaling and adjustment is supported, taking into account timestamp rollover.

Summary

Constants
`const Long`	`MODE_NO_OFFSET = 9223372036854775807` A special `firstSampleTimestampUs` value indicating that presentation timestamps should not be offset.
`const Long`	`MODE_SHARED = 9223372036854775806` A special `firstSampleTimestampUs` value indicating that the adjuster will be shared by multiple threads.

Public constructors
`TimestampAdjuster(firstSampleTimestampUs: Long)`

Public functions
`synchronized Long`	`adjustSampleTimestamp(timeUs: Long)` Offsets a timestamp in microseconds.
`synchronized Long`	`adjustTsTimestamp(pts90Khz: Long)` Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.
`synchronized Long`	`adjustTsTimestampGreaterThanPreviousTimestamp(pts90Khz: Long)` Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.
`synchronized Long`	`getLastAdjustedTimestampUs()` Returns the last adjusted timestamp, in microseconds.
`synchronized Boolean`	`isInitialized()` Returns whether the instance is initialized with a timestamp offset.
`java-static Long`	`ptsToUs(pts: Long)` Converts a 90 kHz clock timestamp to a timestamp in microseconds.
`synchronized Unit`	`reset(firstSampleTimestampUs: Long)` Resets the instance.
`synchronized Unit`	`sharedInitializeOrWait( canInitialize: Boolean, nextSampleTimestampUs: Long, timeoutMs: Long )` For shared timestamp adjusters, performs necessary initialization actions for a caller.
`java-static Long`	`usToNonWrappedPts(us: Long)` Converts a timestamp in microseconds to a 90 kHz clock timestamp.
`java-static Long`	`usToWrappedPts(us: Long)` Converts a timestamp in microseconds to a 90 kHz clock timestamp, performing wraparound to keep the result within 33-bits.

Public properties
`Long`	`@GuardedBy(value = "this") firstSampleTimestampUs`
`Long`	`@GuardedBy(value = "this") timestampOffsetUs`

Constants

MODE_NO_OFFSET

const val MODE_NO_OFFSET = 9223372036854775807: Long

A special firstSampleTimestampUs value indicating that presentation timestamps should not be offset. In this mode:

getFirstSampleTimestampUs will always return TIME_UNSET.
The only timestamp adjustment performed is to account for MPEG-2 TS timestamp rollover.

MODE_SHARED

const val MODE_SHARED = 9223372036854775806: Long

A special firstSampleTimestampUs value indicating that the adjuster will be shared by multiple threads. In this mode:

getFirstSampleTimestampUs will always return TIME_UNSET.
Calling threads must call sharedInitializeOrWait prior to adjusting timestamps.

Public constructors

TimestampAdjuster

TimestampAdjuster(firstSampleTimestampUs: Long)

Parameters
`firstSampleTimestampUs: Long`	The desired value of the first adjusted sample timestamp in microseconds, or `MODE_NO_OFFSET` if timestamps should not be offset, or `MODE_SHARED` if the adjuster will be used in shared mode.

Public functions

adjustSampleTimestamp

synchronized fun adjustSampleTimestamp(timeUs: Long): Long

Offsets a timestamp in microseconds.

Parameters
`timeUs: Long`	The timestamp to adjust in microseconds.

Returns
`Long`	The adjusted timestamp in microseconds.

adjustTsTimestamp

synchronized fun adjustTsTimestamp(pts90Khz: Long): Long

Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.

When estimating the wraparound, the method assumes that this timestamp is close to the previous adjusted timestamp.

Parameters
`pts90Khz: Long`	A 90 kHz clock MPEG-2 TS presentation timestamp.

Returns
`Long`	The adjusted timestamp in microseconds.

adjustTsTimestampGreaterThanPreviousTimestamp

synchronized fun adjustTsTimestampGreaterThanPreviousTimestamp(pts90Khz: Long): Long

Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.

When estimating the wraparound, the method assumes that the timestamp is strictly greater than the previous adjusted timestamp.

Parameters
`pts90Khz: Long`	A 90 kHz clock MPEG-2 TS presentation timestamp.

Returns
`Long`	The adjusted timestamp in microseconds.

getLastAdjustedTimestampUs

synchronized fun getLastAdjustedTimestampUs(): Long

Returns the last adjusted timestamp, in microseconds. If no timestamps have been adjusted yet then the result of getFirstSampleTimestampUs is returned.

isInitialized

synchronized fun isInitialized(): Boolean

Returns whether the instance is initialized with a timestamp offset.

ptsToUs

java-static fun ptsToUs(pts: Long): Long

Converts a 90 kHz clock timestamp to a timestamp in microseconds.

Parameters
`pts: Long`	A 90 kHz clock timestamp.

Returns
`Long`	The corresponding value in microseconds.

reset

synchronized fun reset(firstSampleTimestampUs: Long): Unit

Resets the instance.

Parameters
`firstSampleTimestampUs: Long`	The desired value of the first adjusted sample timestamp after this reset in microseconds, or `MODE_NO_OFFSET` if timestamps should not be offset, or `MODE_SHARED` if the adjuster will be used in shared mode.

sharedInitializeOrWait

synchronized fun sharedInitializeOrWait(
    canInitialize: Boolean,
    nextSampleTimestampUs: Long,
    timeoutMs: Long
): Unit

For shared timestamp adjusters, performs necessary initialization actions for a caller.

If the adjuster has already established a timestamp offset then this method is a no-op.
If canInitialize is true and the adjuster has not yet established a timestamp offset, then the adjuster records the desired first sample timestamp for the calling thread and returns to allow the caller to proceed. If the timestamp offset has still not been established when the caller attempts to adjust its first timestamp, then the recorded timestamp is used to set it.
If canInitialize is false and the adjuster has not yet established a timestamp offset, then the call blocks until the timestamp offset is set.

Parameters
`canInitialize: Boolean`	Whether the caller is able to initialize the adjuster, if needed.
`nextSampleTimestampUs: Long`	The desired timestamp for the next sample loaded by the calling thread, in microseconds. Only used if `canInitialize` is `true`.
`timeoutMs: Long`	The timeout for the thread to wait for the timestamp adjuster to initialize, in milliseconds. A timeout of zero is interpreted as an infinite timeout.

Throws
`java.lang.InterruptedException`	If the thread is interrupted whilst blocked waiting for initialization to complete.
`java.util.concurrent.TimeoutException`	If the thread is timeout whilst blocked waiting for initialization to complete.

usToNonWrappedPts

java-static fun usToNonWrappedPts(us: Long): Long

Converts a timestamp in microseconds to a 90 kHz clock timestamp.

Does not perform any wraparound. To get a 90 kHz timestamp suitable for use with MPEG-TS, use usToWrappedPts.

Parameters
`us: Long`	A value in microseconds.

Returns
`Long`	The corresponding value as a 90 kHz clock timestamp.

usToWrappedPts

java-static fun usToWrappedPts(us: Long): Long

Converts a timestamp in microseconds to a 90 kHz clock timestamp, performing wraparound to keep the result within 33-bits.

Parameters
`us: Long`	A value in microseconds.

Returns
`Long`	The corresponding value as a 90 kHz clock timestamp, wrapped to 33 bits.

Public properties

firstSampleTimestampUs

@GuardedBy(value = "this")
val firstSampleTimestampUs: Long

timestampOffsetUs

@GuardedBy(value = "this")
val timestampOffsetUs: Long