# getActiveTextCues

The cues active now on the text tracks a filter or track definition matches

## Import

```ts
import { getActiveTextCues } from '@videojs/html';
```

`getActiveTextCues` returns the cues active at the current time on the tracks a filter or [track definition](https://videojs.org/docs/framework/html/reference/api/define-text-track) matches, from the media and the app alike. Cues from several tracks are merged in time order.

It reads `textCues` from the [text cues feature](https://videojs.org/docs/framework/html/reference/api/feature-text-cues), which describes when a cue is active, so it only finds cues on the tracks that feature reads.

Read through a definition, cues are typed by it. With a schema, cues whose value fails it are skipped.

## Usage

Read the active cues in a `player.store.subscribe()` callback to follow playback:

```ts
const player = document.querySelector('video-player')!;
const quiz = document.querySelector<HTMLElement>('.quiz')!;

player.store.subscribe(() => {
  const [cue] = getActiveTextCues(player.store, quizTrack);

  quiz.hidden = !cue;
  quiz.textContent = cue?.value?.question ?? '';
});
```

## API Reference

### With Definition

`getActiveTextCues<Cue extends MediaTextCue>(source, track): readonly Cue[]`

The cues active now on the tracks a track definition matches, typed by the definition. With a schema, cues whose value fails it are skipped.

`player.store.subscribe(() => { const [question] = getActiveTextCues(player.store, quizTrack); });`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
| `track` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | — | The track definition to read. |

#### Return Value

`readonly Cue[]`

### With Filter

`getActiveTextCues(source, filter?): readonly MediaTextCue[]`

The cues active now on the tracks a filter matches, from the media or the app.

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
| `filter` | `{ kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)` | — | Picks tracks by kind, label, or language, or with a function. Defaults to every track being read. |

#### Return Value

`readonly MediaTextCue[]`

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt