# `Dala.Media.Subtitle`
[🔗](https://github.com/manhvu/dala/blob/main/lib/dala/media/subtitle.ex#L1)

Timestamp-synchronized subtitle rendering.

Supports SRT and WebVTT formats. Subtitles are rendered as GPU overlays
synchronized with the media clock.

Architecture:
    Subtitle File → Parser → Cue Timeline → Clock Sync → GPU Overlay

## Example

    {:ok, sub} = Dala.Media.Subtitle.load("subtitles.srt")

    # In your screen's handle_info:
    def handle_info({:clock, :tick, %{timestamp_us: ts}}, socket) do
      case Dala.Media.Subtitle.active_cue(sub, ts) do
        nil -> {:noreply, socket}
        cue -> {:noreply, render_subtitle(socket, cue)}
      end
    end

# `cue`

```elixir
@type cue() :: %{
  id: non_neg_integer(),
  start_ms: non_neg_integer(),
  end_ms: non_neg_integer(),
  text: String.t(),
  style: map()
}
```

# `parse_result`

```elixir
@type parse_result() :: {:ok, [cue()]} | {:error, term()}
```

# `active_cue`

```elixir
@spec active_cue([cue()], non_neg_integer()) :: cue() | nil
```

Find the active cue for a given timestamp (in microseconds).

# `cues_in_range`

```elixir
@spec cues_in_range([cue()], non_neg_integer(), non_neg_integer()) :: [cue()]
```

Get all cues that fall within a time range.

# `parse_srt`

```elixir
@spec parse_srt(String.t()) :: parse_result()
```

Parse SRT content into a list of cues.

# `parse_vtt`

```elixir
@spec parse_vtt(String.t()) :: parse_result()
```

Parse WebVTT content into a list of cues.

# `to_overlay`

```elixir
@spec to_overlay(
  cue(),
  keyword()
) :: map()
```

Format a cue for GPU overlay rendering.

---

*Consult [api-reference.md](api-reference.md) for complete listing*