# BinarySearchSeeker

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

*** ** * ** ***


```
@UnstableApi
public abstract class BinarySearchSeeker
```

<br />

*** ** * ** ***

A seeker that supports seeking within a stream by searching for the target frame using binary search.

This seeker operates on a stream that contains multiple frames (or samples). Each frame is associated with some kind of timestamps, such as stream time, or frame indices. Given a target seek time, the seeker will find the corresponding target timestamp, and perform a search operation within the stream to identify the target frame and return the byte position in the stream of the target frame.

## Summary

| ### Nested types |
|---|
| `public class https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.BinarySearchSeekMap implements https://developer.android.com/reference/androidx/media3/extractor/SeekMap` A `https://developer.android.com/reference/androidx/media3/extractor/SeekMap` implementation that returns the estimated byte location from `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekOperationParams#calculateNextSearchBytePosition(long,long,long,long,long,long)` for each `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.BinarySearchSeekMap#getSeekPoints(long)` query. |
| `public final class https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.DefaultSeekTimestampConverter implements https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter` A `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter` implementation that returns the seek time itself as the timestamp for a seek time position. |
| `protected class https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekOperationParams` Contains parameters for a pending seek operation by `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker`. |
| `protected interface https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter` A converter that converts seek time in stream time into target timestamp for the `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker`. |
| `public final class https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSearchResult` Represents possible search results for `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker#searchForTimestamp(androidx.media3.extractor.ExtractorInput,long)`. |
| `protected interface https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker` A seeker that looks for a given timestamp from an input. |

| ### Protected fields |
|---|---|
| `final https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.BinarySearchSeekMap` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#seekMap()` |
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekOperationParams` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#seekOperationParams()` |
| `final https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#timestampSeeker()` |

| ### Protected constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#BinarySearchSeeker(androidx.media3.extractor.BinarySearchSeeker.SeekTimestampConverter,androidx.media3.extractor.BinarySearchSeeker.TimestampSeeker,long,long,long,long,long,long,int)( https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter seekTimestampConverter, https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker timestampSeeker, long durationUs, long floorTimePosition, long ceilingTimePosition, long floorBytePosition, long ceilingBytePosition, long approxBytesPerFrame, int minimumSearchRange )` Constructs an instance. |

| ### Public methods |
|---|---|
| `final https://developer.android.com/reference/androidx/media3/extractor/SeekMap` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#getSeekMap()()` Returns the seek map for the stream. |
| `int` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#handlePendingSeek(androidx.media3.extractor.ExtractorInput,androidx.media3.extractor.PositionHolder)( https://developer.android.com/reference/androidx/media3/extractor/ExtractorInput input, https://developer.android.com/reference/androidx/media3/extractor/PositionHolder seekPositionHolder )` Continues to handle the pending seek operation. |
| `final boolean` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#isSeeking()()` Returns whether the last operation set by `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#setSeekTargetUs(long)` is still pending. |
| `final void` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#setSeekTargetUs(long)(long timeUs)` Sets the target time in microseconds within the stream to seek to. |

| ### Protected methods |
|---|---|
| `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekOperationParams` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#createSeekParamsForTargetTimeUs(long)(long timeUs)` |
| `final void` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#markSeekOperationFinished(boolean,long)( boolean foundTargetFrame, long resultPosition )` |
| `void` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#onSeekOperationFinished(boolean,long)(boolean foundTargetFrame, long resultPosition)` |
| `final int` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#seekToPosition(androidx.media3.extractor.ExtractorInput,long,androidx.media3.extractor.PositionHolder)( https://developer.android.com/reference/androidx/media3/extractor/ExtractorInput input, long position, https://developer.android.com/reference/androidx/media3/extractor/PositionHolder seekPositionHolder )` |
| `final boolean` | `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#skipInputUntilPosition(androidx.media3.extractor.ExtractorInput,long)(https://developer.android.com/reference/androidx/media3/extractor/ExtractorInput input, long position)` |

## Protected fields

### seekMap

```
protected final BinarySearchSeeker.BinarySearchSeekMap seekMap
```

### seekOperationParams

```
protected @Nullable BinarySearchSeeker.SeekOperationParams seekOperationParams
```

### timestampSeeker

```
protected final BinarySearchSeeker.TimestampSeeker timestampSeeker
```

## Protected constructors

### BinarySearchSeeker

```
protected BinarySearchSeeker(
    BinarySearchSeeker.SeekTimestampConverter seekTimestampConverter,
    BinarySearchSeeker.TimestampSeeker timestampSeeker,
    long durationUs,
    long floorTimePosition,
    long ceilingTimePosition,
    long floorBytePosition,
    long ceilingBytePosition,
    long approxBytesPerFrame,
    int minimumSearchRange
)
```

Constructs an instance.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter seekTimestampConverter` | The `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.SeekTimestampConverter` that converts seek time in stream time into target timestamp. |
| `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker timestampSeeker` | A `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker.TimestampSeeker` that will be used to search for timestamps within the stream. |
| `long durationUs` | The duration of the stream in microseconds. |
| `long floorTimePosition` | The minimum timestamp value (inclusive) in the stream. |
| `long ceilingTimePosition` | The minimum timestamp value (exclusive) in the stream. |
| `long floorBytePosition` | The starting position of the frame with minimum timestamp value (inclusive) in the stream. |
| `long ceilingBytePosition` | The position after the frame with maximum timestamp value in the stream. |
| `long approxBytesPerFrame` | Approximated bytes per frame. |
| `int minimumSearchRange` | The minimum byte range that this binary seeker will operate on. If the remaining search range is smaller than this value, the search will stop, and the seeker will return the position at the floor of the range as the result. |

## Public methods

### getSeekMap

```
public final SeekMap getSeekMap()
```

Returns the seek map for the stream.

### handlePendingSeek

```
public int handlePendingSeek(
    ExtractorInput input,
    PositionHolder seekPositionHolder
)
```

Continues to handle the pending seek operation. Returns one of the `RESULT_` values from `https://developer.android.com/reference/androidx/media3/extractor/Extractor`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/extractor/ExtractorInput input` | The `https://developer.android.com/reference/androidx/media3/extractor/ExtractorInput` from which data should be read. |
| `https://developer.android.com/reference/androidx/media3/extractor/PositionHolder seekPositionHolder` | If `https://developer.android.com/reference/androidx/media3/extractor/Extractor#RESULT_SEEK()` is returned, this holder is updated to hold the position of the required seek. |

| Returns |
|---|---|
| `int` | One of the `RESULT_` values defined in `https://developer.android.com/reference/androidx/media3/extractor/Extractor`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` | If an error occurred reading from the input. |

### isSeeking

```
public final boolean isSeeking()
```

Returns whether the last operation set by `https://developer.android.com/reference/androidx/media3/extractor/BinarySearchSeeker#setSeekTargetUs(long)` is still pending.

### setSeekTargetUs

```
public final void setSeekTargetUs(long timeUs)
```

Sets the target time in microseconds within the stream to seek to.

| Parameters |
|---|---|
| `long timeUs` | The target time in microseconds within the stream. |

## Protected methods

### createSeekParamsForTargetTimeUs

```
protected BinarySearchSeeker.SeekOperationParams createSeekParamsForTargetTimeUs(long timeUs)
```

### markSeekOperationFinished

```
protected final void markSeekOperationFinished(
    boolean foundTargetFrame,
    long resultPosition
)
```

### onSeekOperationFinished

```
protected void onSeekOperationFinished(boolean foundTargetFrame, long resultPosition)
```

### seekToPosition

```
protected final int seekToPosition(
    ExtractorInput input,
    long position,
    PositionHolder seekPositionHolder
)
```

### skipInputUntilPosition

```
protected final boolean skipInputUntilPosition(ExtractorInput input, long position)
```

| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` |   |