Package com.google.android.exoplayer2.util

## Class TimestampAdjuster

- java.lang.Object
- - com.google.android.exoplayer2.util.TimestampAdjuster

-     public final class TimestampAdjuster
      extends Object

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

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static long` | `MODE_NO_OFFSET` | A special `firstSampleTimestampUs` value indicating that presentation timestamps should not be offset.
    `static long` | `MODE_SHARED` | A special `firstSampleTimestampUs` value indicating that the adjuster will be shared by multiple threads.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TimestampAdjuster​(long firstSampleTimestampUs)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `long` | `adjustSampleTimestamp​(long timeUs)` | Offsets a timestamp in microseconds.
    `long` | `adjustTsTimestamp​(long pts90Khz)` | Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.
    `long` | `getFirstSampleTimestampUs()` | Returns the value of the first adjusted sample timestamp in microseconds, or `C.TIME_UNSET` if timestamps will not be offset or if the adjuster is in shared mode.
    `long` | `getLastAdjustedTimestampUs()` | Returns the last adjusted timestamp, in microseconds.
    `long` | `getTimestampOffsetUs()` | Returns the offset between the input of `adjustSampleTimestamp(long)` and its output, or `C.TIME_UNSET` if the offset has not yet been determined.
    `static long` | `ptsToUs​(long pts)` | Converts a 90 kHz clock timestamp to a timestamp in microseconds.
    `void` | `reset​(long firstSampleTimestampUs)` | Resets the instance.
    `void` | `sharedInitializeOrWait​(boolean canInitialize, long nextSampleTimestampUs)` | For shared timestamp adjusters, performs necessary initialization actions for a caller.
    `static long` | `usToNonWrappedPts​(long us)` | Converts a timestamp in microseconds to a 90 kHz clock timestamp.
    `static long` | `usToWrappedPts​(long us)` | Converts a timestamp in microseconds to a 90 kHz clock timestamp, performing wraparound to keep the result within 33-bits.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### MODE_NO_OFFSET

          public static final long MODE_NO_OFFSET

      A special `firstSampleTimestampUs` value indicating that presentation timestamps should not be offset. In this mode:
      - `getFirstSampleTimestampUs()` will always return `C.TIME_UNSET`.
      - The only timestamp adjustment performed is to account for MPEG-2 TS timestamp rollover.
      See Also:
        Constant Field Values

    - #### MODE_SHARED

          public static final long MODE_SHARED

      A special `firstSampleTimestampUs` value indicating that the adjuster will be shared by multiple threads. In this mode:
      - `getFirstSampleTimestampUs()` will always return `C.TIME_UNSET`.
      - Calling threads must call `sharedInitializeOrWait(boolean, long)` prior to adjusting timestamps.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TimestampAdjuster

          public TimestampAdjuster​(long firstSampleTimestampUs)

      Parameters:
        `firstSampleTimestampUs` - 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.

  - ### Method Detail

    - #### sharedInitializeOrWait

          public void sharedInitializeOrWait​(boolean canInitialize,
                                             long nextSampleTimestampUs)
                                      throws InterruptedException

      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` - Whether the caller is able to initialize the adjuster, if needed.
        `nextSampleTimestampUs` - The desired timestamp for the next sample loaded by the calling thread, in microseconds. Only used if `canInitialize` is `true`.
      Throws:
        `InterruptedException` - If the thread is interrupted whilst blocked waiting for initialization to complete.

    - #### getFirstSampleTimestampUs

          public long getFirstSampleTimestampUs()

      Returns the value of the first adjusted sample timestamp in microseconds, or `C.TIME_UNSET` if timestamps will not be offset or if the adjuster is in shared mode.

    - #### getLastAdjustedTimestampUs

          public long getLastAdjustedTimestampUs()

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

    - #### getTimestampOffsetUs

          public long getTimestampOffsetUs()

      Returns the offset between the input of `adjustSampleTimestamp(long)` and its output, or `C.TIME_UNSET` if the offset has not yet been determined.

    - #### reset

          public void reset​(long firstSampleTimestampUs)

      Resets the instance.
      Parameters:
        `firstSampleTimestampUs` - 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.

    - #### adjustTsTimestamp

          public long adjustTsTimestamp​(long pts90Khz)

      Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound.
      Parameters:
        `pts90Khz` - A 90 kHz clock MPEG-2 TS presentation timestamp.
      Returns:
        The adjusted timestamp in microseconds.

    - #### adjustSampleTimestamp

          public long adjustSampleTimestamp​(long timeUs)

      Offsets a timestamp in microseconds.
      Parameters:
        `timeUs` - The timestamp to adjust in microseconds.
      Returns:
        The adjusted timestamp in microseconds.

    - #### ptsToUs

          public static long ptsToUs​(long pts)

      Converts a 90 kHz clock timestamp to a timestamp in microseconds.
      Parameters:
        `pts` - A 90 kHz clock timestamp.
      Returns:
        The corresponding value in microseconds.

    - #### usToWrappedPts

          public static long usToWrappedPts​(long us)

      Converts a timestamp in microseconds to a 90 kHz clock timestamp, performing wraparound to keep the result within 33-bits.
      Parameters:
        `us` - A value in microseconds.
      Returns:
        The corresponding value as a 90 kHz clock timestamp, wrapped to 33 bits.

    - #### usToNonWrappedPts

          public static long usToNonWrappedPts​(long us)

      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(long)`.

      Parameters:
        `us` - A value in microseconds.
      Returns:
        The corresponding value as a 90 kHz clock timestamp.