# TimestampAdjuster

Artifact: [androidx.media3:media3-common](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/common/util/TimestampAdjuster.java+class:androidx.media3.common.util.TimestampAdjuster)

*** ** * ** ***


```
@UnstableApi
public final class TimestampAdjuster
```

<br />

*** ** * ** ***

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

## Summary

| ### Constants |
|---|---|
| `static final long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_NO_OFFSET() = 9223372036854775807` A special `firstSampleTimestampUs` value indicating that presentation timestamps should not be offset. |
| `static final long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED() = 9223372036854775806` A special `firstSampleTimestampUs` value indicating that the adjuster will be shared by multiple threads. |

| ### Public fields |
|---|---|
| `long` | `@https://developer.android.com/reference/androidx/annotation/GuardedBy(value = "this") https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#firstSampleTimestampUs()` |
| `long` | `@https://developer.android.com/reference/androidx/annotation/GuardedBy(value = "this") https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#timestampOffsetUs()` |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#TimestampAdjuster(long)(long firstSampleTimestampUs)` |

| ### Public methods |
|---|---|
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#adjustSampleTimestamp(long)(long timeUs)` Offsets a timestamp in microseconds. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#adjustTsTimestamp(long)(long pts90Khz)` Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#adjustTsTimestampGreaterThanPreviousTimestamp(long)(long pts90Khz)` Scales and offsets an MPEG-2 TS presentation timestamp considering wraparound. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getFirstSampleTimestampUs()()` Returns the value of the first adjusted sample timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if timestamps will not be offset or if the adjuster is in shared mode. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getLastAdjustedTimestampUs()()` Returns the last adjusted timestamp, in microseconds. |
| `synchronized long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getTimestampOffsetUs()()` Returns the offset between the input of `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#adjustSampleTimestamp(long)` and its output, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if the offset has not yet been determined. |
| `synchronized boolean` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#isInitialized()()` Returns whether the instance is initialized with a timestamp offset. |
| `static long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#ptsToUs(long)(long pts)` Converts a 90 kHz clock timestamp to a timestamp in microseconds. |
| `synchronized void` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#reset(long)(long firstSampleTimestampUs)` Resets the instance. |
| `synchronized void` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#sharedInitializeOrWait(boolean,long,long)( boolean canInitialize, long nextSampleTimestampUs, long timeoutMs )` For shared timestamp adjusters, performs necessary initialization actions for a caller. |
| `static long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#usToNonWrappedPts(long)(long us)` Converts a timestamp in microseconds to a 90 kHz clock timestamp. |
| `static long` | `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#usToWrappedPts(long)(long us)` Converts a timestamp in microseconds to a 90 kHz clock timestamp, performing wraparound to keep the result within 33-bits. |

## Constants

### MODE_NO_OFFSET

```
public static final long MODE_NO_OFFSET = 9223372036854775807
```

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

- `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getFirstSampleTimestampUs()` will always return `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()`.
- The only timestamp adjustment performed is to account for MPEG-2 TS timestamp rollover.

### MODE_SHARED

```
public static final long MODE_SHARED = 9223372036854775806
```

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

- `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getFirstSampleTimestampUs()` will always return `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()`.
- Calling threads must call `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#sharedInitializeOrWait(boolean,long,long)` prior to adjusting timestamps.

## Public fields

### firstSampleTimestampUs

```
@GuardedBy(value = "this")
public long firstSampleTimestampUs
```

### timestampOffsetUs

```
@GuardedBy(value = "this")
public long timestampOffsetUs
```

## Public constructors

### TimestampAdjuster

```
public TimestampAdjuster(long firstSampleTimestampUs)
```

| Parameters |
|---|---|
| `long firstSampleTimestampUs` | The desired value of the first adjusted sample timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_NO_OFFSET()` if timestamps should not be offset, or `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED()` if the adjuster will be used in shared mode. |

## Public methods

### adjustSampleTimestamp

```
synchronized public long adjustSampleTimestamp(long timeUs)
```

Offsets a timestamp in microseconds.

| Parameters |
|---|---|
| `long timeUs` | The timestamp to adjust in microseconds. |

| Returns |
|---|---|
| `long` | The adjusted timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if `timeUs` is `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` or if the adjuster is in `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED()` and has not yet been initialized via `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#sharedInitializeOrWait(boolean,long,long)`. |

### adjustTsTimestamp

```
synchronized public long adjustTsTimestamp(long pts90Khz)
```

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 |
|---|---|
| `long pts90Khz` | A 90 kHz clock MPEG-2 TS presentation timestamp. |

| Returns |
|---|---|
| `long` | The adjusted timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if `pts90Khz` is `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` or if the adjuster is in `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED()` and has not yet been initialized via `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#sharedInitializeOrWait(boolean,long,long)`. |

### adjustTsTimestampGreaterThanPreviousTimestamp

```
synchronized public long adjustTsTimestampGreaterThanPreviousTimestamp(long pts90Khz)
```

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 |
|---|---|
| `long pts90Khz` | A 90 kHz clock MPEG-2 TS presentation timestamp. |

| Returns |
|---|---|
| `long` | The adjusted timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if `pts90Khz` is `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` or if the adjuster is in `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED()` and has not yet been initialized via `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#sharedInitializeOrWait(boolean,long,long)`. |

### getFirstSampleTimestampUs

```
synchronized public long getFirstSampleTimestampUs()
```

Returns the value of the first adjusted sample timestamp in microseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if timestamps will not be offset or if the adjuster is in shared mode.

### getLastAdjustedTimestampUs

```
synchronized public long getLastAdjustedTimestampUs()
```

Returns the last adjusted timestamp, in microseconds. If no timestamps have been adjusted yet then the result of `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getFirstSampleTimestampUs()` is returned.

### getTimestampOffsetUs

```
synchronized public long getTimestampOffsetUs()
```

Returns the offset between the input of `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#adjustSampleTimestamp(long)` and its output, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if the offset has not yet been determined.

### isInitialized

```
synchronized public boolean isInitialized()
```

Returns whether the instance is initialized with a timestamp offset.

### ptsToUs

```
public static long ptsToUs(long pts)
```

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

| Parameters |
|---|---|
| `long pts` | A 90 kHz clock timestamp. |

| Returns |
|---|---|
| `long` | The corresponding value in microseconds. |

### reset

```
synchronized public void reset(long firstSampleTimestampUs)
```

Resets the instance.

| Parameters |
|---|---|
| `long firstSampleTimestampUs` | The desired value of the first adjusted sample timestamp after this reset in microseconds, or `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_NO_OFFSET()` if timestamps should not be offset, or `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#MODE_SHARED()` if the adjuster will be used in shared mode. |

### sharedInitializeOrWait

```
synchronized public void sharedInitializeOrWait(
    boolean canInitialize,
    long nextSampleTimestampUs,
    long timeoutMs
)
```

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

- If the adjuster has already established a `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#getTimestampOffsetUs()` 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 |
|---|---|
| `boolean canInitialize` | Whether the caller is able to initialize the adjuster, if needed. |
| `long nextSampleTimestampUs` | The desired timestamp for the next sample loaded by the calling thread, in microseconds. Only used if `canInitialize` is `true`. |
| `long timeoutMs` | 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 |
|---|---|
| `https://developer.android.com/reference/java/lang/InterruptedException.html` | If the thread is interrupted whilst blocked waiting for initialization to complete. |
| `https://developer.android.com/reference/java/util/concurrent/TimeoutException.html` | If the thread is timeout whilst blocked waiting for initialization to complete. |

### 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 `https://developer.android.com/reference/androidx/media3/common/util/TimestampAdjuster#usToWrappedPts(long)`.

| Parameters |
|---|---|
| `long us` | A value in microseconds. |

| Returns |
|---|---|
| `long` | The corresponding value as a 90 kHz clock timestamp. |

### 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 |
|---|---|
| `long us` | A value in microseconds. |

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