expo-video-subtitle 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,132 @@ 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.6.0
+
+### Fixed
+
+- **ASS dialogue keeps working with `bottomOffset` and with cue stacking again (Android).** Media3's
+  `SsaParser` calls `setLine` and `setPosition` on *every* cue, including the bottom-centre dialogue
+  the author placed nothing on. `SubtitlePainter` applies `bottomPaddingFraction` only to cues whose
+  `line` is unset, so `SubtitleSource.bottomOffset` silently stopped moving anything on an `.ass`
+  track, and `StackingSubtitleParser` treated every cue as deliberately placed and left simultaneous
+  speakers drawing on top of each other.
+
+  A new `SsaCueNormalizer` clears the placement Media3 filled in. Recognising it is exact rather
+  than a guess: the values are a pure function of the cue's anchors, so a cue matching both defaults
+  for the bottom-centre anchors is precisely a cue with no positioning tag. Anything the author did
+  place — `\an8`, `\pos`, a style aligned elsewhere — keeps everything and still bypasses stacking.
+
+- **Signs keep the colours they were typeset in (Android).** The span filter dropped colour from
+  every cue so the app's own subtitle style would win, which is right for dialogue and wrong for a
+  sign: typesetting is drawn onto the artwork in colours chosen to sit on it, and the dark lettering
+  on the white placards in Jujutsu Kaisen S3E3 became white-on-white. Cues an ASS track positions
+  itself now keep their appearance; unpositioned dialogue still loses its own and follows the
+  viewer's settings. Only ASS opts in — it is the one format where positioning reliably means
+  "sign" rather than a cue setting on ordinary dialogue.
+
+- **Typesetters' working notes stay hidden.** A script ships its production notes on a style that
+  renders nothing: JJK S3E3 carries `Style: f0ld3r-invisible` with `Fontsize 0` and every colour
+  `&HFF……`, holding 158 events of "--mahito", "#1", "check in frame 6212". libass honours both
+  signals. Media3 turns a transparent primary colour into a `ForegroundColorSpan` with alpha 0,
+  which the span filter then strips, so the note came back in the viewer's colour at the viewer's
+  size; the iOS converter never read either field, and WebVTT cannot express opacity anyway. Events
+  on such a style are now dropped on both platforms, before anything can make them visible.
+
+### Known limitations
+
+- Sign **font size** is still the app's, not the script's. Media3 does read `Fontsize` into
+  `Cue.textSize`, but the filter clears it so the two subtitle views measure the same glyphs; giving
+  it back to signs needs the rounded-background view checked on a device first.
+- Blur, borders, shadows, rotation and `\t` animation are still dropped. Matching libass output
+  exactly needs libass, not Media3.
+
+## 0.5.0
+
+### Added
+
+- **`SubtitleSource.format` accepts `'ass'` and `'ssa'`.** Advanced SubStation Alpha is what anime
+  releases actually ship, and it is the only common format that can place a caption anywhere on
+  screen rather than at the bottom.
+
+  The two platforms get there differently. **Android** renders the original file: Media3's
+  `DefaultSubtitleParserFactory` already accepts `MimeTypes.TEXT_SSA`, so this is a MIME mapping and
+  nothing more. **iOS** converts to WebVTT inside the module at load time, because `AVFoundation`
+  reads only WebVTT as a `.text` track.
+
+  What survives: `\an1`-`\an9` and the legacy `\a`, `\pos`, `\N` / `\n` / `\h`, italic and
+  underline. What is dropped: colour, font size, font weight, karaoke timings, transforms, rotations,
+  borders and shadows, `\move`, `\fad`, `\clip`, vector drawings (`\p1`), and `Comment:` events.
+
+  On iOS, a `\an8` sign lands at `line:5%`, matching Media3's `SsaParser.DEFAULT_MARGIN` so the same
+  sign sits in the same place on both platforms.
+
+- **iOS:** `.srt` files carrying `{\anN}` leaked from an ASS converter now position correctly instead
+  of printing the tag on screen. The SubRip path was a two-line regex over timestamps; it is now a cue
+  block parser, because a tag found in a cue's *text* has to become a setting on the *timing line*
+  above it.
+
+- **iOS:** subtitle files that are not UTF-8 are decoded instead of being dropped without a message.
+  The ladder is BOM sniff, UTF-8, then Windows-1252/1251, Shift-JIS, Big5, GB 18030, and finally
+  Latin-1, which never fails. Previously `String(data:encoding:.utf8)` returned nil for a Windows-1251
+  file and the whole track vanished silently.
+
+- **`scripts/verify-subtitle-converter.sh`** compiles the shipped converter against 87 assertions and
+  runs them. The tag table, the `\an` to cue-settings mapping and the escaping order are all pure
+  string transforms, and all three fail silently on a device.
+
+### Changed
+
+- **Colour, font size and font weight carried by a subtitle file are now always ignored, on both
+  platforms.** `subtitleStyle` is the only thing that decides them. This is deliberate and there is no
+  way to opt out: a track shipping yellow 72pt bold text should not override the size a user chose in
+  your app's settings.
+
+  On Android this moved into the parser (`SubtitleSpanFilter`), because `SubtitleView`'s own
+  `applyEmbeddedStyles` flag is all-or-nothing and, when off, strips italic along with everything else.
+  Note it never touches `line`, `position` or `textAlignment`, so a track's placement survives either
+  setting.
+
+- **`subtitleStyle.applyEmbeddedStyles` now defaults to `true`** and means "keep the track's italic,
+  underline and strikethrough". If you want the old flattened look, set it to `false` explicitly.
+
+- **iOS:** subtitle text is now HTML-escaped, so a cue containing `<`, `&` or `-->` renders literally
+  instead of being read as markup or as a cue boundary.
+
+- **iOS:** a sideloaded `.vtt` is no longer passed through untouched. It goes through the same
+  sanitising pass, because `<c.yellow>` and `<b>` are a WebVTT file's colour and weight and belong to
+  `subtitleStyle` like every other track's do.
+
+- **iOS:** the cached rendition's `formatVersion` moved to `v3` and the cache key now includes the
+  format, so an install that has already played a track picks up the newly converted file. Without the
+  bump the change appears not to work on exactly the devices used to test it.
+
+### Known limitations
+
+- **Strikethrough renders on Android only.** WebVTT has no strikethrough tag and CoreMedia has no text
+  markup attribute for one, so there is no iOS workaround to reach for.
+
+- **`bottomOffset` does not move ASS cues on Android.** `SsaParser` gives every cue an explicit line
+  and `SubtitlePainter` only applies `bottomPaddingFraction` to cues without one. On iOS the converter
+  emits no `line:` for bottom-centre cues, so ordinary dialogue still shifts there. Fixing Android
+  means a custom SSA parser that can tell a style default from a real `\pos`.
+
+- **Simultaneous ASS cues at the same alignment can overlap on Android.** Media3 does no collision
+  avoidance between positioned cues; libass does. Two speakers talking over each other in an `.ass`
+  track will overprint.
+
+- **Android renders ASS italic and underline from the `[V4+ Styles]` `Style:` line, not from inline
+  `{\i1}`.** Media3's `SsaStyle.Overrides` parses only `\an`, `\pos` and `\move` and then deletes
+  every remaining `{...}` block. iOS handles both.
+
+- **`position:`, `align:` and the `,center` line alignment are newly relied on and unverified on
+  device.** Only `line:N%,end` has been confirmed (iOS 26.5). CoreMedia exposes a matching attribute
+  for each WebVTT cue setting, which is the reason to expect them to work, but there is no attribute
+  for line-align or position-align, so AVFoundation resolves those internally and internal resolution
+  is exactly the kind of thing that can be partial. The mapping emits nothing at all for `\an2`, omits
+  the default `,start`, and avoids `position-align` and `size:` entirely, so the common case is
+  byte-shaped like the output already known to work.
+
 ## 0.4.1
 
 ### Fixed
@@ -24,10 +150,12 @@ for the history of everything that isn't subtitle related.
   This also fixes `bottomOffset: 0`, which as a bare `line:100%` put the top of the cue box at the bottom
   edge of the video and hid the subtitle completely. It now means "sit at the bottom", matching Android.
 
-  Worth knowing before upgrading: a WebVTT parser that predates the alignment component discards the
-  entire `line` setting rather than ignoring the component, so on such a parser captions would be left
-  unpositioned instead of top-anchored. Bottom anchoring cannot be expressed any other way — it is the
-  same setting — so confirm the offset still lands on your target OS versions.
+  AVFoundation honours both parts — confirmed on iOS 26.5, where the caption's bottom edge lands at the
+  requested percentage and clears a burned-in subtitle exactly as the Android side does at the same
+  value. Worth knowing for older targets, though: a WebVTT parser that predates the alignment component
+  discards the entire `line` setting rather than ignoring the component, so on such a parser captions
+  would be left unpositioned instead of top-anchored. Bottom anchoring cannot be expressed any other
+  way — it is the same setting — so confirm the offset still lands on the oldest OS you support.
 
 - **iOS:** the cached rendition of a rewritten subtitle is keyed on the format version as well as on the
   URL, language and offset. Without it, an install that had already rendered a given offset would be

package/FORK.md

@@ -20,12 +20,15 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 
 | File | Lines | Purpose |
 | --- | --- | --- |
-| `ios/Records/SubtitleSource.swift` | 41 | Record for one sideloaded subtitle; `isSrt` detection; `bottomOffset`, which lives here rather than on `SubtitleStyle` because the composition is built from a `VideoSource` alone, before any `VideoView` has supplied a style. |
+| `ios/Records/SubtitleSource.swift` | 61 | Record for one sideloaded subtitle; `resolvedFormat` / `isSrt` / `isAss` detection; `bottomOffset`, which lives here rather than on `SubtitleStyle` because the composition is built from a `VideoSource` alone, before any `VideoView` has supplied a style. |
 | `ios/Records/SubtitleStyle.swift` | 118 | Record for caption styling; hex→ARGB parsing; builds `[AVTextStyleRule]`. |
-| `ios/VideoPlayerSubtitleSideload.swift` | 281 | Builds the `AVMutableComposition`, downloads remote subs, SRT→WebVTT converter, and `applyLinePosition`, which writes a WebVTT `line:N%,end` cue setting per cue for `bottomOffset` — the only way to position captions AVFoundation renders itself. **The trailing `,end` is the line alignment component, not a `line-align` setting** (there is no such setting; the six are `vertical`/`line`/`position`/`size`/`align`/`region`), and it is what anchors the percentage to the bottom edge, matching Android. A parser predating it drops the whole `line` setting, so there is no graceful degradation — verify on device. Cue timing lines are matched by **timestamp regex, not by searching for `-->`**: subtitle text may contain an arrow, and appending a cue setting to it prints the setting on screen. The temp-file hash includes `bottomOffset` *and* a `formatVersion`, joined on **NUL** — the offset so a changed value does not reuse the previous rendition, the version so an upgrade that changes the written form does not reuse the previous release's, and NUL because a hyphen occurs inside both BCP-47 tags and URLs and let two subtitles collide. |
-| `android/…/records/SubtitleSource.kt` | 54 | Record → `MediaItem.SubtitleConfiguration` + MIME resolution. |
-| `android/…/records/SubtitleStyle.kt` | 144 | Record → `CaptionStyleCompat`; hex colour parsing; font-family resolution (`res/font` → `ReactFontManager`); the `applyEmbeddedStyles` flag, which `SubtitleUtils` reads directly rather than `toCaptionStyle`. |
-| `android/…/utils/StackingSubtitleParser.kt` | 300 | `SubtitleParser` for SubRip that segments the cue timeline and merges simultaneous cues into one stacked block, plus the `SubtitleParser.Factory` that routes SubRip to it. Assigns each cue a vertical slot it keeps for its whole time on screen — a finished cue's line is held blank (`\u200B`) so the cues above it do not drop. Merges through a `SpannableStringBuilder` so cue spans survive. |
+| `ios/VideoPlayerSubtitleSideload.swift` | 282 | Builds the `AVMutableComposition`, downloads remote subs, SRT→WebVTT converter, and `applyLinePosition`, which writes a WebVTT `line:N%,end` cue setting per cue for `bottomOffset` — the only way to position captions AVFoundation renders itself. **The trailing `,end` is the line alignment component, not a `line-align` setting** (there is no such setting; the six are `vertical`/`line`/`position`/`size`/`align`/`region`), and it is what anchors the percentage to the bottom edge, matching Android. A parser predating it drops the whole `line` setting, so there is no graceful degradation — verify on device. Cue timing lines are matched by **timestamp regex, not by searching for `-->`**: subtitle text may contain an arrow, and appending a cue setting to it prints the setting on screen. The temp-file hash includes `bottomOffset` *and* a `formatVersion`, joined on **NUL** — the offset so a changed value does not reuse the previous rendition, the version so an upgrade that changes the written form does not reuse the previous release's, and NUL because a hyphen occurs inside both BCP-47 tags and URLs and let two subtitles collide. |
+| `ios/SubtitleConverterText.swift` | 566 | ASS/SSA → WebVTT, the reworked SubRip → WebVTT cue-block parser, WebVTT sanitising, and the non-UTF-8 decode ladder. Header fields are read from the script's own `Format:` lines, never assumed: encoders reorder them, and reading the Text column one position off yields a file that still parses and is entirely wrong. Override blocks are walked by a **scanner, not a list of regexes**, and the tag name is read as a run of letters — that is what stops `\c` from eating `\clip` and `\b` from eating `\bord`, and what makes `\p` require its digit so `\pos` and `\pbo` can never be mistaken for a vector drawing. Text is escaped **before** markup is inserted (`&` then `<` then `>`), which also turns a dialogue `-->` into `--&gt;` so WebVTT cannot read a text line as a cue boundary. |
+| `android/…/utils/SubtitleSpanFilter.kt` | 135 | Strips colour, size, family and weight from every cue of every format, keeping italic/underline/strikethrough and all positioning, plus `FilteringSubtitleParser` which applies it to whatever a delegate emits. **Load-bearing fact, verified against Media3 1.9.0 bytecode:** `SubtitleViewUtils.removeAllEmbeddedStyling` touches only `clearWindowColor`, `getText`/`setText` and `setTextSize` — never `line`, `position` or `textAlignment`. That is why the filter can live in the parser and the view flag can stay on; if an upstream sync changes it, this whole design has to be revisited. Uses an **allowlist**, because a denylist misses `TextAppearanceSpan` (colour + size + family in one span). `StyleSpan` needs a rewrite rather than a keep/drop: `BOLD_ITALIC` has to come back as plain `ITALIC` over the same range. |
+| `android/…/records/SubtitleSource.kt` | 63 | Record → `MediaItem.SubtitleConfiguration` + MIME resolution. |
+| `android/…/records/SubtitleStyle.kt` | 152 | Record → `CaptionStyleCompat`; hex colour parsing; font-family resolution (`res/font` → `ReactFontManager`); the `applyEmbeddedStyles` flag, which `SubtitleUtils` reads directly rather than `toCaptionStyle` and which defaults to `true` since 0.5.0. |
+| `android/…/utils/StackingSubtitleParser.kt` | 342 | `SubtitleParser` that segments the cue timeline and merges simultaneous **unpositioned** cues into one stacked block, plus the `SubtitleParser.Factory` that routes SubRip and ASS/SSA to it and wraps every parser in `FilteringSubtitleParser`. ASS gets there through `SsaCueNormalizer` as the `prepare` step — without it `SsaParser` sets both `line` and `position` on every cue and they would all take the passthrough branch. Assigns each cue a vertical slot it keeps for its whole time on screen — a finished cue's line is held blank (`\u200B`) so the cues above it do not drop. Merges through a `SpannableStringBuilder` so cue spans survive. |
+| `android/…/utils/SsaCueNormalizer.kt` | 93 | Clears the `line`/`position` Media3's `SsaParser` fills in on cues the ASS author never placed, so `bottomOffset` and cue stacking work on `.ass` the way they already do on `.srt`. The test is exact rather than heuristic: those values are a pure function of the cue's anchors, so matching both defaults for the bottom-centre anchors *is* "no positioning tag". Also drops events on a style the author made invisible (`Fontsize 0`, or a primary colour whose inverted alpha byte is `FF`) — that is where typesetters park working notes, and nothing downstream can carry "invisible". |
 | `android/…/utils/RoundedSubtitleBackground.kt` | 352 | Draws `subtitleStyle.backgroundRadius` as rounded boxes, which Media3 cannot do at all: it paints `backgroundColor` as a framework `BackgroundColorSpan` and `windowColor` with `canvas.drawRect`, neither takes a radius, and `SubtitlePainter`/`CanvasSubtitleOutput` are package-private final while `SubtitleView` is final. A second `SubtitleView` is inserted behind `PlayerView`'s own, fed from `Player.Listener.onCues`, drawing a `LineBackgroundSpan` per line. **Its `EDGE_TYPE_NONE` is load-bearing** — `SubtitlePainter` copies the cue text for an edge pass and draws both layouts when the edge type is outline/raised/depressed, which would paint the box twice and darken a semi-transparent colour. State hangs off the view's `tag`, never a map in the companion object; see the `find` KDoc for why even a `WeakHashMap` leaks here. |
 | `FORK.md`, `LICENSE` | — | This guide; MIT licence (upstream copyright preserved). |
 | `eslint.config.js` | 4 | Verbatim copy of `expo-module-scripts/templates/eslint.config.js`. **Recreate it if a sync drops it** — `expo-module configure` treats it as an *optional* template and only syncs it when it already exists, so without this file `npm run lint` dies with "ESLint couldn't find an eslint.config.js". |
@@ -36,8 +39,8 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 
 | File | Δ | What to re-apply |
 | --- | --- | --- |
-| `src/VideoPlayer.types.ts` | +79 | `subtitleTracks?: SubtitleSource[]` on `VideoSourceObject`; the exported `SubtitleSource` type, including `bottomOffset`. |
-| `src/VideoView.types.ts` | +129 | `subtitleStyle?: SubtitleStyle` on `VideoViewProps`; `SubtitleStyle` + `SubtitleEdgeType` types. |
+| `src/VideoPlayer.types.ts` | +92 | `subtitleTracks?: SubtitleSource[]` on `VideoSourceObject`; the exported `SubtitleSource` type, including `bottomOffset` and the `'vtt' | 'srt' | 'ass' | 'ssa'` format union. |
+| `src/VideoView.types.ts` | +123 | `subtitleStyle?: SubtitleStyle` on `VideoViewProps`; `SubtitleStyle` + `SubtitleEdgeType` types. |
 | `src/index.ts` | +2 | Export `SubtitleStyle`, `SubtitleEdgeType` (`SubtitleSource` rides on `export type *`). |
 | `src/VideoPlayer.web.tsx` | +5 / −1 | Hoist `JSON.stringify(source)` out of the `useMemo` dependency list into a `sourceKey` const. No behaviour change — it was already recomputed every render — but `react-hooks/use-memo` rejects non-simple expressions in a dependency array, and it was the single lint **error** in the package. |
 | `src/ts-declarations/react-native-assets.d.ts` | +22 / −1 | Replace upstream's `../../../expo-asset/…` reference (monorepo-only) with standalone `declare module` shims. **Always needed outside the Expo monorepo.** |
@@ -47,7 +50,7 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 | `ios/VideoView.swift` | +8 | `subtitleStyle` property; forward it when `player` is (re)assigned. |
 | `ios/VideoModule.swift` | +4 | `Prop("subtitleStyle")`. |
 | `android/…/records/VideoSource.kt` | +9 / −2 | `subtitleTracks` field; `setSubtitleConfigurations(…)` in `toMediaItem()`; subtitle key in `toMediaId()`. |
-| `android/…/utils/SubtitleUtils.kt` | +92 / −21 | `configureSubtitleView(…, customStyle)` overload and a `styleProvider` on the captioning listener. Keeps the original behaviour when no custom style is set. Passes `context` to `toCaptionStyle` for font lookup. Drives `setApplyEmbeddedStyles` from `customStyle.applyEmbeddedStyles` (upstream hardcodes `false`). |
+| `android/…/utils/SubtitleUtils.kt` | +92 / −21 | `configureSubtitleView(…, customStyle)` overload and a `styleProvider` on the captioning listener. Keeps the original behaviour when no custom style is set. Passes `context` to `toCaptionStyle` for font lookup. Drives `setApplyEmbeddedStyles` from `customStyle.applyEmbeddedStyles`, defaulting to `true` (upstream hardcodes `false`). The resolved value is shared with `RoundedSubtitleBackground`: `StyleSpan` is a `MetricAffectingSpan`, so italic measures wider and a disagreement draws the box too narrow. |
 | `android/…/VideoView.kt` | +16 / −5 | `subtitleStyle` property; pass it at all 4 `configureSubtitleView` call sites + the captioning listener. |
 | `android/…/VideoModule.kt` | +4 | `Prop("subtitleStyle")`. |
 | `android/…/utils/DataSourceUtils.kt` | +5 | `setSubtitleParserFactory(ExpoVideoSubtitleParserFactory())` on the `DefaultMediaSourceFactory`. Note this file declares `package expo.modules.video` despite living in `utils/`, so the factory needs an explicit import. |
@@ -182,7 +185,8 @@ npm pack --dry-run       # expect build/, plugin/build/, LICENSE, native sources
                          # NO dev config (.prettierrc, eslint.config.js, *.tsbuildinfo) — see §1
 ```
 
-The file count is a blunt but effective regression check: **255 files** as of 0.4.1 (254 at 0.2.2, plus
+The file count is a blunt but effective regression check: **257 files** as of 0.5.0 (255 at 0.4.1, plus
+`ios/SubtitleConverterText.swift` and `android/…/utils/SubtitleSpanFilter.kt`; 254 at 0.2.2, plus
 `RoundedSubtitleBackground.kt` in 0.3.0). If a change moves
 it, diff the list against the previous release and confirm every difference is intended —
 `npm pack --dry-run --json` gives a machine-readable list. Both directions matter: an unexpected
@@ -197,33 +201,57 @@ the config went missing than that the code is genuinely misformatted — check t
 
 ### iOS — running the subtitle converter without a host app
 
-`SubtitleConverter` at the bottom of `ios/VideoPlayerSubtitleSideload.swift` imports only `Foundation`,
-so it compiles and runs on its own. It is worth exercising on every change to it: `srtToVtt` and
-`applyLinePosition` are pure string transforms whose failure mode is a silently malformed cue rather
-than a crash — a cue setting appended to a *text* line prints on screen, and a percentage outside
-`0`–`100` can cost the whole cue.
-
-Extract the shipped source rather than retyping it, so the test cannot drift from what ships:
+The converter imports only `Foundation`, so it compiles and runs without a host app. There is a
+script for it:
 
 ```bash
-awk '/^internal enum SubtitleConverter \{/,0' ios/VideoPlayerSubtitleSideload.swift \
-  > /tmp/swiftcheck/Converter.swift
-sed -i '' '1i\
-import Foundation
-' /tmp/swiftcheck/Converter.swift
-# Assertions go in main.swift — Swift allows top-level code only in a file with that name.
-swiftc -o converttest Converter.swift main.swift && ./converttest
+./scripts/verify-subtitle-converter.sh
 ```
 
-Cases worth keeping covered: the emitted setting is `line:N%,end`; `0` and `1` map to `line:100%,end`
-and `line:0%,end`; out-of-range offsets clamp; a text line containing `-->` is left alone; a cue already
-carrying `line:` is passed through; an unrelated cue setting (`align:start`) is preserved while the cue
-still moves; hourless timings are recognised; CRLF is normalised.
+It extracts the shipped source rather than copying it — `awk` for the `SubtitleConverter` enum out of
+`ios/VideoPlayerSubtitleSideload.swift`, plus `ios/SubtitleConverterText.swift` with its
+`ExpoModulesCore` import stripped and `log` stubbed — so the assertions cannot drift from what ships.
+87 of them live in `scripts/subtitle-converter-checks.swift`.
+
+**`scripts/` must stay out of `ios/`.** The podspec globs `ios/**/*.{h,m,swift}`, so a checks file
+with top-level code placed under `ios/` would be compiled into every consumer's pod and fail their
+build. It is also listed in `.npmignore`.
+
+This is worth exercising on every change, because everything it covers is a pure string transform
+whose failure mode is a silently malformed cue rather than a crash: a cue setting appended to a
+*text* line prints on screen, a percentage outside `0`–`100` can cost the whole cue, and a
+mis-scanned override block can eat the dialogue around it.
+
+Cases the harness keeps covered: all nine `\an` values and the legacy `\a`; `\pos` scaling against
+`PlayResX`/`PlayResY`, including the 4:3 derivation when only one axis is declared; the full
+drop-list of appearance tags; longest-match (`\clip` is not `\c`, `\bord` is not `\b`); whole-event
+drops for `Comment:`, `{\p1}` drawings and tags-only lines; escaping order, including a dialogue
+`-->`; commas inside the ASS Text column; a reordered `[Events] Format:` line; the SubRip path with a
+leaked `{\an8}`, `<font color>` and `<b>`; WebVTT `<c.…>` and STYLE-block sanitising; the
+`applyLinePosition` interaction for positioned, bottom-centre and side-only cues; and the encoding
+ladder.
 
 **A passing harness does not mean the cue renders where you asked.** It checks the bytes written, not
-whether AVFoundation honours them. `line:` positioning is the part of this package with no automated
-coverage at all — confirm it against a real player with a *two-line* cue, which is the case the
-alignment component exists for.
+whether AVFoundation honours them. That is the part of this package with no automated coverage at all
+— confirm it against a real player with a *two-line* cue, which is the case the alignment component
+exists for.
+
+Baseline: as of 0.4.1, AVFoundation honours `line:` **and** the `,end` alignment component on iOS 26.5,
+placing the caption's bottom edge at the requested percentage.
+
+As of 0.5.0 the ASS mapping newly relies on **`position:`, `align:` and the `,center` line alignment,
+and none of the three is confirmed on device.** CoreMedia exposes a matching text-markup attribute for
+each WebVTT cue setting, which is the reason to expect them to work, but there is no attribute for
+line-align or position-align — AVFoundation resolves those internally, and internal resolution is
+exactly the kind of thing that can be partial. Verify `\an5` (`,center`) and `\an7`
+(`position:` + `align:`) on the oldest supported OS as well as the newest; the deployment target is
+16.4. If they turn out unsupported, the fallback is to keep the vertical mapping and drop the
+horizontal one, which puts `\an7`/`\an8`/`\an9` all at top-centre and still delivers most of the
+value.
+
+Re-confirm all of this after an upstream sync or when adding support for an older deployment target —
+the failure is silent, and for `line:` it is total rather than partial (a parser that rejects the
+alignment component drops the whole setting).
 
 ### Android — compiling the parser without a host app
 

package/README.md

@@ -60,6 +60,7 @@ const player = useVideoPlayer({
   subtitleTracks: [
     { uri: 'https://cdn.example.com/en.vtt', language: 'en', label: 'English', default: true },
     { uri: 'https://cdn.example.com/id.srt', language: 'id', label: 'Indonesia', format: 'srt' },
+    { uri: 'https://cdn.example.com/signs.ass', language: 'ja', label: 'Signs', format: 'ass' },
   ],
 });
 
@@ -67,12 +68,14 @@ const player = useVideoPlayer({
 player.subtitleTrack = player.availableSubtitleTracks[0];
 ```
 
-`SubtitleSource` fields: `uri` (local `file://` or remote `http(s)://`), `language` (BCP-47 / ISO 639), optional `label`, optional `format` (`'vtt' | 'srt'`, inferred from the extension when omitted), optional `default`, and optional `bottomOffset` (iOS — see [Moving subtitles off burned-in captions](#moving-subtitles-off-burned-in-captions)).
+`SubtitleSource` fields: `uri` (local `file://` or remote `http(s)://`), `language` (BCP-47 / ISO 639), optional `label`, optional `format` (`'vtt' | 'srt' | 'ass' | 'ssa'`, inferred from the extension when omitted), optional `default`, and optional `bottomOffset` (iOS — see [Moving subtitles off burned-in captions](#moving-subtitles-off-burned-in-captions)).
+
+Pass `format` whenever you know it. A URL that serves the file without an extension — a Directus asset at `/assets/<uuid>`, say — leaves nothing to infer from, and the WebVTT default would decode a SubRip or ASS file to zero cues in silence.
 
 | | Android | iOS |
 | --- | --- | --- |
 | Mechanism | `MediaItem.SubtitleConfiguration` (Media3 merges into a `MergingMediaSource`) | `AVMutableComposition` (copies the video/audio tracks and inserts a `.text` track) |
-| Formats | VTT, SRT, TTML natively | VTT natively; **SRT is auto-converted to VTT**; remote files are **downloaded to a local cache first** |
+| Formats | VTT, SRT, ASS/SSA, TTML natively | VTT natively; **SRT and ASS/SSA are auto-converted to VTT**; remote files are **downloaded to a local cache first** |
 
 > **iOS limitations:** sideloading only runs on the asynchronous loading path (the default `VideoPlayer` constructor and `replaceAsync`, not the synchronous `replace`), and only for progressive (non-HLS, non-DRM) sources. HLS/DASH already carry their own subtitle renditions.
 
@@ -145,12 +148,20 @@ That last row is worth knowing: subtitles carrying their own placement — SubRi
 cues with a `line:` setting — were positioned deliberately by whoever wrote them, so neither platform
 moves them.
 
+**ASS/SSA is the case where the two platforms diverge.** Media3's `SsaParser` gives *every* cue an
+explicit line, so `subtitleStyle.bottomOffset` moves nothing on an ASS track on Android. On iOS the
+converter deliberately emits no `line:` for bottom-centre cues (`\an2`, the default for dialogue),
+so ordinary dialogue still shifts while genuine `\an8` signs stay put. Fixing the Android side means
+a custom SSA parser that can tell a style default from a real `\pos`; it is not in this release.
+
 The iOS cue setting is written as `line:N%,end`. The trailing `,end` is WebVTT's line alignment
 component, and it is what makes the percentage refer to the bottom edge of the cue box — so the two
-platforms anchor the same way and one value is correct on both. Note that a WebVTT parser predating
-that component discards the whole `line` setting rather than ignoring the component, which would leave
-captions unpositioned; there is no form that degrades more gently, since both behaviours come from the
-same setting.
+platforms anchor the same way and one value is correct on both. AVFoundation honours both parts,
+confirmed on iOS 26.5.
+
+For older targets, note that a WebVTT parser predating that component discards the whole `line` setting
+rather than ignoring the component, which would leave captions unpositioned; there is no form that
+degrades more gently, since both behaviours come from the same setting.
 
 ## Styling subtitles
 
@@ -170,7 +181,7 @@ Pass a `subtitleStyle` prop to `VideoView`. It applies to whichever subtitle tra
     edgeType: 'outline',          // 'none' | 'outline' | 'dropShadow' | 'raised' | 'depressed'
     edgeColor: '#000000',
     bottomOffset: 0.1,            // Android only — fraction of the view height (0–1)
-    applyEmbeddedStyles: false,   // Android only — see "Inline formatting from the track"
+    applyEmbeddedStyles: true,    // Android only — keeps the track's italic/underline; default true
   }}
 />
 ```
@@ -205,21 +216,34 @@ the region the caption occupies, the background is the box that hugs the text.
 
 ### Inline formatting from the track
 
-Subtitle files carry formatting of their own — `<b>`, `<i>`, `<u>` and `<font color>` tags in `SRT`, and
-richer per-cue styling in embedded `WebVTT`/`TTML` tracks. **Android strips all of it by default**, so
-`subtitleStyle` is the only thing deciding how captions look. Opt in to keep it:
+Subtitle files carry formatting of their own: `<b>`, `<i>`, `<u>` and `<font color>` in `SRT`, `<c.yellow>`
+and `<b>` in `WebVTT`, and a whole styling language in `ASS`. The module splits it in two.
+
+**Colour, font size, font family and weight are always discarded, on both platforms.** They are removed
+while the file is being parsed, before any view exists, so `subtitleStyle` is the single thing deciding
+how captions look. There is no way to opt back into a track's own colours — a subtitle shipping yellow
+72pt bold text cannot override the size your user picked.
+
+**Italic, underline and strikethrough are kept**, and `applyEmbeddedStyles: false` is the blunt switch
+that drops them too:
 
 ```tsx
-<VideoView player={player} subtitleStyle={{ textColor: '#FFFFFF', applyEmbeddedStyles: true }} />
+<VideoView player={player} subtitleStyle={{ textColor: '#FFFFFF', applyEmbeddedStyles: false }} />
 ```
 
-The rest of `subtitleStyle` still applies underneath, and `fontSize` keeps overriding any size the track
-asks for. Only the properties a cue explicitly sets change — an unstyled cue looks identical either way.
-The trade-off is that a track specifying its own colors overrides `textColor` and `windowColor` for those
-cues, so leave this off when the captions must match your UI exactly.
+A track's own placement is unaffected either way, so an `\an8` sign still sits at the top.
+
+Two asymmetries worth knowing:
+
+| | Android | iOS |
+| --- | --- | --- |
+| Strikethrough | renders | **cannot render** — WebVTT has no strikethrough tag and CoreMedia has no attribute for one |
+| Italic/underline in ASS | from the `[V4+ Styles]` `Style:` line only | from the style line **and** inline `{\i1}` |
+| `applyEmbeddedStyles` | honoured | ignored; italic and underline always render |
 
-On iOS this is not configurable: `AVPlayerItem.textStyleRules` composes with whatever the WebVTT cue
-declares, so a track's inline formatting always renders.
+The Android ASS limitation is Media3's: `SsaStyle.Overrides` parses only `\an`, `\pos` and `\move`,
+then `stripStyleOverrides` deletes every remaining `{...}` block, so an inline `{\i1}` never reaches
+the renderer.
 
 ### Fonts
 

package/android/src/main/java/expo/modules/video/records/SubtitleSource.kt

@@ -37,14 +37,24 @@ class SubtitleSource(
     return builder.build()
   }
 
+  /**
+   * ASS and SSA both map to [MimeTypes.TEXT_SSA] ("text/x-ssa"), which Media3's
+   * `DefaultSubtitleParserFactory` already accepts, so no parser of our own is
+   * needed for them. The `else` branch defaults to WebVTT, which means an
+   * unrecognised extension decodes to zero cues rather than erroring: the
+   * caller should pass [format] whenever it knows, and a Directus asset URL
+   * (`/assets/<uuid>`) carries no extension to fall back on.
+   */
   private fun resolveMimeType(uri: Uri): String {
     return when (format?.lowercase()) {
-      "vtt" -> MimeTypes.TEXT_VTT
-      "srt" -> MimeTypes.APPLICATION_SUBRIP
+      "vtt", "webvtt" -> MimeTypes.TEXT_VTT
+      "srt", "subrip" -> MimeTypes.APPLICATION_SUBRIP
+      "ass", "ssa" -> MimeTypes.TEXT_SSA
       else -> {
         val path = uri.toString().substringBefore('?').lowercase()
         when {
           path.endsWith(".srt") -> MimeTypes.APPLICATION_SUBRIP
+          path.endsWith(".ass") || path.endsWith(".ssa") -> MimeTypes.TEXT_SSA
           path.endsWith(".ttml") || path.endsWith(".dfxp") -> MimeTypes.APPLICATION_TTML
           else -> MimeTypes.TEXT_VTT
         }

package/android/src/main/java/expo/modules/video/records/SubtitleStyle.kt

@@ -35,11 +35,16 @@ class SubtitleStyle(
    */
   @Field val backgroundRadius: Float? = null,
   /**
-   * Whether the inline formatting carried by the subtitle track itself is kept. Consumed by
-   * [expo.modules.video.utils.SubtitleUtils.configureSubtitleView] rather than [toCaptionStyle],
-   * because it maps to a [androidx.media3.ui.SubtitleView] flag and not to a caption style property.
+   * Whether the italic, underline and strikethrough carried by the subtitle track itself are kept.
+   * Consumed by [expo.modules.video.utils.SubtitleUtils.configureSubtitleView] rather than
+   * [toCaptionStyle], because it maps to a [androidx.media3.ui.SubtitleView] flag and not to a
+   * caption style property.
+   *
+   * Colour, font size, font family and weight are never taken from the track regardless of this
+   * flag: [expo.modules.video.utils.SubtitleSpanFilter] strips them in the parser, before any view
+   * exists. That is what makes `true` a safe default here, which it was not before.
    */
-  @Field val applyEmbeddedStyles: Boolean = false
+  @Field val applyEmbeddedStyles: Boolean = true
 ) : Record, Serializable {
   /**
    * Builds a [CaptionStyleCompat], falling back to [base] for any unspecified property so that

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

@@ -0,0 +1,93 @@
+package expo.modules.video.utils
+
+import android.graphics.Color
+import android.text.Spanned
+import android.text.style.ForegroundColorSpan
+import androidx.annotation.OptIn
+import androidx.media3.common.text.Cue
+import androidx.media3.common.util.UnstableApi
+import kotlin.math.abs
+
+/**
+ * Undoes two things Media3's `SsaParser` does to every ASS cue, so the rest of this package can
+ * treat an `.ass` track the way it treats every other format.
+ *
+ * ### Dialogue gets its position taken back off
+ *
+ * `SsaParser.createCue` ends with an `else` branch that runs for every cue *without* a `\pos` or
+ * `\move`: it calls `setPosition` and `setLine` with values derived purely from the cue's
+ * alignment. So an ordinary bottom-centre dialogue line — the overwhelming majority of a subtitle
+ * file — arrives carrying `line = 0.95` and `position = 0.5` even though the author placed nothing.
+ *
+ * Two features break on that. `SubtitlePainter` applies `bottomPaddingFraction` only to cues whose
+ * `line` is unset, so `SubtitleSource.bottomOffset` (the app's `subtitle_offset_percent`, used to
+ * lift softsubs clear of burnt-in hardsubs) silently stops moving anything. And
+ * [StackingSubtitleParser] treats a positioned cue as deliberately placed and passes it through
+ * unstacked, so two simultaneous speakers draw on top of each other.
+ *
+ * Recognising "the parser filled this in" is exact rather than a guess: the values are a pure
+ * function of the anchors, so a cue matching *both* defaults for the bottom-centre anchors is
+ * precisely a cue that had no positioning tag. Clearing them puts an ASS dialogue cue in the same
+ * shape as a SubRip one, which is the shape both features already work on.
+ *
+ * A cue the author did place — `\an8`, `\pos`, a style aligned anywhere but bottom-centre — fails
+ * the check and keeps everything. That is the signs-and-typesetting case, and it must not move.
+ *
+ * ### Cues the author made invisible are dropped
+ *
+ * Typesetters keep their working notes in the script on a style that renders nothing: JJK S3E3
+ * ships `Style: f0ld3r-invisible` with `Fontsize 0` and every colour `&HFF……`, holding 158 events
+ * of production notes ("--mahito", "#1", "check in frame 6212").
+ *
+ * libass honours both signals and shows nothing. Media3 turns the fully transparent primary colour
+ * into a `ForegroundColorSpan` with alpha 0 — and [SubtitleSpanFilter] then strips colour spans,
+ * because the app owns the subtitle colour. The note would come back in the viewer's own colour, at
+ * the viewer's own size, on screen. Dropping the cue here, before any of that, is the only place
+ * the alpha still means what the author meant.
+ */
+@OptIn(UnstableApi::class)
+internal object SsaCueNormalizer {
+  /** `SsaParser.DEFAULT_MARGIN`. Kept in sync by [sitsWhereTheParserPutIt]'s test. */
+  private const val DEFAULT_MARGIN = 0.05f
+
+  /** The values are computed, not parsed, so they compare exactly; this only guards float drift. */
+  private const val EPSILON = 0.0001f
+
+  fun normalize(cue: Cue): Cue? {
+    if (isInvisible(cue)) return null
+    if (!sitsWhereTheParserPutIt(cue)) return cue
+
+    return cue.buildUpon()
+      .setLine(Cue.DIMEN_UNSET, Cue.LINE_TYPE_FRACTION)
+      .setPosition(Cue.DIMEN_UNSET)
+      .build()
+  }
+
+  /**
+   * True when the cue's placement is exactly what `SsaParser` computes for the bottom-centre
+   * anchors, which is to say the author placed nothing.
+   */
+  private fun sitsWhereTheParserPutIt(cue: Cue): Boolean =
+    cue.lineType == Cue.LINE_TYPE_FRACTION &&
+      cue.lineAnchor == Cue.ANCHOR_TYPE_END &&
+      cue.positionAnchor == Cue.ANCHOR_TYPE_MIDDLE &&
+      abs(cue.line - (1f - DEFAULT_MARGIN)) < EPSILON &&
+      abs(cue.position - 0.5f) < EPSILON
+
+  /**
+   * Either of the two ways an ASS style says "draw nothing": a fully transparent primary colour, or
+   * a zero font size. Both have to cover the whole cue — a transparent run *inside* a line is a
+   * typesetting effect, not a hidden line.
+   */
+  private fun isInvisible(cue: Cue): Boolean {
+    val text = cue.text ?: return false
+    if (cue.textSize == 0f) return true
+    if (text !is Spanned || text.isEmpty()) return false
+
+    return text.getSpans(0, text.length, ForegroundColorSpan::class.java).any { span ->
+      Color.alpha(span.foregroundColor) == 0 &&
+        text.getSpanStart(span) == 0 &&
+        text.getSpanEnd(span) == text.length
+    }
+  }
+}