expo-video-subtitle 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,78 @@ Changes inherited from the upstream base version are not repeated here — see t
 [upstream changelog](https://github.com/expo/expo/blob/main/packages/expo-video/CHANGELOG.md)
 for the history of everything that isn't subtitle related.
 
+## 0.8.0
+
+### Added
+
+- **ASS signs are drawn with their transforms on iOS too.** AVFoundation renders a sideloaded
+  WebVTT track itself, and WebVTT can express no rotation, no scale and no per-cue opacity;
+  `AVTextStyleRule` has no attribute for any of them either. So the same split the Android side
+  makes: `SubtitleConverter.splitAss` takes the typeset events out of the script before the WebVTT
+  is built, and `AssSignOverlayView` draws them in `AVPlayerViewController.contentOverlayView`,
+  sized to `videoBounds` and driven by a `CADisplayLink`.
+
+  Signs travel on the `AVPlayerItem` that owns them rather than through a store of their own. A
+  store would have to be keyed by something both ends can see, and the only identity a sideloaded
+  track keeps inside a composition is its language — so two players loading different videos in the
+  same language would overwrite each other, and the next episode would inherit the previous one's
+  typesetting. The item is the identity, and the overlay re-resolves whenever the item or the
+  selected language changes.
+
+  Read and honoured: `\pos`, `\move` (at its destination), `\org`, `\an` and the legacy `\a`,
+  `\frz`, `\fscx`, `\fscy`, `\fs`, `\c` / `\1c`, `\alpha` / `\1a`, `\b`, `\i`, `\u`, and the
+  style columns behind them.
+
+### Known limitations on iOS
+
+- `\frx` and `\fry` are not applied. `CGAffineTransform` is two-dimensional, and the values are
+  almost always under 3° in practice; `\frz` is what carries the effect.
+- Signs do not appear in Picture in Picture. The system renders that window from the video layer
+  alone, not from the view hierarchy `contentOverlayView` belongs to.
+- `\t` animation, `\fad`, `\clip`, `\blur`, `\be`, `\fax` shear, vector drawings and karaoke are
+  dropped, as on Android. Fonts fall back to the system face.
+
+### Fixed
+
+- **Non-finite numbers are refused.** `Double("nan")` and `Double("inf")` parse, and a subtitle is
+  untrusted scraper output; either one reaching a transform makes a sign silently fail to draw,
+  which looks exactly like a sign that was never parsed. Every number out of a tag or a style column
+  now goes through a finiteness check.
+
+### Changed
+
+- The override-block scanner reads a leading digit as part of a tag name, so `\1c`, `\1a` and `\4a`
+  are recognised. The WebVTT path ignores them as before — 91 existing checks confirm its output is
+  unchanged — but the sign path needs them.
+- The Swift harness is at 119 checks, up from 91.
+
+## 0.7.6
+
+### Fixed
+
+- **Signs stopped appearing at all.** The id lookup between the parser and the overlay had never
+  matched. Media3 prefixes a merged track's id with the index of the source it came from, so the
+  parser is handed `expo-subtitle:id:https://…` while the overlay reads
+  `2:expo-subtitle:id:https://…` off the selected track. Every lookup missed, and the
+  "use the only script on hand" fallback quietly covered for it — which is why removing that
+  fallback in 0.7.5 took the whole feature with it, and why the fallback's own bug (one episode's
+  signs drawing over the next) had been the only visible symptom until then.
+
+  Both ends now normalize the id through the same function before touching the map. Five tests pin
+  it, using the exact strings a device produced, and were checked by removing the normalization and
+  watching them fail.
+
+- **A track with no typesetting no longer logs once a second forever.** The parser files its result
+  even when there are no signs in it. Absence in the store used to mean two different things —
+  "still parsing" and "nothing to draw" — and the overlay kept asking for the second one.
+
+### Changed
+
+- A missed lookup is now logged, throttled to once a second, naming both the id being asked for and
+  the ids on hand. Its absence is what let this bug hide behind a fallback for three releases: the
+  overlay asked, got nothing, and said nothing, so a wrong key looked exactly like a file that had
+  not finished parsing.
+
 ## 0.7.5
 
 ### Fixed

package/android/src/main/java/expo/modules/video/utils/AssSignOverlay.kt

@@ -109,7 +109,18 @@ internal class AssSignOverlay(context: Context) : View(context), Player.Listener
     val trackId = selectedTextTrackId()
     val next = AssSignStore.get(trackId)
     scriptTrackId = trackId
-    if (next === script) return
+    if (next === script) {
+      // Reported, not swallowed. A lookup that quietly finds nothing is how this subsystem has
+      // failed three times running: the overlay asks, gets nothing, and says nothing, so the log
+      // looks identical whether the file is still parsing or the key is simply wrong. Throttled to
+      // once a second because the poll runs four times that.
+      val now = SystemClock.uptimeMillis()
+      if (now - lastMissLogMs >= MISS_LOG_INTERVAL_MS) {
+        lastMissLogMs = now
+        Log.w(TAG, "no ASS signs for track $trackId; parsed so far: ${AssSignStore.keys()}")
+      }
+      return
+    }
     // The one line worth keeping. Every failure of this subsystem has been silent — a span dropped
     // by Parcel, a timestamp rejected, a loop that never started — and each time this line would
     // have named the stage that broke.
@@ -169,6 +180,7 @@ internal class AssSignOverlay(context: Context) : View(context), Player.Listener
 
 
   private var lastLookupMs = 0L
+  private var lastMissLogMs = 0L
 
   private fun tick() {
     val player = this.player ?: return
@@ -367,6 +379,9 @@ internal class AssSignOverlay(context: Context) : View(context), Player.Listener
 
     /** How often to ask the store for a script that has not arrived yet. */
     private const val LOOKUP_INTERVAL_MS = 250L
+
+    /** How often to say so when the answer is still nothing. */
+    private const val MISS_LOG_INTERVAL_MS = 1000L
     private const val OPAQUE = 0xFF000000.toInt()
 
     /** Removes the overlay from [playerView], dropping its listener registration with it. */

package/android/src/main/java/expo/modules/video/utils/AssSignStore.kt

@@ -41,10 +41,27 @@ internal object AssSignStore {
       size > MAX_TRACKS
   }
 
+  /**
+   * A merged track's id carries the index of the source it came from: Media3 hands the overlay
+   * `2:expo-subtitle:id:https://…` for the track the parser was given as `expo-subtitle:id:https://…`.
+   * Both ends key on the same string only if that prefix is taken off first.
+   *
+   * Measured on a device, and it is what made every id lookup miss while a fallback quietly covered
+   * for it. Stripped repeatedly, since sources can nest, and safe for these ids because
+   * `SubtitleSource` always begins them with `expo-subtitle:`, never a digit.
+   */
+  private val MERGED_SOURCE_PREFIX = Regex("""^\d+:""")
+
+  fun normalizeTrackId(trackId: String): String {
+    var id = trackId
+    while (MERGED_SOURCE_PREFIX.containsMatchIn(id)) id = id.replaceFirst(MERGED_SOURCE_PREFIX, "")
+    return id
+  }
+
   /** Called from the extractor's loading thread. */
   @Synchronized
   fun put(trackId: String, script: AssScript) {
-    scripts[trackId] = script
+    scripts[normalizeTrackId(trackId)] = script
   }
 
   /**
@@ -61,7 +78,11 @@ internal object AssSignStore {
    * script takes about twelve seconds, and the overlay polls until it has.
    */
   @Synchronized
-  fun get(trackId: String?): AssScript? = trackId?.let { scripts[it] }
+  fun get(trackId: String?): AssScript? = trackId?.let { scripts[normalizeTrackId(it)] }
+
+  /** The keys on hand, for telling a "not parsed yet" miss from a "wrong key" miss. */
+  @Synchronized
+  fun keys(): List<String> = scripts.keys.toList()
 
   @Synchronized
   fun clear() {

package/android/src/main/java/expo/modules/video/utils/StackingSubtitleParser.kt

@@ -342,10 +342,13 @@ class StackingSsaParser(
       if (trackId == null) return@runCatching Split(data, offset, length)
 
       val script = AssSignParser.parse(String(data, offset, length, Charsets.UTF_8))
+      // Filed even with no signs in it. The overlay cannot tell "still parsing" from "nothing to
+      // draw" by absence alone, and would go on asking — and logging — for the whole episode.
+      AssSignStore.put(trackId, script)
+
       if (script.signs.isEmpty()) {
         Split(data, offset, length)
       } else {
-        AssSignStore.put(trackId, script)
         val dialogue = script.dialogueOnly.toByteArray(Charsets.UTF_8)
         Split(dialogue, 0, dialogue.size)
       }

package/ios/AssSign.swift

@@ -0,0 +1,264 @@
+import Foundation
+
+/// One typeset event, in script coordinates. `AssSignOverlayView` maps it onto the video rect.
+///
+/// The Android side has the same shape, field for field, and for the same reason: this is what a
+/// renderer needs to put a sign on a placard, and AVFoundation can carry almost none of it.
+struct AssSign: Equatable {
+  let startMs: Int
+  let endMs: Int
+  let text: String
+
+  let x: Double
+  let y: Double
+  let alignment: Int
+
+  /// Clockwise, having already been flipped from ASS's counter-clockwise measure.
+  let rotationZ: Double
+  let rotationX: Double
+  let rotationY: Double
+  let pivotX: Double
+  let pivotY: Double
+
+  let scaleX: Double
+  let scaleY: Double
+  let fontSize: Double
+  let colour: Int
+  let alpha: Double
+  let outlineColour: Int
+  let outlineWidth: Double
+  let bold: Bool
+  let italic: Bool
+  let underline: Bool
+
+  /// The coordinate space the values above are expressed in.
+  let playResX: Double
+  let playResY: Double
+}
+
+extension AssSign {
+  /// `AVMediaSelectionOption` reports a full locale identifier (`id_ID`, `pt-BR`) where the track was
+  /// given a bare language tag. Comparing the language subtag is what makes the two ends meet.
+  static func normalizeLanguage(_ language: String) -> String {
+    let lowered = language.lowercased()
+    if let cut = lowered.firstIndex(where: { $0 == "-" || $0 == "_" }) {
+      return String(lowered[lowered.startIndex..<cut])
+    }
+    return lowered
+  }
+}
+
+/// A script split into the part this package draws and the part AVFoundation draws.
+struct AssSplit {
+  /// Typeset events, drawn by `AssSignOverlayView`.
+  let signs: [AssSign]
+  /// The script with every sign, drawing and invisible event cut out, for the WebVTT converter.
+  let dialogueOnly: String
+}
+
+extension SubtitleConverter {
+
+  /// Takes the typesetting out of a script and hands back what is left.
+  ///
+  /// ### Why signs cannot go through WebVTT
+  ///
+  /// AVFoundation renders a `.text` track itself, and WebVTT has no rotation, no scale and no
+  /// per-cue opacity to express. `AVTextStyleRule` has no attribute for any of it either. A sign
+  /// tilted to lie on a placard comes out flat, which reads as pasted over the picture rather than
+  /// part of it — in one episode of Jujutsu Kaisen S3, 3,723 events carry `\frz`, 1,304 of them past
+  /// 5°.
+  ///
+  /// So the same split the Android side makes: typeset events to us, dialogue to the platform, and
+  /// the sign lines removed from the copy the platform parses. There is no matching step to get
+  /// wrong, because an event is in exactly one of the two outputs.
+  ///
+  /// ### What counts as a sign
+  ///
+  /// Anything the author placed: an event carrying `\pos` or `\move`, or whose effective alignment
+  /// is not bottom-centre. The complement is dialogue, and AVFoundation is welcome to it.
+  static func splitAss(_ ass: String) -> AssSplit {
+    let normalized = normalizeNewlines(ass)
+    let script = AssScript(parsing: normalized)
+    let lines = normalized.components(separatedBy: "\n")
+
+    var signs: [AssSign] = []
+    var removed = Set<Int>()
+
+    for event in script.events {
+      guard event.endMs > event.startMs else { continue }
+      let style = script.styles[event.styleName]
+
+      // A style that draws nothing is where a typesetter parks working notes. Neither renderer
+      // should show it, and the WebVTT converter drops it too — cut here so both agree.
+      if style?.invisible == true {
+        removed.insert(event.lineIndex)
+        continue
+      }
+
+      guard let sign = buildSign(event: event, style: style, script: script) else { continue }
+
+      switch sign {
+      case .drop:
+        removed.insert(event.lineIndex)
+      case .sign(let value):
+        signs.append(value)
+        removed.insert(event.lineIndex)
+      case .dialogue:
+        break
+      }
+    }
+
+    let dialogueOnly = removed.isEmpty
+      ? normalized
+      : lines.enumerated().filter { !removed.contains($0.offset) }.map(\.element).joined(separator: "\n")
+
+    return AssSplit(signs: signs, dialogueOnly: dialogueOnly)
+  }
+
+  private enum SignResolution {
+    case sign(AssSign)
+    case dialogue
+    case drop
+  }
+
+  private static func buildSign(
+    event: AssScript.Event,
+    style: AssScript.Style?,
+    script: AssScript
+  ) -> SignResolution? {
+    var alignment: Int = style?.alignment ?? 2
+    var position: (x: Double, y: Double)?
+    var origin: (x: Double, y: Double)?
+    var rotationZ: Double = style?.angle ?? 0
+    var rotationX: Double = 0
+    var rotationY: Double = 0
+    var scaleX: Double = style?.scaleX ?? 1
+    var scaleY: Double = style?.scaleY ?? 1
+    var fontSize: Double = style?.fontSize ?? 48
+    var colour: Int = style?.colour ?? 0xFFFFFF
+    var alpha: Double = style?.alpha ?? 1
+    var bold: Bool = style?.bold ?? false
+    var italic: Bool = style?.italic ?? false
+    var underline: Bool = style?.underline ?? false
+    var isDrawing = false
+
+    for block in overrideBlocks(in: event.text) {
+      for tag in parseOverrideBlock(block) {
+        switch tag {
+        case .alignment(let value): alignment = value
+        case .position(let x, let y): position = (x, y)
+        case .origin(let x, let y): origin = (x, y)
+        case .rotationZ(let value): rotationZ = value
+        case .rotationX(let value): rotationX = value
+        case .rotationY(let value): rotationY = value
+        case .scaleX(let value): scaleX = value
+        case .scaleY(let value): scaleY = value
+        case .fontSize(let value): fontSize = value
+        case .primaryColour(let value): colour = value
+        case .primaryAlpha(let value): alpha = value
+        case .bold(let on): bold = on
+        case .italic(let on): italic = on
+        case .underline(let on): underline = on
+        case .drawing: isDrawing = true
+        case .reset: break
+        }
+      }
+    }
+
+    if isDrawing { return .drop }
+
+    let text = strippedText(event.text)
+    if text.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines).isEmpty { return .drop }
+
+    // The complement of what AVFoundation lays out at the bottom by itself.
+    guard position != nil || alignment != 2 else { return .dialogue }
+
+    // Style margins only. A per-event margin override would need the Event to carry one, and it
+    // only ever matters for a sign with no `\pos` at all — which in a typeset script is close to
+    // none of them. Media3 ignores per-event margins outright, so both platforms agree here.
+    let marginL: Double = style?.marginL ?? 0
+    let marginR: Double = style?.marginR ?? 0
+    let marginV: Double = style?.marginV ?? 0
+
+    let x: Double = position?.x ?? {
+      switch (alignment - 1) % 3 {
+      case 0: return marginL
+      case 2: return script.playResX - marginR
+      default: return script.playResX / 2
+      }
+    }()
+    let y: Double = position?.y ?? {
+      switch (alignment - 1) / 3 {
+      case 0: return script.playResY - marginV
+      case 2: return marginV
+      default: return script.playResY / 2
+      }
+    }()
+
+    return .sign(AssSign(
+      startMs: event.startMs,
+      endMs: event.endMs,
+      text: text,
+      x: x,
+      y: y,
+      alignment: alignment,
+      // ASS measures counter-clockwise; every renderer here turns clockwise.
+      rotationZ: -rotationZ,
+      rotationX: rotationX,
+      rotationY: -rotationY,
+      pivotX: origin?.x ?? x,
+      pivotY: origin?.y ?? y,
+      scaleX: scaleX,
+      scaleY: scaleY,
+      fontSize: fontSize,
+      colour: colour,
+      alpha: alpha,
+      outlineColour: style?.outlineColour ?? 0x000000,
+      outlineWidth: style?.outlineWidth ?? 0,
+      bold: bold,
+      italic: italic,
+      underline: underline,
+      playResX: script.playResX,
+      playResY: script.playResY
+    ))
+  }
+
+  /// The contents of every `{...}` block, in order.
+  private static func overrideBlocks(in text: String) -> [String] {
+    var blocks: [String] = []
+    let chars = Array(text)
+    var i = 0
+    while i < chars.count {
+      guard chars[i] == "{" else { i += 1; continue }
+      guard let close = chars[(i + 1)...].firstIndex(of: "}") else { break }
+      blocks.append(String(chars[(i + 1)..<close]))
+      i = close + 1
+    }
+    return blocks
+  }
+
+  /// Override blocks out, ASS escapes in.
+  private static func strippedText(_ raw: String) -> String {
+    var out = ""
+    let chars = Array(raw)
+    var i = 0
+    while i < chars.count {
+      if chars[i] == "{", let close = chars[(i + 1)...].firstIndex(of: "}") {
+        i = close + 1
+        continue
+      }
+      if chars[i] == "\\", i + 1 < chars.count {
+        switch chars[i + 1] {
+        case "N", "n": out.append("\n"); i += 2; continue
+        // A hard space: U+00A0, not U+0020. A plain space would let the layout break the line
+        // exactly where the typesetter wrote the escape to stop it doing so.
+        case "h": out.append("\u{00A0}"); i += 2; continue
+        default: break
+        }
+      }
+      out.append(chars[i])
+      i += 1
+    }
+    return out
+  }
+}

package/ios/AssSignOverlayView.swift

@@ -0,0 +1,302 @@
+import AVKit
+import ExpoModulesCore
+import UIKit
+
+/// Draws ASS typesetting — signs, placards, on-screen labels — with the transforms the script asks
+/// for.
+///
+/// AVFoundation cannot: it renders a `.text` track itself, WebVTT can express no rotation, scale or
+/// per-cue opacity, and `AVTextStyleRule` has no attribute for any of them. So `SubtitleConverter`
+/// takes those events out of the WebVTT it builds and leaves them in `AssSignStore`, and this view
+/// draws them.
+///
+/// ### Where it sits
+///
+/// In `AVPlayerViewController.contentOverlayView`, which is the frame Apple provides between the
+/// video and the transport controls. Sized to `videoBounds` on every frame, so `\pos` — which is in
+/// `PlayResX`/`PlayResY` space — maps onto the picture rather than onto the player, and survives
+/// letterboxing and rotation without any arithmetic of its own.
+///
+/// ### Why it drives itself from the clock
+///
+/// Signs do not ride the subtitle track, so nothing announces when one starts. It reads the player's
+/// time on each frame instead, which is also the only granularity that works: frame-by-frame
+/// typesetting writes one event per frame, and a sign on screen for 40 ms has to arrive and leave on
+/// the frame it was authored for.
+final class AssSignOverlayView: UIView {
+
+  private weak var playerViewController: AVPlayerViewController?
+  private var displayLink: CADisplayLink?
+
+  private var signs: [AssSign] = []
+  private var active: [AssSign] = []
+  /// What `signs` was resolved from. Both halves matter: the item changes when the next episode
+  /// loads, the language when the viewer switches track.
+  private var resolvedItem: ObjectIdentifier?
+  private var resolvedLanguage: String?
+  private var lastLookup: CFTimeInterval = 0
+
+  /// Rebuilt only when the on-screen set changes, not per frame.
+  private var rendered: [RenderedSign] = []
+
+  private struct RenderedSign {
+    let text: NSAttributedString
+    let size: CGSize
+    let origin: CGPoint
+    let transform: CGAffineTransform
+  }
+
+  // MARK: - Lifecycle
+
+  init(playerViewController: AVPlayerViewController) {
+    self.playerViewController = playerViewController
+    super.init(frame: .zero)
+    isUserInteractionEnabled = false
+    backgroundColor = .clear
+    contentMode = .redraw
+  }
+
+  @available(*, unavailable)
+  required init?(coder: NSCoder) {
+    fatalError("init(coder:) is not used")
+  }
+
+  /// Adds the overlay to the controller's content overlay, or returns the one already there.
+  @discardableResult
+  static func install(in controller: AVPlayerViewController) -> AssSignOverlayView? {
+    guard let host = controller.contentOverlayView else { return nil }
+
+    for subview in host.subviews {
+      if let existing = subview as? AssSignOverlayView { return existing }
+    }
+
+    let overlay = AssSignOverlayView(playerViewController: controller)
+    host.addSubview(overlay)
+    overlay.start()
+    return overlay
+  }
+
+  static func remove(from controller: AVPlayerViewController) {
+    guard let host = controller.contentOverlayView else { return }
+    for subview in host.subviews {
+      guard let overlay = subview as? AssSignOverlayView else { continue }
+      overlay.stop()
+      overlay.removeFromSuperview()
+    }
+  }
+
+  private func start() {
+    guard displayLink == nil else { return }
+    let link = CADisplayLink(target: self, selector: #selector(tick))
+    link.add(to: .main, forMode: .common)
+    displayLink = link
+  }
+
+  private func stop() {
+    displayLink?.invalidate()
+    displayLink = nil
+    clearResolved()
+  }
+
+  override func willMove(toWindow newWindow: UIWindow?) {
+    super.willMove(toWindow: newWindow)
+    if newWindow == nil {
+      displayLink?.invalidate()
+      displayLink = nil
+    } else {
+      start()
+    }
+  }
+
+  // MARK: - The clock
+
+  @objc private func tick() {
+    guard let controller = playerViewController, let player = controller.player else { return }
+
+    // The picture moves under us: rotation, full screen, and a letterbox that changes with the
+    // video's own aspect all land here rather than in any positioning arithmetic.
+    let bounds = controller.videoBounds
+    if bounds != frame, bounds.width > 0, bounds.height > 0 {
+      frame = bounds
+      // Every measurement in `prepare` is in view pixels, so all of it is stale after a resize.
+      rendered = []
+      setNeedsDisplay()
+    }
+
+    // Re-resolved on a timer rather than only when empty. Gating on "no signs yet" is the same
+    // mistake twice: it never fires again once a video with typesetting has loaded, so the next
+    // episode inherits the previous one's signs and matches them against its own timeline. The
+    // Android side shipped exactly that and it took two releases to unpick.
+    let now = CACurrentMediaTime()
+    if now - lastLookup >= AssSignOverlayView.lookupInterval {
+      lastLookup = now
+      resolveSigns(for: player)
+    }
+    if signs.isEmpty { return }
+
+    let positionMs = Int(CMTimeGetSeconds(player.currentTime()) * 1000)
+    setActive(signs.filter { positionMs >= $0.startMs && positionMs < $0.endMs })
+  }
+
+  private func resolveSigns(for player: AVPlayer) {
+    guard let item = player.currentItem else {
+      if resolvedItem != nil { clearResolved() }
+      return
+    }
+
+    let identity = ObjectIdentifier(item)
+    let language = selectedSubtitleLanguage(of: item)
+    guard identity != resolvedItem || language != resolvedLanguage else { return }
+
+    resolvedItem = identity
+    resolvedLanguage = language
+
+    // Typesetting rides on the item that owns it, so there is no key to mismatch and no store to go
+    // stale: a different item simply has different signs.
+    let found = (item as? VideoPlayerItem)
+      .flatMap { playerItem in language.map { playerItem.assSigns[AssSign.normalizeLanguage($0)] } }
+      ?? nil
+
+    signs = found ?? []
+    rendered = []
+    setActive([])
+    log.info("[expo-video] ASS signs for \(language ?? "nil"): \(signs.count)")
+  }
+
+  private func clearResolved() {
+    resolvedItem = nil
+    resolvedLanguage = nil
+    signs = []
+    rendered = []
+    setActive([])
+  }
+
+  /// The locale of the selected legible option, which is the only identity a sideloaded track keeps
+  /// once it is inside the composition.
+  private func selectedSubtitleLanguage(of item: AVPlayerItem) -> String? {
+    guard let group = item.asset.mediaSelectionGroup(forMediaCharacteristic: .legible),
+          let option = item.currentMediaSelection.selectedMediaOption(in: group) else {
+      return nil
+    }
+    return option.locale?.identifier ?? option.extendedLanguageTag
+  }
+
+  private func setActive(_ next: [AssSign]) {
+    // Value equality across the whole sign, not a (time, text) stand-in: two events can share both
+    // and differ in where they sit, which is the case a frame-by-frame animation is made of.
+    guard next != active else { return }
+    active = next
+    rendered = []
+    setNeedsDisplay()
+  }
+
+  // MARK: - Drawing
+
+  override func draw(_ rect: CGRect) {
+    guard let context = UIGraphicsGetCurrentContext(), bounds.width > 0, bounds.height > 0 else { return }
+
+    if rendered.isEmpty && !active.isEmpty {
+      rendered = active.compactMap(prepare)
+    }
+
+    for sign in rendered {
+      context.saveGState()
+      context.concatenate(sign.transform)
+      sign.text.draw(at: sign.origin)
+      context.restoreGState()
+    }
+  }
+
+  private func prepare(_ sign: AssSign) -> RenderedSign? {
+    let alpha = max(0, min(1, sign.alpha))
+    if alpha == 0 { return nil }
+
+    // Script space to view space. Both axes scale independently, so a script authored at a different
+    // aspect ratio than the video still lands where it was drawn.
+    let scaleToViewX = bounds.width / CGFloat(sign.playResX)
+    let scaleToViewY = bounds.height / CGFloat(sign.playResY)
+
+    let attributed = attributedText(for: sign, scaleToViewY: scaleToViewY, alpha: alpha)
+    let size = attributed.boundingRect(
+      with: CGSize(width: CGFloat.greatestFiniteMagnitude, height: CGFloat.greatestFiniteMagnitude),
+      options: [.usesLineFragmentOrigin, .usesFontLeading],
+      context: nil
+    ).size
+
+    let anchorX = CGFloat(sign.x) * scaleToViewX
+    let anchorY = CGFloat(sign.y) * scaleToViewY
+    // \pos names the point the cue's alignment corner sits on, so the box is offset from it.
+    let left: CGFloat
+    switch (sign.alignment - 1) % 3 {
+    case 0: left = anchorX
+    case 2: left = anchorX - size.width
+    default: left = anchorX - size.width / 2
+    }
+    let top: CGFloat
+    switch (sign.alignment - 1) / 3 {
+    case 0: top = anchorY - size.height
+    case 2: top = anchorY
+    default: top = anchorY - size.height / 2
+    }
+
+    // \org moves the centre of rotation away from the text, which is how a sign stays glued to a
+    // placard pivoting off-screen. Without it every rotation would spin about the text's own middle.
+    let pivotX = CGFloat(sign.pivotX) * scaleToViewX
+    let pivotY = CGFloat(sign.pivotY) * scaleToViewY
+
+    // Scale first, then turn — ASS scales the glyph and then rotates it, and with an anisotropic
+    // scale the two do not commute. `concatenating` applies the receiver first, so the order reads
+    // in the order it happens.
+    let transform = CGAffineTransform(translationX: -pivotX, y: -pivotY)
+      .concatenating(CGAffineTransform(scaleX: CGFloat(sign.scaleX), y: CGFloat(sign.scaleY)))
+      .concatenating(CGAffineTransform(rotationAngle: CGFloat(sign.rotationZ) * .pi / 180))
+      .concatenating(CGAffineTransform(translationX: pivotX, y: pivotY))
+
+    return RenderedSign(text: attributed, size: size, origin: CGPoint(x: left, y: top), transform: transform)
+  }
+
+  private func attributedText(for sign: AssSign, scaleToViewY: CGFloat, alpha: Double) -> NSAttributedString {
+    let pointSize = max(1, CGFloat(sign.fontSize) * scaleToViewY)
+    var font = UIFont.systemFont(ofSize: pointSize, weight: sign.bold ? .bold : .regular)
+    if sign.italic, let descriptor = font.fontDescriptor.withSymbolicTraits(.traitItalic) {
+      font = UIFont(descriptor: descriptor, size: pointSize)
+    }
+
+    let paragraph = NSMutableParagraphStyle()
+    switch (sign.alignment - 1) % 3 {
+    case 0: paragraph.alignment = .left
+    case 2: paragraph.alignment = .right
+    default: paragraph.alignment = .center
+    }
+
+    var attributes: [NSAttributedString.Key: Any] = [
+      .font: font,
+      .foregroundColor: colour(sign.colour, alpha: alpha),
+      .paragraphStyle: paragraph
+    ]
+    if sign.underline {
+      attributes[.underlineStyle] = NSUnderlineStyle.single.rawValue
+    }
+    if sign.outlineWidth > 0 {
+      attributes[.strokeColor] = colour(sign.outlineColour, alpha: alpha)
+      // Negative means stroke *and* fill. A positive width would draw the outline only, leaving the
+      // letters hollow.
+      attributes[.strokeWidth] = -sign.outlineWidth * 2
+    }
+
+    return NSAttributedString(string: sign.text, attributes: attributes)
+  }
+
+  /// ASS colours carry no alpha byte; opacity travels separately.
+  private func colour(_ rgb: Int, alpha: Double) -> UIColor {
+    UIColor(
+      red: CGFloat((rgb >> 16) & 0xFF) / 255,
+      green: CGFloat((rgb >> 8) & 0xFF) / 255,
+      blue: CGFloat(rgb & 0xFF) / 255,
+      alpha: CGFloat(alpha)
+    )
+  }
+
+  /// How often to ask the store for signs that have not been parsed yet.
+  private static let lookupInterval: CFTimeInterval = 0.25
+}

package/ios/SubtitleConverterText.swift

@@ -285,12 +285,14 @@ internal struct RenderedSubtitleText {
   var isDrawing: Bool
 }
 
-private enum InlineToken {
+internal enum InlineToken {
   case text(String)
   case markup(String)
 }
 
-private extension SubtitleConverter {
+// Internal rather than private: `AssSign.swift` reuses the override-block scanner and the colour
+// parser, and reimplementing either would be two copies that have to agree about ASS forever.
+internal extension SubtitleConverter {
   /// Escapes only the parts of a cue that came from the source text.
   ///
   /// Order matters: `&` first, then `<`, then `>`. Escaping `&` last would double-escape the one in
@@ -370,6 +372,9 @@ private extension SubtitleConverter {
           case .underline(let on): on ? openTag("u") : closeTag("u")
           case .drawing: isDrawing = true
           case .reset: closeAll()
+          // The transform tags are for signs, which never reach this converter — a sign is taken
+          // out of the script before the WebVTT is built, because WebVTT can express none of them.
+          default: break
           }
         }
         i = end + 1
@@ -479,6 +484,50 @@ private extension SubtitleConverter {
     case underline(Bool)
     case drawing
     case reset
+    // Read for signs only. The WebVTT path ignores every one of them, because WebVTT can express
+    // none of it — which is the whole reason signs are drawn separately.
+    case origin(Double, Double)
+    case rotationZ(Double)
+    case rotationX(Double)
+    case rotationY(Double)
+    case scaleX(Double)
+    case scaleY(Double)
+    case fontSize(Double)
+    case primaryColour(Int)
+    case primaryAlpha(Double)
+    case bold(Bool)
+  }
+
+  struct AssColour {
+    let rgb: Int
+    let alpha: Double
+  }
+
+  /// `&HAABBGGRR&` or `&HBBGGRR&`, with or without the ampersands.
+  ///
+  /// The bytes are reversed against RGB and the alpha byte is inverted — `FF` is fully transparent.
+  /// A six-digit value carries no alpha byte and is therefore opaque.
+  static func parseAssColour(_ value: String, alphaOnly: Bool = false) -> AssColour? {
+    var text = value.trimmingCharacters(in: .whitespaces)
+    if text.hasSuffix("&") { text = String(text.dropLast()) }
+    if text.lowercased().hasPrefix("&h") { text = String(text.dropFirst(2)) }
+    guard !text.isEmpty, let hex = UInt32(text, radix: 16) else { return nil }
+
+    if alphaOnly || text.count <= 2 {
+      return AssColour(rgb: 0xFFFFFF, alpha: 1 - Double(hex & 0xFF) / 255)
+    }
+
+    let red: UInt32 = hex & 0xFF
+    let green: UInt32 = (hex >> 8) & 0xFF
+    let blue: UInt32 = (hex >> 16) & 0xFF
+    let rgb: Int = Int(red) << 16 | Int(green) << 8 | Int(blue)
+
+    var alpha: Double = 1
+    if text.count > 6 {
+      let transparency: UInt32 = (hex >> 24) & 0xFF
+      alpha = 1 - Double(transparency) / 255
+    }
+    return AssColour(rgb: rgb, alpha: alpha)
   }
 
   /// Scans one `{...}` block left to right.
@@ -487,6 +536,14 @@ private extension SubtitleConverter {
   /// one pass and the `\i1` keeps its position within the text. Reading the tag name as a run of
   /// letters is also what makes the longest-match problem disappear: `\c` cannot eat `\clip` and
   /// `\b` cannot eat `\bord`, because those parse as the names "clip" and "bord".
+  /// A number, or nothing. `Double` parses "nan" and "inf", and neither belongs in a transform.
+  static func finite(_ text: String) -> Double? {
+    guard let value = Double(text.trimmingCharacters(in: CharacterSet.whitespaces)), value.isFinite else {
+      return nil
+    }
+    return value
+  }
+
   static func parseOverrideBlock(_ block: String) -> [OverrideTag] {
     var tags: [OverrideTag] = []
     let chars = Array(block)
@@ -497,6 +554,10 @@ private extension SubtitleConverter {
       i += 1
 
       var name = ""
+      // A leading digit belongs to the name: \1c, \1a and \4a all start with one. Reading only
+      // letters left those as the empty name, which was harmless while colour was being dropped and
+      // is not once signs need it.
+      while i < chars.count, chars[i].isNumber { name.append(chars[i]); i += 1 }
       while i < chars.count, chars[i].isLetter { name.append(chars[i]); i += 1 }
 
       var argument = ""
@@ -526,9 +587,7 @@ private extension SubtitleConverter {
           tags.append(.alignment(value))
         }
       case "pos":
-        let parts = argument.split(separator: ",").map {
-          Double($0.trimmingCharacters(in: .whitespaces)) ?? 0
-        }
+        let parts = argument.split(separator: ",").compactMap { finite(String($0)) }
         if parts.count >= 2 { tags.append(.position(parts[0], parts[1])) }
       case "i": tags.append(.italic(argument.trimmingCharacters(in: .whitespaces) == "1"))
       case "u": tags.append(.underline(argument.trimmingCharacters(in: .whitespaces) == "1"))
@@ -539,6 +598,34 @@ private extension SubtitleConverter {
           tags.append(.drawing)
         }
       case "r": tags.append(.reset)
+      case "move":
+        // A move ends where it ends; drawing it at the destination beats drawing it at the start.
+        let parts = argument.split(separator: ",").compactMap { finite(String($0)) }
+        if parts.count >= 4 { tags.append(.position(parts[2], parts[3])) }
+      case "org":
+        let parts = argument.split(separator: ",").compactMap { finite(String($0)) }
+        if parts.count >= 2 { tags.append(.origin(parts[0], parts[1])) }
+      // `Double("nan")` and `Double("inf")` parse. A subtitle is untrusted scraper output, and a
+      // non-finite value carried into a transform makes the sign silently fail to draw — so every
+      // number here goes through `finite`.
+      case "frz", "fr":
+        if let value = finite(argument) { tags.append(.rotationZ(value)) }
+      case "frx":
+        if let value = finite(argument) { tags.append(.rotationX(value)) }
+      case "fry":
+        if let value = finite(argument) { tags.append(.rotationY(value)) }
+      case "fscx":
+        if let value = finite(argument) { tags.append(.scaleX(value / 100)) }
+      case "fscy":
+        if let value = finite(argument) { tags.append(.scaleY(value / 100)) }
+      case "fs":
+        if let value = finite(argument), value > 0 { tags.append(.fontSize(value)) }
+      case "c", "1c":
+        if let colour = parseAssColour(argument) { tags.append(.primaryColour(colour.rgb)) }
+      case "alpha", "1a":
+        if let colour = parseAssColour(argument, alphaOnly: true) { tags.append(.primaryAlpha(colour.alpha)) }
+      case "b":
+        tags.append(.bold(argument.trimmingCharacters(in: .whitespaces) != "0"))
       default: break
       }
     }
@@ -610,16 +697,35 @@ private extension SubtitleConverter {
 /// Header fields are read from their own `Format:` lines rather than assumed, because encoders
 /// reorder them and reading the Text column one position off produces a file that still parses and
 /// is entirely wrong.
-private struct AssScript {
+internal struct AssScript {
   struct Style {
+
     var alignment: Int
     var italic: Bool
     var underline: Bool
     /// The author asked for this style to draw nothing. See `isInvisibleStyle`.
     var invisible: Bool
+    // Read for signs. The WebVTT path uses none of it: colour, size and weight are the app's to
+    // decide there, and a sign is the one case where they are not.
+    var fontSize: Double = 48
+    var colour: Int = 0xFFFFFF
+    var alpha: Double = 1
+    var outlineColour: Int = 0x000000
+    var outlineWidth: Double = 0
+    var bold: Bool = false
+    var scaleX: Double = 1
+    var scaleY: Double = 1
+    var angle: Double = 0
+    var marginL: Double = 0
+    var marginR: Double = 0
+    var marginV: Double = 0
   }
 
   struct Event {
+    /// Index of the line this came from, so a sign can be cut out of the script handed to the
+    /// WebVTT converter. Mirrors the split on Android; it is what makes drawing an event twice
+    /// structurally impossible rather than merely avoided.
+    var lineIndex: Int = -1
     var startMs: Int
     var endMs: Int
     var styleName: String
@@ -639,7 +745,7 @@ private struct AssScript {
     var sawPlayResX = false
     var sawPlayResY = false
 
-    for rawLine in content.components(separatedBy: "\n") {
+    for (lineIndex, rawLine) in content.components(separatedBy: "\n").enumerated() {
       let line = rawLine.trimmingCharacters(in: .whitespaces)
       if line.isEmpty || line.hasPrefix(";") { continue }
 
@@ -685,7 +791,19 @@ private struct AssScript {
               : ((1...9).contains(rawAlignment) ? rawAlignment : 2),
             italic: field("italic") == "-1",
             underline: field("underline") == "-1",
-            invisible: Self.isInvisibleStyle(fontSize: field("fontsize"), primaryColour: field("primarycolour"))
+            invisible: Self.isInvisibleStyle(fontSize: field("fontsize"), primaryColour: field("primarycolour")),
+            fontSize: field("fontsize").flatMap(SubtitleConverter.finite) ?? 48,
+            colour: field("primarycolour").flatMap { SubtitleConverter.parseAssColour($0)?.rgb } ?? 0xFFFFFF,
+            alpha: field("primarycolour").flatMap { SubtitleConverter.parseAssColour($0)?.alpha } ?? 1,
+            outlineColour: field("outlinecolour").flatMap { SubtitleConverter.parseAssColour($0)?.rgb } ?? 0x000000,
+            outlineWidth: field("outline").flatMap(SubtitleConverter.finite) ?? 0,
+            bold: field("bold") == "-1",
+            scaleX: (field("scalex").flatMap(SubtitleConverter.finite) ?? 100) / 100,
+            scaleY: (field("scaley").flatMap(SubtitleConverter.finite) ?? 100) / 100,
+            angle: field("angle").flatMap(SubtitleConverter.finite) ?? 0,
+            marginL: field("marginl").flatMap(SubtitleConverter.finite) ?? 0,
+            marginR: field("marginr").flatMap(SubtitleConverter.finite) ?? 0,
+            marginV: field("marginv").flatMap(SubtitleConverter.finite) ?? 0
           )
         }
 
@@ -697,7 +815,8 @@ private struct AssScript {
         } else if key.caseInsensitiveCompare("Dialogue") == .orderedSame {
           // Only Dialogue reaches the screen. Comment carries typesetting notes and unused
           // alternates, and Picture/Sound/Movie/Command are not text at all.
-          guard let event = Self.parseEvent(value, fields: eventFields) else { continue }
+          guard var event = Self.parseEvent(value, fields: eventFields) else { continue }
+          event.lineIndex = lineIndex
           events.append(event)
         }
 

package/ios/VideoPlayerItem.swift

@@ -7,6 +7,13 @@ class VideoPlayerItem: AVPlayerItem {
   let urlAsset: VideoAsset
   let videoSource: VideoSource
   let isHls: Bool
+  /// ASS typesetting taken out of this item's subtitle tracks, keyed by language subtag.
+  ///
+  /// Carried on the item rather than in a store of its own, because the item *is* the identity the
+  /// overlay needs: two players can be loading different videos at once, and a store keyed by
+  /// anything a subtitle track keeps inside a composition — which is only its language — would have
+  /// them overwrite each other.
+  let assSigns: [String: [AssSign]]
   var videoTracks: [VideoTrack] {
     get async {
       return await tracksLoadingTask?.value ?? []
@@ -24,6 +31,8 @@ class VideoPlayerItem: AVPlayerItem {
     let asset = VideoAsset(url: url, videoSource: videoSource)
     self.urlAsset = asset
     self.isHls = asset.effectivePlaybackURL.isHLS || asset.effectiveContentType == .hls
+    // This initializer builds no composition, so it sideloads nothing and has no typesetting.
+    self.assSigns = [:]
     super.init(asset: urlAsset, automaticallyLoadedAssetKeys: nil)
     self.createTracksLoadingTask()
   }
@@ -51,15 +60,18 @@ class VideoPlayerItem: AVPlayerItem {
     // (non-HLS, non-DRM) sources — HLS declares its own subtitle renditions, and a composition would
     // bypass the DRM/resource-loader path used by protected content.
     var playbackAsset: AVAsset = asset
+    var signs: [String: [AssSign]] = [:]
     if let subtitleTracks = videoSource.subtitleTracks, !subtitleTracks.isEmpty, !isHls, videoSource.drm == nil {
-      if let composition = await VideoPlayerSubtitleSideload.buildComposition(
+      if let sideloaded = await VideoPlayerSubtitleSideload.buildComposition(
         from: asset,
         subtitleTracks: subtitleTracks,
         headers: videoSource.headers
       ) {
-        playbackAsset = composition
+        playbackAsset = sideloaded.composition
+        signs = sideloaded.signsByLanguage
       }
     }
+    self.assSigns = signs
 
     super.init(asset: playbackAsset, automaticallyLoadedAssetKeys: nil)
     self.createTracksLoadingTask()

package/ios/VideoPlayerSubtitleSideload.swift

@@ -13,14 +13,27 @@ import ExpoModulesCore
 /// pipeline already understands. Only WebVTT is natively supported, so `SRT` files are converted first, and
 /// remote files are downloaded to a temporary location because `insertTimeRange` requires a readable local track.
 internal enum VideoPlayerSubtitleSideload {
+  /// A composition plus the typesetting taken out of its subtitle tracks, keyed by language.
+  ///
+  /// The signs travel with the composition rather than through a store of their own. A store would
+  /// have to be keyed by something both ends can see, and the only identity a sideloaded track keeps
+  /// inside a composition is its language — which means two players loading different videos in the
+  /// same language would overwrite each other, and a second episode would inherit the first one's
+  /// signs. Handing them back here makes the `AVPlayerItem` itself the identity.
+  struct SideloadResult {
+    let composition: AVMutableComposition
+    let signsByLanguage: [String: [AssSign]]
+  }
+
   static func buildComposition(
     from asset: AVURLAsset,
     subtitleTracks: [SubtitleSource],
     headers: [String: String]?
-  ) async -> AVMutableComposition? {
+  ) async -> SideloadResult? {
     do {
       let mainDuration = try await asset.load(.duration)
       let composition = AVMutableComposition()
+      var signsByLanguage: [String: [AssSign]] = [:]
 
       // Copy the original audio + video tracks.
       let tracks = try await asset.load(.tracks)
@@ -54,7 +67,7 @@ internal enum VideoPlayerSubtitleSideload {
 
       var didAddSubtitle = false
       for subtitle in subtitleTracks {
-        guard let localURL = await resolveLocalVttURL(for: subtitle, headers: headers) else {
+        guard let localURL = await resolveLocalVttURL(for: subtitle, headers: headers, signs: &signsByLanguage) else {
           continue
         }
         let subtitleAsset = AVURLAsset(url: localURL)
@@ -94,7 +107,7 @@ internal enum VideoPlayerSubtitleSideload {
         }
       }
 
-      return didAddSubtitle ? composition : nil
+      return didAddSubtitle ? SideloadResult(composition: composition, signsByLanguage: signsByLanguage) : nil
     } catch {
       log.warn("[expo-video] Failed to build subtitle composition: \(error.localizedDescription)")
       return nil
@@ -108,7 +121,11 @@ internal enum VideoPlayerSubtitleSideload {
   /// also preserved the colours and weights a WebVTT file carries in `<c.yellow>` and `<b>`, which
   /// would then beat `subtitleStyle`. The temp-file cache means the work happens once per
   /// (uri, language, format, offset).
-  private static func resolveLocalVttURL(for subtitle: SubtitleSource, headers: [String: String]?) async -> URL? {
+  private static func resolveLocalVttURL(
+    for subtitle: SubtitleSource,
+    headers: [String: String]?,
+    signs: inout [String: [AssSign]]
+  ) async -> URL? {
     guard let uri = subtitle.uri else {
       return nil
     }
@@ -130,7 +147,15 @@ internal enum VideoPlayerSubtitleSideload {
     }
 
     switch subtitle.resolvedFormat {
-    case .ass: text = SubtitleConverter.assToVtt(text)
+    case .ass:
+      // Typesetting is taken out here rather than converted. WebVTT can express no rotation, scale
+      // or per-cue opacity, and AVFoundation renders the track itself, so a sign that went through
+      // would come out flat. `AssSignOverlayView` draws them instead.
+      let split = SubtitleConverter.splitAss(text)
+      if !split.signs.isEmpty {
+        signs[AssSign.normalizeLanguage(subtitle.language ?? "und")] = split.signs
+      }
+      text = SubtitleConverter.assToVtt(split.dialogueOnly)
     case .srt: text = SubtitleConverter.srtToVtt(text)
     case .vtt: text = SubtitleConverter.sanitizeVtt(text)
     }

package/ios/VideoView.swift

@@ -11,6 +11,14 @@ public final class VideoView: ExpoView, AVPlayerViewControllerDelegate {
       playerViewController.player = player?.ref
       // Forward any subtitle style set before the player was attached.
       player?.subtitleStyle = subtitleStyle
+      // ASS typesetting is drawn by us, not by AVFoundation, which can express none of its
+      // transforms. Installed whenever a player arrives and torn down with the view; the overlay
+      // sits idle and costs a display-link tick until a track with signs is actually loaded.
+      if player != nil {
+        AssSignOverlayView.install(in: playerViewController)
+      } else {
+        AssSignOverlayView.remove(from: playerViewController)
+      }
     }
   }
 
@@ -74,6 +82,7 @@ public final class VideoView: ExpoView, AVPlayerViewControllerDelegate {
   deinit {
     VideoManager.shared.unregister(videoView: self)
     removeFirstFrameObserver()
+    AssSignOverlayView.remove(from: playerViewController)
   }
 
   func enterFullscreen() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-video-subtitle",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "A cross-platform, performant video component for React Native and Expo with external subtitle sideloading and custom subtitle styling.",
   "keywords": [
     "expo",