expo-video-subtitle 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,111 @@ 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.3.0
+
+### Added
+
+- **Android:** `subtitleStyle.backgroundRadius` rounds the corners of the `backgroundColor` box, in dp.
+  One box is drawn per rendered line, so a caption that wraps gets two rounded boxes stacked on each
+  other, the way VLC and most desktop players draw them. It has no effect unless `backgroundColor` is
+  set to something that is not fully transparent, and `windowColor` is deliberately left rectangular —
+  the window is the region the caption occupies, the background is the box that hugs the text.
+
+  Media3 offers nothing for this. `SubtitlePainter` renders `backgroundColor` as an Android
+  `BackgroundColorSpan`, which the framework paints with `canvas.drawRect`, and it paints `windowColor`
+  with a `canvas.drawRect` of its own; neither takes a radius, and `SubtitlePainter` and
+  `CanvasSubtitleOutput` are package-private and final while `SubtitleView` is final, so none of it can
+  be subclassed or replaced. The background is therefore drawn by a second subtitle view inserted
+  behind the one `PlayerView` owns, fed the same cues and configured with the same typeface, text size
+  and bottom padding so the two layouts match; the box itself comes from a `LineBackgroundSpan` calling
+  `drawRoundRect`. That view pins its edge type to `EDGE_TYPE_NONE` on purpose: `SubtitlePainter` copies
+  the cue text for a second edge pass and draws both layouts whenever the edge type is `outline`,
+  `raised` or `depressed`, which would paint the box twice and make a semi-transparent colour composite
+  with itself and come out darker than asked for.
+
+  Leaving `backgroundRadius` unset takes the original code path unchanged, with no extra view and no
+  extra listener.
+
+### Changed
+
+- **Android:** the subtitle view is now reconfigured whenever a player moves between views —
+  attaching a player, entering fullscreen, leaving it. `PlayerView` re-attaches its own subtitle view
+  on `setPlayer`, so nothing needed this before; the rounded background does, because it subscribes to
+  the `Player` rather than riding on `PlayerView`, and a view that no longer drives the player would
+  otherwise keep that subscription and go on drawing cues behind a surface nobody is looking at. For
+  anyone not using `backgroundRadius` this only means the caption style is re-applied at those
+  moments, which is what it already was.
+
+## 0.2.2
+
+### Changed
+
+- The published tarball no longer carries the repo's own development configuration: `.prettierrc`,
+  `.gitattributes`, `eslint.config.js`, `tsconfig.all.json` and the two `*.tsbuildinfo` build caches
+  (260 files → 254). None of it is read from inside a consumer's `node_modules`, and
+  `eslint.config.js` would in fact throw if anything did load it, because it requires
+  `expo-module-scripts` — a devDependency, and therefore absent for consumers. Two conventions
+  combined to publish these: `.npmignore` excludes hidden *directories* but not hidden *files*, and
+  npm ignores `.gitignore` entirely once an `.npmignore` exists, so a build cache that git already
+  ignores still shipped. Nothing a consumer uses changed — the file list is otherwise byte-identical,
+  and installing the tarball into a clean project still resolves `build/`, `plugin/build/`,
+  `app.plugin.js`, `expo-module.config.json` and the Android/iOS sources.
+- Dropped the `.npmignore` entry for `oxlint.config.mjs`, which has not existed since 0.2.0.
+
+## 0.2.1
+
+### Changed
+
+- Repository tooling, with no effect on the published runtime: `npm run lint` is quiet again. Making
+  the lint step runnable in 0.2.0 exposed 377 `prettier/prettier` warnings against code that is in
+  fact correctly formatted. `eslint-config-universe` enables the `prettier/prettier` rule but supplies
+  no options of its own, and `expo-video` inherits them from the Expo monorepo's root `.prettierrc` —
+  a file that does not come along when the package is forked out to stand on its own. Prettier
+  therefore fell back to its own defaults, and every source file disagreed with them about quote style
+  and line width. Adding the upstream options as a `.prettierrc` takes the count to zero without
+  reformatting a single line.
+
+## 0.2.0
+
+### Added
+
+- **Android:** `subtitleStyle.applyEmbeddedStyles` keeps the inline formatting a subtitle track
+  carries instead of discarding it. Subtitle formats bring styling of their own — SubRip's `<b>`,
+  `<i>`, `<u>` and `<font color>` tags, and the richer per-cue styling of embedded WebVTT/TTML — and
+  until now every bit of it was thrown away so that `subtitleStyle` was the only thing deciding how
+  captions looked. `SubtitleView.setApplyEmbeddedStyles(false)` was hardcoded, and Media3 implements
+  that by removing every span from every cue, so an `.srt` written with `<i>` rendered upright.
+  Defaults to `false`, so nothing changes until you opt in. The rest of `subtitleStyle` still applies
+  underneath and `fontSize` still overrides any size the track asks for; the trade-off is that a cue
+  specifying its own colours overrides `textColor` and `windowColor` for that cue. There is no iOS
+  equivalent: `AVPlayerItem.textStyleRules` always composes with what the WebVTT cue declares.
+
+### Fixed
+
+- **Android:** a subtitle no longer drops down a line when the subtitle *below* it ends. Cues that
+  are on screen together are drawn as one block anchored at its bottom, so the moment the lower cue
+  expired the upper one fell into its place — moving the text at exactly the spot the viewer is
+  reading. Every cue now keeps the same line for its whole time on screen: the line a finished cue
+  leaves behind is held empty, and the next cue to start reclaims the lowest empty line rather than
+  stacking on top, which is what keeps the block from creeping upwards. An empty line can therefore
+  sit below — or between — the cues still on screen, and the stack resets once nothing is left on
+  screen. Cues with explicit `{\anN}` positioning are still passed through untouched.
+- **Android:** merging simultaneous SubRip cues no longer flattens their text. The cues were joined
+  through `toString()`, which erases the spans Media3's SubRip parser produces from inline tags. This
+  changed nothing on screen at the time, because the renderer stripped those spans anyway, but it
+  would have silently defeated the new `applyEmbeddedStyles` option for any overlapping cue.
+
+### Changed
+
+- Repository tooling, with no effect on the published runtime: `npm run lint` runs again. The repo
+  had no `eslint.config.js` — `expo-module configure` treats it as an optional template and never
+  creates one — while the `oxlint.config.mjs` it did have re-exported a module that
+  `expo-module-scripts@56` does not ship, so the lint step in `FORK.md` §5 had never actually
+  executed. A `.gitattributes` now pins the working copy to LF, which stops the Prettier rule from
+  reporting nearly every line of every file on a Windows checkout. The single lint error this
+  uncovered, a non-simple expression in a `useMemo` dependency list in `VideoPlayer.web.tsx`, is
+  fixed by hoisting it into a variable; the value and its identity semantics are unchanged.
+
 ## 0.1.3
 
 ### Documentation

package/FORK.md

@@ -5,9 +5,10 @@ and (b) pull a newer `expo-video` release into it **without losing the subtitle
 
 - **Baseline:** `expo-video@56.1.4` (Expo SDK 56), as published on npm.
 - **Native module name:** unchanged (`ExpoVideo`) — this is a drop-in replacement, not a coexisting package.
-- **Design principle:** the fork is deliberately **surgical and additive**. 5 new files hold almost all
-  of the logic (505 lines); the 14 touched upstream files receive ~130 added lines and only ~29 removed
-  ones. Nothing upstream is rewritten, so a version bump is a small, mechanical re-apply.
+- **Design principle:** the fork is deliberately **surgical and additive**. 7 new source files hold
+  almost all of the logic (~1,200 lines); the 19 touched upstream files receive ~450 added lines and
+  only ~44 removed ones. Nothing upstream is rewritten — the removals are call-site signatures and a
+  handful of rewritten function bodies — so a version bump is a small, mechanical re-apply.
 
 ---
 
@@ -23,17 +24,22 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 | `ios/Records/SubtitleStyle.swift` | 118 | Record for caption styling; hex→ARGB parsing; builds `[AVTextStyleRule]`. |
 | `ios/VideoPlayerSubtitleSideload.swift` | 203 | Builds the `AVMutableComposition`, downloads remote subs, SRT→WebVTT converter. |
 | `android/…/records/SubtitleSource.kt` | 54 | Record → `MediaItem.SubtitleConfiguration` + MIME resolution. |
-| `android/…/records/SubtitleStyle.kt` | 129 | Record → `CaptionStyleCompat`; hex colour parsing; font-family resolution (`res/font` → `ReactFontManager`). |
-| `android/…/utils/StackingSubtitleParser.kt` | 214 | `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. |
+| `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. |
+| `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". |
+| `.gitattributes` | 21 | Pins the working copy to LF. Git stores these files with LF, but a Windows checkout rewrites them to CRLF and the Prettier rule `npm run lint` enforces wants LF, which drowned the output in ~2800 "Delete `␍`" warnings. |
+| `.prettierrc` | 7 | The Expo monorepo's Prettier options, which the sources were formatted with. `eslint-config-universe` turns the `prettier/prettier` rule *on* but supplies no options, and upstream inherits them from the monorepo root — a file that does not come along when the package is forked out on its own. Without this, Prettier falls back to its own defaults and reports 377 warnings against correctly formatted code. Only `printWidth` and `singleQuote` differ from Prettier 2's defaults today; the rest are written out because they are what upstream uses, and `trailingComma` guards against a bump to Prettier 3, whose default is `"all"`. |
 
 ### Modified — upstream files carrying fork edits (re-apply these after a sync)
 
 | File | Δ | What to re-apply |
 | --- | --- | --- |
 | `src/VideoPlayer.types.ts` | +59 | `subtitleTracks?: SubtitleSource[]` on `VideoSourceObject`; the exported `SubtitleSource` type. |
-| `src/VideoView.types.ts` | +94 | `subtitleStyle?: SubtitleStyle` on `VideoViewProps`; `SubtitleStyle` + `SubtitleEdgeType` types. |
+| `src/VideoView.types.ts` | +129 | `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.** |
 | `ios/Records/VideoSource.swift` | +3 | `@Field var subtitleTracks: [SubtitleSource]?`. |
 | `ios/VideoPlayerItem.swift` | +17 / −2 | In the **async** init: hoist `isHls` to a local, and build the sideload composition for non-HLS/non-DRM sources before `super.init(asset:)`. |
@@ -41,14 +47,16 @@ 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` | +27 / −16 | `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. |
-| `android/…/VideoView.kt` | +12 / −5 | `subtitleStyle` property; pass it at all 4 `configureSubtitleView` call sites + the captioning listener. |
+| `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/…/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. |
+| `android/…/player/VideoPlayer.kt` | +13 / −2 | In `changeVideoView`, after `switchTargetView`: release the subtitle view the player is leaving and reconfigure the one it moves to. **Load-bearing for `backgroundRadius`** — that feature subscribes to the `Player` directly rather than riding on `PlayerView.setPlayer`, so a view that no longer drives the player keeps its subscription and goes on drawing stale cues. This is the choke point for every player move except entering fullscreen, which bypasses it (see `FullscreenPlayerActivity`). |
 | `android/…/player/VideoPlayerSubtitles.kt` | +14 / −8 | Apply the cleared track-selection parameters when the requested subtitle id matches nothing, instead of only inside the `format?.let` block. |
-| `android/…/FullscreenPlayerActivity.kt` | +3 / −3 | Pass `videoView.subtitleStyle` at its 2 call sites + the captioning listener. |
+| `android/…/FullscreenPlayerActivity.kt` | +15 / −3 | Pass `videoView.subtitleStyle` at its 2 call sites + the captioning listener. Also release the originating `VideoView`'s subtitle view right after its own `switchTargetView` — this path bypasses `changeVideoView`, so without it the player carries two cue listeners for the whole time it is fullscreen — and release this activity's own in `onDestroy`. |
 | `package.json` | — | Fork identity + build scripts — see §3. |
 | `expo-module.config.json` | — | **Android `publication` block removed** — see §3. |
+| `.npmignore` | +21 / −1 | A "Fork additions" block excluding the repo's own development config from the tarball: `.gitattributes`, `.prettierrc`, `eslint.config.js`, `tsconfig.all.json` and `*.tsbuildinfo`. Needed because the generated file only excludes hidden *directories* (`/.*/`), and because npm ignores `.gitignore` outright once an `.npmignore` exists — so the tsc build caches shipped despite git ignoring them. The `−1` drops the entry for `oxlint.config.mjs`, deleted in 0.2.0. |
 | `README.md`, `CHANGELOG.md` | — | Fork docs; do not take upstream's. |
 
 ### Removed — upstream artifacts deliberately dropped
@@ -58,6 +66,7 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 | `local-maven-repo/` (Android AAR) | Upstream ships a **precompiled** `expo.modules.video` AAR. If present, Gradle resolves it and **silently ignores the modified Kotlin**. |
 | `prebuilds/` (iOS XCFramework) | Same trap on iOS: CocoaPods links the prebuilt `ExpoVideo.xcframework` instead of compiling the modified Swift. |
 | `spm.config.json` | Swift Package Manager prebuild config; meaningless once we build from source. |
+| `oxlint.config.mjs` | Re-exported `expo-module-scripts/oxlint.config.base`, which does not exist in `expo-module-scripts@56` — that package lints with ESLint and ships no oxlint base. A dead file that only misled readers into thinking oxlint was the configured linter. |
 
 > **This is the single most important thing to preserve.** If a sync re-introduces the `publication`
 > block, `local-maven-repo/` or `prebuilds/`, the app keeps building — it just runs **upstream's**
@@ -105,7 +114,11 @@ Then re-apply the fork:
    with real deletions are `SubtitleUtils.kt` (function rewritten), `VideoView.kt`/`FullscreenPlayerActivity.kt`
    (call-site signatures), `VideoPlayerItem.swift` (`isHls` hoist) and the ts-declarations shim.
 7. **Remove the Android `publication` block** from `expo-module.config.json`.
-8. **Restore the fork's `package.json`** (§3) and keep `README.md`, `CHANGELOG.md`, `LICENSE`, `FORK.md`.
+8. **Restore the fork's `package.json`** (§3) and keep `README.md`, `CHANGELOG.md`, `LICENSE`,
+   `FORK.md`, `eslint.config.js`, `.gitattributes` and `.prettierrc`. Step 3 only replaces
+   `src ios android plugin`, so the root-level files survive on their own — but confirm it, because a
+   missing `eslint.config.js` breaks `npm run lint` in a way that reads like a tooling bug rather than
+   a lost file, and a missing `.prettierrc` buries the output in warnings against correct code.
 9. Update the baseline version in this file, the README, and add a `CHANGELOG.md` entry.
 10. Verify with §5, then commit.
 
@@ -154,29 +167,107 @@ entry, in §1 of this file and in the README's intro line.
 
 ## 5. Verification
 
-Run all four. The native ones are what actually prove the fork survived the sync.
+> **This package is standalone.** Nothing in this section may reach into an unrelated project's
+> checkout. Verifying by overlaying the package onto some other app's `node_modules` silently mutates
+> a repository that has nothing to do with this one, and couples a public npm package to a private
+> codebase. If a step needs a host app, create a throwaway one for that purpose.
+
+### Self-contained — run these on every change
 
 ```bash
 npm run typecheck        # must be clean
-npm run lint
+npm run lint             # expect zero output: no errors and no warnings
 npm pack --dry-run       # expect build/, plugin/build/, LICENSE, native sources;
-                         # NO node_modules, prebuilds, local-maven-repo
+                         # NO node_modules, prebuilds, local-maven-repo;
+                         # 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
+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.
+
+`npm run lint` depends on two root files that upstream does not carry, both described in §1:
+`eslint.config.js` (without it ESLint refuses to run at all) and `.prettierrc` (without it Prettier
+falls back to its own defaults and reports hundreds of warnings against correctly formatted code).
+Neither is created by `expo-module configure`, so a sync that loses one breaks this step in a way
+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.
+
+### Android — compiling the parser without a host app
+
+`utils/StackingSubtitleParser.kt` imports only `android.text.*` and `androidx.media3.*`, so it
+compiles on its own. This is the file that carries almost all of the Android subtitle logic, and it
+is the one most likely to break when Media3 changes `SubtitleParser`, `CuesWithTiming` or `Cue`.
+
+In a scratch directory, with `<media3>` set to `androidxMedia3Version` from `android/build.gradle`
+and `<sdk>` to an installed Android platform:
+
+```kotlin
+// settings.gradle.kts -> rootProject.name = "kotlincheck"
+// build.gradle.kts:
+import java.util.zip.ZipFile
+
+plugins { kotlin("jvm") version "2.1.21" }
+repositories { google(); mavenCentral() }
+
+val media3: Configuration by configurations.creating
+dependencies {
+  media3("androidx.media3:media3-common:<media3>")
+  media3("androidx.media3:media3-extractor:<media3>")
+  media3("androidx.media3:media3-ui:<media3>")
+}
+
+// A plain JVM compile cannot read .aar, so pull classes.jar out of each one.
+val unpacked = layout.buildDirectory.dir("unpacked")
+val unpackAars by tasks.registering {
+  outputs.dir(unpacked)
+  doLast {
+    val out = unpacked.get().asFile.also { it.deleteRecursively(); it.mkdirs() }
+    media3.forEach { f ->
+      if (f.name.endsWith(".aar")) {
+        ZipFile(f).use { zip ->
+          zip.getEntry("classes.jar")?.let { e ->
+            zip.getInputStream(e).use { it.copyTo(File(out, f.name.removeSuffix(".aar") + ".jar").outputStream()) }
+          }
+        }
+      } else if (f.name.endsWith(".jar")) f.copyTo(File(out, f.name), overwrite = true)
+    }
+  }
+}
+
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
+  dependsOn(unpackAars)
+  libraries.from(fileTree(unpacked) { include("*.jar") }, files("<sdk>/platforms/android-36/android.jar"))
+}
 ```
 
-**Native compile** — because both platforms default to precompiled artifacts, you must build from
-source inside a host app. Overlay this package into the app's `node_modules/expo-video`, then:
+Copy the file to `src/main/kotlin/expo/modules/video/utils/` and run `gradle compileKotlin` —
+expect `BUILD SUCCESSFUL`. Because the class implements Media3's `SubtitleParser`, a successful
+build also proves the three overrides still match that Media3 version's interface.
+
+The rest of the Android sources import `expo.modules.kotlin` and `com.facebook.react`, neither of
+which is on a public Maven repository, so they cannot be checked this way — a full build is the only
+option for them.
+
+### Full native build — needs a throwaway host app
+
+Both platforms default to precompiled artifacts, so a complete check means building from source in a
+host app. Create one for this purpose (`npx create-expo-app`), install this package into it, and
+confirm §1's "Removed" artifacts are absent from the installed copy:
 
 ```bash
 # Android — expect BUILD SUCCESSFUL
-cd <app>/android && ./gradlew :expo-video:compileDebugKotlin
+cd <scratch-app>/android && ./gradlew :expo-video-subtitle:compileDebugKotlin
 
 # iOS — expect BUILD SUCCEEDED
-cd <app>/ios && pod install
+cd <scratch-app>/ios && pod install
 xcodebuild -project Pods/Pods.xcodeproj -target ExpoVideo -sdk iphoneos \
   -configuration Debug build CODE_SIGNING_ALLOWED=NO
 ```
 
-Back up `node_modules/expo-video` first and restore it (plus `pod install`) afterwards.
+`npm pack` the fork and install the tarball rather than editing the app's `node_modules` in place,
+so the thing you compile is exactly what a consumer would receive.
 
 **Smoke test in the app:** an MP4 source with `subtitleTracks` must list the tracks in
 `player.availableSubtitleTracks`, render when selected via `player.subtitleTrack`, and visibly change

package/README.md

@@ -89,6 +89,25 @@ Nah, ayo pergi.                     <- started earlier
 
 This matches how WebVTT stacks cues, and behaves the same on Android and iOS. Cues that carry
 explicit positioning (SubRip's `{\anN}` tags) are left where they were placed and are not merged.
+Any inline formatting the merged cues carry is preserved, so it survives an overlap unchanged — see
+[Inline formatting from the track](#inline-formatting-from-the-track) for when that formatting renders.
+
+**A cue never changes line while it is on screen** (Android). Because the block is anchored at its
+bottom, a cue would otherwise drop down the moment the cue *below* it ended — moving the text you are
+reading at that moment. The line a finished cue leaves behind is held empty instead, and the next cue
+to start reclaims the lowest empty line rather than stacking on top:
+
+```
+Apa mereka berdua berteman, ya?     both on screen
+Nah, ayo pergi.
+
+Apa mereka berdua berteman, ya?     the lower cue ended — the upper one stays put
+                                    (held empty, reclaimed by whichever cue starts next)
+```
+
+The empty line can also sit *between* two cues when the middle one finishes first. Once nothing is
+left on screen, the stack resets and the next cue starts from the bottom again. This is Android-only;
+on iOS the system renderer decides the layout.
 
 ## Styling subtitles
 
@@ -100,6 +119,7 @@ Pass a `subtitleStyle` prop to `VideoView`. It applies to whichever subtitle tra
   subtitleStyle={{
     textColor: '#FFFFFF',
     backgroundColor: '#000000A0', // box drawn behind the text
+    backgroundRadius: 8,          // Android only — corner radius of that box, in dp
     windowColor: 'transparent',   // background of the whole cue region
     fontSize: 20,                 // Android: absolute sp · iOS: percent relative to default (100 = default)
     fontFamily: 'Helvetica',
@@ -107,6 +127,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"
   }}
 />
 ```
@@ -115,7 +136,47 @@ Pass a `subtitleStyle` prop to `VideoView`. It applies to whichever subtitle tra
 | --- | --- | --- |
 | Implementation | `CaptionStyleCompat` on the `PlayerView` subtitle view | `AVPlayerItem.textStyleRules` |
 
-> **iOS note:** styling relies on `textStyleRules`, which only affects WebVTT captions the system renders. The device's **Settings → Accessibility → Subtitles & Captioning** preferences take precedence when enabled. `edgeType`/`edgeColor` and `bottomOffset` are Android-only.
+> **iOS note:** styling relies on `textStyleRules`, which only affects WebVTT captions the system renders. The device's **Settings → Accessibility → Subtitles & Captioning** preferences take precedence when enabled. `edgeType`/`edgeColor`, `bottomOffset`, `backgroundRadius` and `applyEmbeddedStyles` are Android-only.
+
+### Rounded background
+
+`backgroundRadius` rounds the corners of the `backgroundColor` box. It is a dp value, and it does
+nothing unless `backgroundColor` is set to something that isn't fully transparent:
+
+```tsx
+<VideoView player={player} subtitleStyle={{ backgroundColor: '#000000A0', backgroundRadius: 8 }} />
+```
+
+One box is drawn per rendered line, so a caption that wraps onto two lines gets two rounded boxes
+stacked directly on top of each other — the way VLC and most desktop players draw them. Boxes on
+adjacent lines share an edge; the rounding is on the outside of the block.
+
+`windowColor` is **not** affected and stays rectangular. The two are different things: the window is
+the region the caption occupies, the background is the box that hugs the text.
+
+> Media3 has no rounded-caption support of its own — it paints both the background and the window
+> with `canvas.drawRect`. This option is implemented by rendering the background in a second
+> subtitle view placed behind the text, so it costs one extra view and one cue listener per player,
+> and only while it is switched on. Leaving `backgroundRadius` unset takes the original code path
+> exactly as before.
+
+### 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:
+
+```tsx
+<VideoView player={player} subtitleStyle={{ textColor: '#FFFFFF', applyEmbeddedStyles: true }} />
+```
+
+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.
+
+On iOS this is not configurable: `AVPlayerItem.textStyleRules` composes with whatever the WebVTT cue
+declares, so a track's inline formatting always renders.
 
 ### Fonts
 

package/android/src/main/java/expo/modules/video/FullscreenPlayerActivity.kt

@@ -83,6 +83,12 @@ class FullscreenPlayerActivity : Activity(), VideoManagerListener {
     videoPlayer = videoView.videoPlayer
     videoPlayer?.player?.let {
       PlayerView.switchTargetView(it, videoView.playerView, playerView)
+      // This bypasses `VideoPlayer.changeVideoView`, so the handover it performs has to be done here:
+      // the view we took the player from keeps its own `Player` subscription otherwise, leaving two
+      // listeners on one player for the whole time we are in fullscreen. `onPostCreate` configures
+      // this activity's own player view, and `exitFullscreen` restores the original through
+      // `changeVideoView`.
+      SubtitleUtils.releaseSubtitleView(videoView.playerView)
       videoPlayer?.hasBeenDisconnectedFromVideoView() // The video player is disconnected. We are only using the ExoPlayer it contained
     }
 
@@ -180,6 +186,12 @@ class FullscreenPlayerActivity : Activity(), VideoManagerListener {
       captioningChangeListener = null
     }
 
+    // Release whatever `configureSubtitleView` attached to this activity's own player view; the
+    // `VideoView` it came from keeps its own, which `exitFullscreen` reconfigures.
+    if (::playerView.isInitialized) {
+      SubtitleUtils.releaseSubtitleView(playerView)
+    }
+
     if (::videoView.isInitialized) {
       videoView.exitFullscreen()
     }

package/android/src/main/java/expo/modules/video/VideoView.kt

@@ -389,6 +389,10 @@ open class VideoView(context: Context, appContext: AppContext, useTextureView: B
       captioningChangeListener = null
     }
 
+    // Release whatever `configureSubtitleView` attached to the player view. `onAttachedToWindow`
+    // reconfigures from scratch, so there is nothing to preserve across a detach.
+    SubtitleUtils.releaseSubtitleView(playerView)
+
     // Clean up window focus listener
     decorView.onFocusChangeListener = null
 

package/android/src/main/java/expo/modules/video/player/VideoPlayer.kt

@@ -46,6 +46,7 @@ import expo.modules.video.records.SeekTolerance
 import expo.modules.video.records.TimeUpdate
 import expo.modules.video.records.VideoSource
 import expo.modules.video.utils.MutableWeakReference
+import expo.modules.video.utils.SubtitleUtils
 import expo.modules.video.records.VideoTrack
 import expo.modules.video.utils.buildBasicMediaSession
 import kotlinx.coroutines.DelicateCoroutinesApi
@@ -406,8 +407,18 @@ class VideoPlayer(val context: Context, appContext: AppContext, source: VideoSou
   }
 
   fun changeVideoView(videoView: VideoView?) {
-    PlayerView.switchTargetView(player, currentVideoView?.playerView, videoView?.playerView)
+    val previousPlayerView = currentVideoView?.playerView
+    PlayerView.switchTargetView(player, previousPlayerView, videoView?.playerView)
     currentVideoView = videoView
+
+    // Subtitle rendering has to follow the player, and only after the swap so the rebind below reads
+    // the new `playerView.player`. `PlayerView` re-attaches its own subtitle view on `setPlayer`, but
+    // the rounded background subscribes to the `Player` directly, so a view that no longer drives the
+    // player would keep that subscription and go on drawing stale cues.
+    if (previousPlayerView != null && previousPlayerView !== videoView?.playerView) {
+      SubtitleUtils.releaseSubtitleView(previousPlayerView)
+    }
+    videoView?.let { SubtitleUtils.configureSubtitleView(it.playerView, it.context, it.subtitleStyle) }
   }
 
   fun prepare() {

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

@@ -26,7 +26,20 @@ class SubtitleStyle(
   @Field val bold: Boolean = false,
   @Field val edgeType: String? = null,
   @Field val edgeColor: String? = null,
-  @Field val bottomOffset: Float? = null
+  @Field val bottomOffset: Float? = null,
+  /**
+   * Corner radius, in dp, of the [backgroundColor] box. Consumed by
+   * [expo.modules.video.utils.SubtitleUtils.configureSubtitleView] rather than [toCaptionStyle]:
+   * [CaptionStyleCompat] has no radius, and Media3 draws the box with `canvas.drawRect`, so a rounded
+   * one has to be rendered separately — see [expo.modules.video.utils.RoundedSubtitleBackground].
+   */
+  @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.
+   */
+  @Field val applyEmbeddedStyles: Boolean = false
 ) : Record, Serializable {
   /**
    * Builds a [CaptionStyleCompat], falling back to [base] for any unspecified property so that