expo-video-subtitle 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,133 @@ 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.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
+
+- **iOS:** `SubtitleSource.bottomOffset` now anchors the **bottom** of the subtitle block, the same way
+  Android does, so one value places captions identically on both platforms.
+
+  0.4.0 emitted a bare WebVTT `line:` percentage, which anchors the *top* of the cue box. A cue that
+  wrapped onto two lines therefore sat a full line lower on iOS than on Android — 5–13% of the video
+  height at typical caption sizes, comparable to the offset itself, and enough to drop the second line
+  back over the burned-in captions the offset exists to escape. The cue setting is now written as
+  `line:N%,end`, where the trailing `,end` is WebVTT's line alignment component and is what makes the
+  percentage refer to the bottom edge.
+
+  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.
+
+  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
+  handed the file written by the previous version and the fix above would appear not to work — on
+  exactly the devices being used to test it.
+
+- **iOS:** the same cache key joins its parts on NUL instead of a hyphen. A hyphen occurs in both
+  variable parts — BCP-47 tags carry one (`pt-BR`) and so does almost every URL — so two different
+  subtitles could flatten to the same string and be served each other's rewritten file.
+
+### Documentation
+
+- **Android:** `subtitleStyle.bottomOffset` was documented as a fraction of the *view* height. It is a
+  fraction of the content frame, which under the default `contentFit="contain"` is the displayed picture
+  — `SubtitleView` sits inside `AspectRatioFrameLayout`, which `RESIZE_MODE_FIT` shrinks to the video's
+  aspect ratio. The distinction matters for a letterboxed source, and the old wording invited callers to
+  write letterbox compensation that would have been wrong.
+
 ## 0.4.0
 
 ### Added

package/FORK.md

@@ -20,12 +20,14 @@ 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` | 257 | Builds the `AVMutableComposition`, downloads remote subs, SRT→WebVTT converter, and `applyLinePosition`, which writes a WebVTT `line:` cue setting per cue for `bottomOffset` — the only way to position captions AVFoundation renders itself. 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`, or a changed offset would reuse the rendition written for the previous one. |
-| `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` | 308 | `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 and wraps every parser in `FilteringSubtitleParser`. SSA/ASS is deliberately not stacked: `SsaParser` sets both `line` and `position` on every cue, so they would all take the passthrough branch anyway. 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/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 +38,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 +49,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 +184,9 @@ 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: **254 files** as of 0.2.2. If a change moves
+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
 *addition* means dev clutter leaked in, an unexpected *removal* means a consumer is missing something.
@@ -194,6 +198,60 @@ Neither is created by `expo-module configure`, so a sync that loses one breaks t
 that reads like a tooling bug. A `prettier/prettier` warning after a sync is far more likely to mean
 the config went missing than that the code is genuinely misformatted — check that first.
 
+### iOS — running the subtitle converter without a host app
+
+The converter imports only `Foundation`, so it compiles and runs without a host app. There is a
+script for it:
+
+```bash
+./scripts/verify-subtitle-converter.sh
+```
+
+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. 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
 
 `utils/StackingSubtitleParser.kt` imports only `android.text.*` and `androidx.media3.*`, so it

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.
 
@@ -138,13 +141,28 @@ takes effect the next time the source loads**.
 | Where | `subtitleStyle.bottomOffset` | `subtitleTracks[].bottomOffset` |
 | Applies to | every track, embedded included | sideloaded tracks only |
 | Updates | live | on next source load |
-| Anchors | the bottom of the subtitle block | the top of it, so a two-line cue grows downward |
+| Anchors | the bottom of the subtitle block | the bottom of the subtitle block |
 | Cues that position themselves | left alone | left alone |
 
 That last row is worth knowing: subtitles carrying their own placement — SubRip `{\anN}` tags, WebVTT
 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. 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
 
 Pass a `subtitleStyle` prop to `VideoView`. It applies to whichever subtitle track is currently displayed, whether embedded or sideloaded. Colors accept a hex string (`#RGB`, `#RRGGBB`, `#RRGGBBAA`) or `transparent`.
@@ -163,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
   }}
 />
 ```
@@ -198,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/StackingSubtitleParser.kt

@@ -275,8 +275,16 @@ class StackingSubripParser : SubtitleParser {
 }
 
 /**
- * Routes SubRip through [StackingSubripParser] so simultaneous cues stack, and delegates every other
- * subtitle format to Media3's default handling.
+ * Routes SubRip through [StackingSubripParser] so simultaneous cues stack, delegates every other
+ * subtitle format to Media3's default handling, and wraps the result in [FilteringSubtitleParser] so
+ * the appearance a track asks for never overrides the app's own subtitle style.
+ *
+ * SSA and ASS are deliberately NOT stacked. `SsaParser` gives every cue both a `line` and a
+ * `position`, so [StackingSubripParser.hasExplicitPosition] would send all of them down the
+ * passthrough branch anyway, and its merge deliberately leaves `line` unset, which would fight
+ * `\an` and `\pos`. The consequence is real and known: Media3 does no collision avoidance between
+ * positioned cues, so two simultaneous `\an2` dialogue lines overlap on Android where libass would
+ * stack them.
  */
 @OptIn(UnstableApi::class)
 class ExpoVideoSubtitleParserFactory : SubtitleParser.Factory {
@@ -293,7 +301,9 @@ class ExpoVideoSubtitleParserFactory : SubtitleParser.Factory {
     }
 
   override fun create(format: Format): SubtitleParser =
-    if (format.isSubrip()) StackingSubripParser() else defaultFactory.create(format)
+    FilteringSubtitleParser(
+      if (format.isSubrip()) StackingSubripParser() else defaultFactory.create(format)
+    )
 
   private fun Format.isSubrip(): Boolean =
     MimeTypes.APPLICATION_SUBRIP.equals(sampleMimeType, ignoreCase = true)

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

@@ -0,0 +1,135 @@
+package expo.modules.video.utils
+
+import android.graphics.Typeface
+import android.text.Spannable
+import android.text.SpannableString
+import android.text.Spanned
+import android.text.style.AlignmentSpan
+import android.text.style.StrikethroughSpan
+import android.text.style.StyleSpan
+import android.text.style.UnderlineSpan
+import androidx.annotation.OptIn
+import androidx.media3.common.text.Cue
+import androidx.media3.common.text.LanguageFeatureSpan
+import androidx.media3.common.util.Consumer
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.extractor.text.CuesWithTiming
+import androidx.media3.extractor.text.SubtitleParser
+
+/**
+ * Drops the appearance a subtitle file asks for while keeping its layout.
+ *
+ * Colour, font size, font family and weight are the app's to decide: only the
+ * app knows the viewer's appearance settings, so a track that ships yellow
+ * 72pt bold text must not win over them. Everything about *where* and *how the
+ * text reads* stays: italic, underline, strikethrough, alignment, and every
+ * positioning field on the cue.
+ *
+ * This has to live in the parser. It is the only place that sees a cue before
+ * Media3 hands it to a `SubtitleView` we do not own, and the parser factory is
+ * installed on the media source (see [DataSourceUtils.buildMediaSourceFactory])
+ * long before any `VideoView` has supplied a style.
+ *
+ * The complementary fact, verified against Media3 1.9.0: `SubtitleView`'s own
+ * `applyEmbeddedStyles` flag is all-or-nothing and, when off,
+ * `SubtitleViewUtils.removeAllEmbeddedStyling` strips *every* span including
+ * italic. It never touches `line`, `position` or `textAlignment`, which is why
+ * filtering here and leaving that flag on is the combination that works.
+ */
+@OptIn(UnstableApi::class)
+internal object SubtitleSpanFilter {
+  /**
+   * An allowlist, not a denylist.
+   *
+   * A denylist would miss `TextAppearanceSpan`, which carries colour, size and
+   * family in a single span and is what `Html.fromHtml` emits on some API
+   * levels, and it stays wrong for whatever span type a future Media3 parser
+   * introduces. Dropping an unknown span is the safe direction.
+   */
+  private fun isKept(span: Any): Boolean = when (span) {
+    is UnderlineSpan, is StrikethroughSpan, is AlignmentSpan -> true
+    // Ruby, text emphasis and vertical-context spans are layout and language
+    // features. Media3 exempts them from its own stripping for the same reason.
+    is LanguageFeatureSpan -> true
+    // Bold goes, italic stays. BOLD_ITALIC needs the rewrite below.
+    is StyleSpan -> span.style == Typeface.ITALIC
+    else -> false
+  }
+
+  fun filter(cue: Cue): Cue {
+    val text = cue.text
+    val hasSpans = text is Spanned
+    val needsWork = hasSpans || cue.windowColorSet || cue.textSize != Cue.DIMEN_UNSET
+    if (!needsWork) return cue
+
+    val builder = cue.buildUpon()
+
+    if (hasSpans) {
+      val spannable = SpannableString(text)
+      // Snapshot the spans first: the loop both removes and adds, and a live
+      // query would see the replacements it just made.
+      for (span in spannable.getSpans(0, spannable.length, Any::class.java)) {
+        if (isKept(span)) continue
+
+        val start = spannable.getSpanStart(span)
+        val end = spannable.getSpanEnd(span)
+        val flags = spannable.getSpanFlags(span)
+        spannable.removeSpan(span)
+
+        // StyleSpan is one class carrying four states, so bold and italic
+        // cannot be separated by a keep/drop decision. BOLD_ITALIC has to come
+        // back as plain italic over the same range.
+        if (span is StyleSpan && span.style == Typeface.BOLD_ITALIC) {
+          spannable.setSpan(StyleSpan(Typeface.ITALIC), start, end, flags)
+        }
+      }
+      builder.setText(spannable)
+    }
+
+    // A cue's own window colour is the track's, and `subtitleStyle.windowColor`
+    // owns that. Sizes go the same way: `setFixedTextSize` is the single source
+    // of truth, and clearing it here keeps the rounded-background view (which
+    // reads raw player cues) measuring the same glyphs as the front one.
+    builder.clearWindowColor()
+    builder.setTextSize(Cue.DIMEN_UNSET, Cue.TYPE_UNSET)
+
+    return builder.build()
+  }
+}
+
+/**
+ * Applies [SubtitleSpanFilter] to every cue a delegate parser emits.
+ *
+ * Wrapping is deliberately the outermost layer so it also covers the merged
+ * block [StackingSubripParser] produces, and so every format gets the same
+ * policy for free.
+ */
+@OptIn(UnstableApi::class)
+internal class FilteringSubtitleParser(
+  private val delegate: SubtitleParser
+) : SubtitleParser {
+  // Forwarded verbatim. Getting this wrong silently changes whether consecutive
+  // CuesWithTiming replace or merge: SsaParser is MERGE, StackingSubripParser
+  // is REPLACE.
+  override fun getCueReplacementBehavior(): Int = delegate.cueReplacementBehavior
+
+  override fun reset() = delegate.reset()
+
+  override fun parse(
+    data: ByteArray,
+    offset: Int,
+    length: Int,
+    outputOptions: SubtitleParser.OutputOptions,
+    output: Consumer<CuesWithTiming>
+  ) {
+    delegate.parse(data, offset, length, outputOptions) { group ->
+      output.accept(
+        CuesWithTiming(
+          group.cues.map(SubtitleSpanFilter::filter),
+          group.startTimeUs,
+          group.durationUs
+        )
+      )
+    }
+  }
+}

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

@@ -20,12 +20,18 @@ object SubtitleUtils {
    * the app full control over text color, background, window color, edge, font, size, and position.
    */
   fun configureSubtitleView(playerView: PlayerView, context: Context, customStyle: SubtitleStyle? = null) {
+    // Resolved once and shared with the rounded-background view below. The two must agree: a
+    // `StyleSpan` is a `MetricAffectingSpan`, so italic text measures wider, and a disagreement
+    // draws the box too narrow for the glyphs in front of it.
+    val applyEmbeddedStyles = customStyle?.applyEmbeddedStyles ?: true
+
     playerView.subtitleView?.apply {
-      // Off by default so the app's style fully controls the appearance. `SubtitleView` implements
-      // this by stripping every span from each cue (`SubtitleViewUtils.removeAllEmbeddedStyling`),
-      // which also erases the formatting `SubripParser` produces for SubRip's <b>/<i>/<u>/<font>
-      // tags — so a track's inline formatting only survives when the app opts in here.
-      setApplyEmbeddedStyles(customStyle?.applyEmbeddedStyles == true)
+      // On by default now that the parser has already removed colour, size and weight
+      // (`SubtitleSpanFilter`), so what is left to keep is only italic, underline and
+      // strikethrough. Turning this off is the blunt option: `SubtitleView` implements it via
+      // `SubtitleViewUtils.removeAllEmbeddedStyling`, which strips every remaining span. It does
+      // not touch `line`/`position`/`textAlignment`, so a track's own placement survives either way.
+      setApplyEmbeddedStyles(applyEmbeddedStyles)
       // Sizes stay app-controlled either way: `setFixedTextSize` below is the single source of truth.
       setApplyEmbeddedFontSizes(false)
 
@@ -71,7 +77,7 @@ object SubtitleUtils {
             cornerRadiusDp,
             textSizeSp,
             bottomPaddingFraction,
-            customStyle.applyEmbeddedStyles
+            applyEmbeddedStyles
           )
         } else {
           setStyle(resolved)