Skip to content

v0.3.0 — Styled captions → TextOverlay

Choose a tag to compare

View all tags
@SteliyanH SteliyanH released this 30 Apr 07:44
· 17 commits to main since this release
v0.3.0
4f74e8a

The biggest leap of the cycle. A parser path that preserves VTT cue settings and inline styling, plus a bridge that maps a styled cue onto kadr v0.8's `TextOverlay` + `textAnimation`. Consumers can now render captions as styled, animated overlays burned into the export — not just `AVMetadataItem` cues for the OS picker.

What's new

import Kadr
import KadrCaptions

let cues = try await Caption.loadStyled(vtt: vttURL)

let video = Video {
    VideoClip(url: footage)
}
.styledCaptions(cues, animation: .fadeIn(duration: 0.3))

try await video.export(to: outputURL)  // captions baked as styled overlays
  • `StyledCaption` value type — text + timeRange + alignment + line + position + bold / italic / underline flags + speaker + classes.
  • `StyledCaptionAlignment` (`.start` / `.center` / `.end`) and `StyledCaptionLine` (`.auto` / `.top` / `.bottom` / `.percent(Double)`).
  • `CaptionParser.parseStyledVTT(_:)` + `Caption.loadStyled(vtt:)` — preserve `align:` / `line:` / `position:` cue settings and inline tags.
  • `StyledCaption.toTextOverlay(baseStyle:animation:)` — bridge to `Kadr.TextOverlay` with per-cue `visibilityRange`.
  • `Video.styledCaptions(_:baseStyle:animation:)` — convenience modifier.

Tag handling

"Any tag of this kind appeared in the cue → per-cue flag set":

  • `` / `` / `` toggle the respective flag.
  • `` extracts the speaker name.
  • `<c.foo.bar>` accumulates classnames.
  • `<00:00:01.500>` timed-text markers stripped.

Bridge mapping

  • Alignment → `TextStyle.Alignment` (`.leading` / `.center` / `.trailing`).
  • Bold → `Weight.bold`. Italic → `fontName = "Helvetica-Oblique"` (documented limitation).
  • Line position → y-coordinate + anchor row; alignment → x-anchor.

Critical contract

The plain-text part of every `StyledCaption` equals what `parseVTT` would produce for the same input. Verified by round-trip test.

Compatibility

Pure additive — every v0.2 composition compiles unchanged. Same platform floor: iOS 16+ / macOS 13+ / tvOS 16+ / visionOS 1+, Swift 6.0.

Tests

Suite: 98 → 155 (+57).

What's next

  • v0.4.0 — ASS / SSA support (Advanced SubStation Alpha)
  • v0.3.x — `<STYLE>`-block parser to apply `<c.classname>` styling

Full notes in CHANGELOG.md.

Assets 2
Loading