expo-video-subtitle 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+This package is a fork of [`expo-video`](https://github.com/expo/expo/tree/main/packages/expo-video).
+Changes inherited from the upstream base version are not repeated here — see the
+[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.1.0 — Unreleased
+
+Initial release. Based on `expo-video` **56.1.4** (Expo SDK 56).
+
+### Added
+
+- **External (sideloaded) subtitles** via `VideoSource.subtitleTracks`. Attach WebVTT or SubRip
+  subtitle files (local or remote) to any source — most importantly progressive **MP4**, which,
+  unlike HLS/DASH manifests, cannot advertise its own subtitle renditions. Sideloaded tracks are
+  merged into the media and surface through `availableSubtitleTracks`, so they are selected with
+  `subtitleTrack` exactly like embedded tracks.
+  - Android: merged with `MediaItem.SubtitleConfiguration` (Media3 wraps them in a `MergingMediaSource`).
+  - iOS: merged into an `AVMutableComposition` as a `.text` track. SRT is converted to WebVTT, remote
+    files are cached locally first, and per-track time ranges are clamped to the video duration.
+    Applies to progressive, non-DRM sources on the asynchronous loading path.
+- **Custom subtitle styling** via the `VideoView` `subtitleStyle` prop: `textColor`, `backgroundColor`,
+  `windowColor`, `fontSize`, `fontFamily`, `bold`, `edgeType`, `edgeColor`, and `bottomOffset`.
+  Applies to embedded and sideloaded tracks alike.
+  - Android: `CaptionStyleCompat` on the `PlayerView` subtitle view.
+  - iOS: `AVPlayerItem.textStyleRules`.
+
+### Changed
+
+- The Android `publication` block and the iOS prebuild artifacts are removed, so the modified
+  Kotlin and Swift are compiled from source instead of resolving a precompiled AAR/XCFramework.

package/FORK.md

@@ -0,0 +1,149 @@
+# Fork maintenance guide
+
+Everything you need to know to (a) understand exactly how this package differs from `expo-video`,
+and (b) pull a newer `expo-video` release into it **without losing the subtitle work**.
+
+- **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.
+
+---
+
+## 1. Change manifest
+
+Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/removed lines.
+
+### Added — new files (never conflict on sync, just copy them over)
+
+| File | Lines | Purpose |
+| --- | --- | --- |
+| `ios/Records/SubtitleSource.swift` | 32 | Record for one sideloaded subtitle; `isSrt` detection. |
+| `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` | 98 | Record → `CaptionStyleCompat`; hex colour parsing. |
+| `FORK.md`, `LICENSE` | — | This guide; MIT licence (upstream copyright preserved). |
+
+### 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/index.ts` | +2 | Export `SubtitleStyle`, `SubtitleEdgeType` (`SubtitleSource` rides on `export type *`). |
+| `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:)`. |
+| `ios/VideoPlayer.swift` | +15 | `subtitleStyle` property + `applySubtitleStyle()`; re-apply `textStyleRules` in `onItemChanged`. |
+| `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. |
+| `android/…/VideoView.kt` | +12 / −5 | `subtitleStyle` property; pass it at all 4 `configureSubtitleView` call sites + the captioning listener. |
+| `android/…/VideoModule.kt` | +4 | `Prop("subtitleStyle")`. |
+| `android/…/FullscreenPlayerActivity.kt` | +3 / −3 | Pass `videoView.subtitleStyle` at its 2 call sites + the captioning listener. |
+| `package.json` | — | Fork identity + build scripts — see §3. |
+| `expo-module.config.json` | — | **Android `publication` block removed** — see §3. |
+| `README.md`, `CHANGELOG.md` | — | Fork docs; do not take upstream's. |
+
+### Removed — upstream artifacts deliberately dropped
+
+| Path | Why |
+| --- | --- |
+| `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. |
+
+> **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**
+> video module, and every subtitle feature silently disappears. Verify with §4.
+
+---
+
+## 2. Syncing a newer `expo-video`
+
+```bash
+# 0. Start clean, on a branch, with the current state tagged for easy diffing.
+git checkout -b sync/expo-video-<new-version>
+git tag pre-sync-<new-version>
+
+# 1. Get the target version's source (must be the EXACT version your app uses).
+npm pack expo-video@<new-version>
+tar -xzf expo-video-<new-version>.tgz          # -> ./package
+
+# 2. Record the fork's edits BEFORE overwriting, so you can re-apply them.
+git diff pre-sync-<new-version> -- src ios android > /tmp/fork.patch   # or just use §1's table
+
+# 3. Replace the upstream-owned trees.
+rm -rf src ios android plugin
+cp -R package/src package/ios package/android .
+mkdir -p plugin && cp -R package/plugin/src plugin/src
+cp package/plugin/tsconfig.json plugin/tsconfig.json
+cp package/expo-module.config.json package/app.plugin.js package/tsconfig.json .
+
+# 4. Drop the precompiled artifacts (see §1 "Removed"). NEVER skip this.
+rm -rf local-maven-repo prebuilds spm.config.json package
+```
+
+Then re-apply the fork:
+
+5. **Copy the 5 new files back** (they are self-contained — `git checkout pre-sync-<v> -- <path>` works).
+6. **Re-apply the 14 modified files** using the table in §1. Most are pure insertions; the only ones
+   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`.
+9. Update the baseline version in this file, the README, and add a `CHANGELOG.md` entry.
+10. Verify with §4, then commit.
+
+---
+
+## 3. `package.json` invariants
+
+Upstream's `package.json` will overwrite these if copied blindly. Keep:
+
+- `name: expo-video-subtitle`, the fork's `version`, `author`, `contributors`, `homepage`, `repository`, `bugs`.
+- `"build": "expo-module build && npm run build:plugin"` and `"build:plugin": "tsc -p plugin"`.
+  **`expo-module build` only compiles `src/` → `build/`.** Without `build:plugin` there is no
+  `plugin/build/withExpoVideo.js`, and `app.plugin.js` (`require('./plugin/build/withExpoVideo')`)
+  throws for every consumer during config resolution.
+- `"prepublishOnly": "npm run clean && npm run build"` so a publish can never ship a stale `build/`.
+- `expo-module-scripts` must track the SDK (56.x for SDK 56). An older major provides a different CLI
+  (`expo-build` vs `expo-module build`) and the build breaks.
+- `plugin/index.js` + `plugin/index.d.ts` shims (upstream layout parity).
+
+---
+
+## 4. Verification
+
+Run all four. The native ones are what actually prove the fork survived the sync.
+
+```bash
+npm run typecheck        # must be clean
+npm run lint
+npm pack --dry-run       # expect build/, plugin/build/, LICENSE, native sources;
+                         # NO node_modules, prebuilds, local-maven-repo
+```
+
+**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:
+
+```bash
+# Android — expect BUILD SUCCESSFUL
+cd <app>/android && ./gradlew :expo-video:compileDebugKotlin
+
+# iOS — expect BUILD SUCCEEDED
+cd <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.
+
+**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
+appearance when `subtitleStyle` is set. If tracks are missing on Android, `Format.id`/`Format.language`
+are probably null (see `SubtitleTrack.fromFormat`); if they are missing on iOS, the composition likely
+fell back to the plain asset — check the `[expo-video]` warnings.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# expo-video-subtitle
+
+A cross-platform, performant video component for React Native and Expo with Web support.
+
+This package is a fork of `expo-video` (SDK 56 / `56.1.4`) that adds two subtitle capabilities on top of the original module:
+
+1. **External (sideloaded) subtitles** — attach subtitle files to any source, including progressive **MP4** (which, unlike HLS/DASH, cannot advertise its own subtitle renditions).
+2. **Custom subtitle styling** — control the text color, background, font, edge, and position of the rendered captions.
+
+Everything else in the API is identical to `expo-video`, so the [upstream documentation](https://docs.expo.dev/versions/latest/sdk/video/) applies to all other props and methods.
+
+## What's different from `expo-video`
+
+Nothing in the existing API was renamed, removed, or given new behaviour — the changes are purely
+additive, plus one packaging change.
+
+**Added**
+
+| API | Where | Description |
+| --- | --- | --- |
+| `subtitleTracks?: SubtitleSource[]` | `VideoSource` | Attach external subtitle files to a source. See [Sideloading subtitles onto MP4](#sideloading-subtitles-onto-mp4). |
+| `subtitleStyle?: SubtitleStyle` | `VideoView` prop | Customise caption appearance. See [Styling subtitles](#styling-subtitles). |
+| `SubtitleSource`, `SubtitleStyle`, `SubtitleEdgeType` | exported types | Supporting TypeScript types. |
+
+**Changed**
+
+- **Native code is compiled from source.** Upstream ships a precompiled Android AAR and iOS
+  XCFramework; those are removed here, because a prebuilt binary would ignore the modified native
+  code. Expect your first native build after installing to take longer than with `expo-video`.
+
+**Removed**
+
+- Nothing from the public API. Only the upstream prebuild artifacts (`local-maven-repo/`,
+  `prebuilds/`, `spm.config.json`) — see above.
+
+Maintaining this fork or pulling in a newer `expo-video`? See [FORK.md](./FORK.md) for the full change
+manifest and the upstream sync procedure.
+
+## Installation
+
+```
+npm install expo-video-subtitle
+```
+
+The native module registers under the same name as `expo-video` (`ExpoVideo`). It is a **drop-in replacement**: a project must use either `expo-video` or `expo-video-subtitle`, not both. Remove `expo-video` from your dependencies and import from `expo-video-subtitle` instead:
+
+```tsx
+import { useVideoPlayer, VideoView } from 'expo-video-subtitle';
+```
+
+## Sideloading subtitles onto MP4
+
+Pass a `subtitleTracks` array on the `VideoSource`. The tracks are merged into the media and surface through `player.availableSubtitleTracks`, so they are selected the same way as embedded tracks.
+
+```tsx
+import { useVideoPlayer, VideoView } from 'expo-video-subtitle';
+
+const player = useVideoPlayer({
+  uri: 'https://cdn.example.com/movie.mp4',
+  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' },
+  ],
+});
+
+// After the source loads, pick a track:
+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), and optional `default`.
+
+| | 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** |
+
+> **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.
+
+## 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`.
+
+```tsx
+<VideoView
+  player={player}
+  subtitleStyle={{
+    textColor: '#FFFFFF',
+    backgroundColor: '#000000A0', // box drawn behind the text
+    windowColor: 'transparent',   // background of the whole cue region
+    fontSize: 20,                 // Android: absolute sp · iOS: percent relative to default (100 = default)
+    fontFamily: 'Helvetica',
+    bold: true,
+    edgeType: 'outline',          // 'none' | 'outline' | 'dropShadow' | 'raised' | 'depressed'
+    edgeColor: '#000000',
+    bottomOffset: 0.1,            // Android only — fraction of the view height (0–1)
+  }}
+/>
+```
+
+| Mechanism | Android | iOS |
+| --- | --- | --- |
+| 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.
+
+## License
+
+MIT. Based on [`expo-video`](https://github.com/expo/expo/tree/main/packages/expo-video) by 650 Industries, Inc.

package/android/build.gradle

@@ -0,0 +1,32 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'host.exp.exponent'
+version = '56.1.4'
+
+android {
+  namespace "expo.modules.video"
+  defaultConfig {
+    versionCode 1
+    versionName '56.1.4'
+  }
+}
+
+dependencies {
+  implementation 'com.facebook.react:react-android'
+
+  // Remember to keep this in sync with the version in `expo-audio`
+  def androidxMedia3Version = "1.9.0"
+  implementation "androidx.media3:media3-session:${androidxMedia3Version}"
+  implementation "androidx.media3:media3-exoplayer:${androidxMedia3Version}"
+  implementation "androidx.media3:media3-exoplayer-dash:${androidxMedia3Version}"
+  implementation "androidx.media3:media3-exoplayer-hls:${androidxMedia3Version}"
+  implementation "androidx.media3:media3-ui:${androidxMedia3Version}"
+  implementation "androidx.media3:media3-datasource-okhttp:${androidxMedia3Version}"
+
+  def fragment_version = "1.8.9"
+  implementation "androidx.fragment:fragment:$fragment_version"
+  implementation "androidx.fragment:fragment-ktx:$fragment_version"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+
+  <application>
+    <activity android:name=".FullscreenPlayerActivity"
+      android:supportsPictureInPicture="true"
+      android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation|navigation"
+      android:theme="@style/Fullscreen" />
+  </application>
+</manifest>

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

@@ -0,0 +1,258 @@
+package expo.modules.video
+
+import android.app.Activity
+import android.content.pm.ActivityInfo
+import android.content.res.Configuration
+import android.os.Build
+import android.os.Bundle
+import android.content.Context
+import android.util.Log
+import android.view.View
+import android.view.accessibility.CaptioningManager
+import android.view.WindowInsets
+import android.view.WindowInsetsController
+import android.widget.ImageButton
+import androidx.media3.ui.PlayerView
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.video.listeners.VideoManagerListener
+import expo.modules.video.player.VideoPlayer
+import expo.modules.video.records.FullscreenOptions
+import expo.modules.video.utils.FullscreenActivityOrientationHelper
+import expo.modules.video.utils.SubtitleUtils
+import expo.modules.video.utils.applyPiPParams
+import expo.modules.video.utils.applyRectHint
+import expo.modules.video.utils.calculatePiPAspectRatio
+import expo.modules.video.utils.calculateRectHint
+import expo.modules.video.managers.VideoManager
+
+@androidx.annotation.OptIn(androidx.media3.common.util.UnstableApi::class)
+class FullscreenPlayerActivity : Activity(), VideoManagerListener {
+  private lateinit var mContentView: View
+  private var videoViewId: String? = null
+  private var videoPlayer: VideoPlayer? = null
+  private lateinit var playerView: PlayerView
+  private lateinit var videoView: VideoView
+  private var didFinish = false
+  private var wasAutoPaused = false
+  private var isStopped = false
+  private lateinit var options: FullscreenOptions
+  private var orientationHelper: FullscreenActivityOrientationHelper? = null
+  private var captioningChangeListener: CaptioningManager.CaptioningChangeListener? = null
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+
+    try {
+      videoViewId = intent.getStringExtra(VideoManager.INTENT_PLAYER_KEY)
+        ?: throw FullScreenVideoViewNotFoundException()
+
+      options = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+        intent.getSerializableExtra(INTENT_FULLSCREEN_OPTIONS_KEY, FullscreenOptions::class.java)
+          ?: throw FullScreenOptionsNotFoundException()
+      } else {
+        @Suppress("DEPRECATION")
+        intent.getSerializableExtra(INTENT_FULLSCREEN_OPTIONS_KEY) as? FullscreenOptions
+          ?: throw FullScreenOptionsNotFoundException()
+      }
+
+      videoView = videoViewId?.let { VideoManager.getVideoView(it) }
+        ?: throw FullScreenVideoViewNotFoundException()
+
+      orientationHelper = FullscreenActivityOrientationHelper(
+        this,
+        options,
+        onShouldAutoExit = {
+          finish()
+        },
+        onShouldReleaseOrientation = {
+          requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
+        }
+      )
+      orientationHelper?.startOrientationEventListener()
+    } catch (e: CodedException) {
+      Log.e("ExpoVideo", "${e.message}", e)
+      finish()
+      return
+    }
+
+    setContentView(R.layout.fullscreen_player_activity)
+    mContentView = findViewById(R.id.enclosing_layout)
+    playerView = findViewById(R.id.player_view)
+    requestedOrientation = options.orientation.toActivityOrientation()
+
+    videoPlayer = videoView.videoPlayer
+    videoPlayer?.player?.let {
+      PlayerView.switchTargetView(it, videoView.playerView, playerView)
+      videoPlayer?.hasBeenDisconnectedFromVideoView() // The video player is disconnected. We are only using the ExoPlayer it contained
+    }
+
+    videoViewId?.let { VideoManager.registerFullscreenPlayerActivity(it, this) }
+    VideoManager.registerListener(this)
+    playerView.player?.let {
+      val aspectRatio = calculatePiPAspectRatio(it.videoSize, playerView.width, playerView.height, videoView.contentFit)
+      applyPiPParams(this, videoView.autoEnterPiP, aspectRatio)
+    }
+  }
+
+  override fun onPostCreate(savedInstanceState: Bundle?) {
+    super.onPostCreate(savedInstanceState)
+    hideStatusBar()
+    setupFullscreenButton()
+    val requiresLinearPlayback = videoPlayer?.requiresLinearPlayback ?: false
+    val buttonConfig = videoView.buttonOptions.copy(showBottomBar = true) // Always show bottom bar in fullscreen mode so user can exit
+    playerView.applyButtonOptions(buttonConfig, requiresLinearPlayback)
+    playerView.setTimeBarInteractive(requiresLinearPlayback)
+    playerView.addOnLayoutChangeListener { _, _, _, _, _, _, _, _, _ ->
+      // On every re-layout ExoPlayer makes the timeBar interactive.
+      // We need to disable it to keep scrubbing off.
+      playerView.setTimeBarInteractive(requiresLinearPlayback)
+    }
+    playerView.setShowSubtitleButton(videoView.buttonOptions.showSubtitles ?: videoView.currentTrackHasSubtitles)
+
+    // Configure subtitle view to fix sizing issues with embedded styles (same as VideoView)
+    SubtitleUtils.configureSubtitleView(playerView, this, videoView.subtitleStyle)
+
+    // Set up listener for accessibility caption changes
+    setupCaptioningChangeListener()
+
+    playerView.addOnLayoutChangeListener { _, _, _, _, _, _, _, _, _ ->
+      applyRectHint(this, calculateRectHint(playerView))
+    }
+  }
+
+  override fun finish() {
+    super.finish()
+    didFinish = true
+    videoViewId?.let {
+      try {
+        VideoManager.getVideoView(it).attachPlayer()
+      } catch (e: VideoViewNotFoundException) {
+        Log.w("ExpoVideo", "VideoView $it already unmounted when finishing fullscreen — skipping attachPlayer")
+      }
+    }
+
+    // Disable the exit transition
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+      overrideActivityTransition(OVERRIDE_TRANSITION_CLOSE, 0, 0)
+    } else {
+      @Suppress("DEPRECATION")
+      overridePendingTransition(0, 0)
+    }
+  }
+
+  override fun onResume() {
+    orientationHelper?.startOrientationEventListener()
+    playerView.useController = true
+    // Reconfigure subtitles when resuming (handles returning from settings)
+    SubtitleUtils.configureSubtitleView(playerView, this, videoView.subtitleStyle)
+    super.onResume()
+  }
+
+  override fun onPause() {
+    if (videoPlayer?.staysActiveInBackground != true && !didFinish) {
+      wasAutoPaused = videoPlayer?.player?.isPlaying == true
+      if (wasAutoPaused) {
+        playerView.useController = false
+        videoPlayer?.player?.pause()
+      }
+    }
+    orientationHelper?.stopOrientationEventListener()
+    super.onPause()
+  }
+
+  override fun onStop() {
+    isStopped = true
+    super.onStop()
+  }
+
+  override fun onStart() {
+    isStopped = false
+    super.onStart()
+  }
+
+  override fun onDestroy() {
+    super.onDestroy()
+
+    // Clean up captioning change listener
+    captioningChangeListener?.let {
+      val captioningManager = getSystemService(Context.CAPTIONING_SERVICE) as? CaptioningManager
+      captioningManager?.removeCaptioningChangeListener(it)
+      captioningChangeListener = null
+    }
+
+    if (::videoView.isInitialized) {
+      videoView.exitFullscreen()
+    }
+    VideoManager.unregisterListener(this)
+    videoViewId?.let { VideoManager.unregisterFullscreenPlayerActivity(it) }
+    orientationHelper?.stopOrientationEventListener()
+  }
+
+  // When the app enters the foreground, we need to decide whether to close this activity.
+  // - If stopped: the user went home from fullscreen and came back via app icon -> close
+  // - If in PiP: the user went home while in PiP and came back via app icon -> close
+  // - If only paused (not stopped, not yet in PiP): we're mid-transition into PiP -> keep alive
+  override fun onAppForegrounded() {
+    if (isStopped || isInPictureInPictureMode) {
+      finish()
+    }
+  }
+
+  private fun setupFullscreenButton() {
+    playerView.setFullscreenButtonClickListener { finish() }
+
+    val fullScreenButton: ImageButton = playerView.findViewById(androidx.media3.ui.R.id.exo_fullscreen)
+    fullScreenButton.setImageResource(androidx.media3.ui.R.drawable.exo_icon_fullscreen_exit)
+  }
+
+  override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration?) {
+    if (!isInPictureInPictureMode) {
+      playerView.useController = videoView.useNativeControls
+    } else {
+      playerView.useController = false
+    }
+    if (wasAutoPaused && isInPictureInPictureMode) {
+      videoPlayer?.player?.play()
+    }
+    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
+  }
+
+  private fun hideStatusBar() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+      val controller = mContentView.windowInsetsController
+      controller?.apply {
+        systemBarsBehavior = WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        hide(WindowInsets.Type.statusBars() or WindowInsets.Type.navigationBars())
+      }
+    } else {
+      @Suppress("DEPRECATION")
+      mContentView.systemUiVisibility = (
+        View.SYSTEM_UI_FLAG_LOW_PROFILE
+          or View.SYSTEM_UI_FLAG_FULLSCREEN
+          or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+          or View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
+          or View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+          or View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+        )
+    }
+  }
+
+  private fun setupCaptioningChangeListener() {
+    val captioningManager = getSystemService(Context.CAPTIONING_SERVICE) as? CaptioningManager
+
+    captioningChangeListener = SubtitleUtils.createCaptioningChangeListener(playerView, this) { videoView.subtitleStyle }
+
+    captioningChangeListener?.let { listener ->
+      captioningManager?.addCaptioningChangeListener(listener)
+    }
+  }
+
+  override fun onConfigurationChanged(newConfig: Configuration) {
+    super.onConfigurationChanged(newConfig)
+    orientationHelper?.onConfigurationChanged(newConfig)
+  }
+
+  companion object {
+    const val INTENT_FULLSCREEN_OPTIONS_KEY = "fullscreen_options"
+  }
+}

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

@@ -0,0 +1,54 @@
+package expo.modules.video
+
+import android.os.Handler
+import android.os.Looper
+import expo.modules.video.delegates.IgnoreSameSet
+import java.lang.ref.WeakReference
+
+fun interface IntervalUpdateEmitter {
+  fun emitTimeUpdate()
+}
+
+class IntervalUpdateClock(emitter: IntervalUpdateEmitter) {
+  private val emitter: WeakReference<IntervalUpdateEmitter> = WeakReference(emitter)
+  private var handler: Handler = Handler(Looper.getMainLooper())
+
+  // TODO: @behenate - Once the Player instance is available in OnStartObserving we can automatically start/stop the clock.
+  var interval by IgnoreSameSet(0L) { new: Long, _: Long? ->
+    if (new <= 0) {
+      stop()
+    } else {
+      startOrUpdate()
+    }
+  }
+
+  private var isRunning: Boolean = false
+
+  private fun stop() {
+    handler.removeCallbacksAndMessages(null)
+    isRunning = false
+  }
+
+  private fun startOrUpdate() {
+    if (!isRunning) {
+      emitter.get()?.emitTimeUpdate()
+    } else {
+      handler.removeCallbacksAndMessages(null)
+    }
+    isRunning = true
+    scheduleNextUpdate()
+  }
+
+  private fun scheduleNextUpdate() {
+    if (interval <= 0L) {
+      return
+    }
+
+    val update = {
+      emitter.get()?.emitTimeUpdate()
+      scheduleNextUpdate()
+    }
+
+    handler.postDelayed(update, interval)
+  }
+}