# `GoSaveTool.Subtitles`

SRT and WebVTT: read cues, write them in either format, shift and repair timings. The Elixir version of
`@gosavetool/subtitles`.

Online editor: https://www.gosavetool.com/vtt-subtitle-generator

    iex> GoSaveTool.Subtitles.convert("1\n00:00:01,000 --> 00:00:02,500\nHello\n", :vtt)
    "WEBVTT\n\n00:00:01.000 --> 00:00:02.500\nHello\n"

# `convert`

```elixir
@spec convert(String.t(), :srt | :vtt) :: String.t()
```

Converts a subtitle text to `:srt` or `:vtt`.

# `from_ms`

```elixir
@spec from_ms(number(), String.t()) :: String.t()
```

Milliseconds to `"00:01:02,500"` (separator `","`, SRT) or `"00:01:02.500"` (separator `"."`, WebVTT).

    iex> GoSaveTool.Subtitles.from_ms(3723004)
    "01:02:03,004"

# `parse`

```elixir
@spec parse(String.t()) :: [GoSaveTool.Subtitles.Cue.t()]
```

Cues of an SRT or WebVTT text. Headers, NOTE and STYLE blocks are skipped.

# `repair`

```elixir
@spec repair([GoSaveTool.Subtitles.Cue.t()], non_neg_integer()) ::
  {[GoSaveTool.Subtitles.Cue.t()], non_neg_integer()}
```

Repairs common faults: cues out of order, an end before its start, overlapping cues and empty cues.
Returns `{cues, number_of_changes}`. Cues that end before they start get `min_duration` milliseconds.

# `shift`

```elixir
@spec shift([GoSaveTool.Subtitles.Cue.t()], integer()) :: [
  GoSaveTool.Subtitles.Cue.t()
]
```

Moves every cue by `ms` (negative = earlier); cues pushed before zero are clipped or dropped.

# `to_ms`

```elixir
@spec to_ms(String.t()) :: non_neg_integer() | nil
```

`"00:01:02,500"` or `"01:02.5"` to milliseconds; `nil` when it is not a timestamp.

    iex> GoSaveTool.Subtitles.to_ms("1:02:03.4")
    3723400

# `to_srt`

```elixir
@spec to_srt([GoSaveTool.Subtitles.Cue.t()]) :: String.t()
```

SRT text, numbered from 1.

# `to_vtt`

```elixir
@spec to_vtt([GoSaveTool.Subtitles.Cue.t()]) :: String.t()
```

WebVTT text; cue settings are kept.

# `vtt?`

```elixir
@spec vtt?(String.t()) :: boolean()
```

True when the text starts with the WEBVTT signature.

---

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