# getTextCues

Every cue on the text tracks a filter or track definition matches

## Import

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

`getTextCues` returns every cue 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), so it only finds cues on the tracks that feature reads: `metadata` and `chapters` tracks that aren’t `disabled`, except the `thumbnails` track, and the tracks a `watchTextCues()` filter matches.

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

## Usage

To read tracks the feature doesn’t read by default, such as captions for a transcript, watch them first:

```ts
const player = document.querySelector('video-player')!;
const captions = { kind: 'captions', language: 'en' } as const;

player.store.watchTextCues(captions);

player.store.subscribe(() => {
  const cues = getTextCues(player.store, captions);
  console.log(cues.map((cue) => cue.text));
});
```

## API Reference

### With Definition

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

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

`const questions = getTextCues(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

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

Every cue 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