expo-video-subtitle 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,7 +7,43 @@ 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.1.0 — Unreleased
+## 0.1.2
+
+### Fixed
+
+- **Android:** subtitles that are on screen at the same time are now stacked as one block instead of
+  being drawn on top of each other. `.srt` files legitimately contain overlapping timestamps (two
+  speakers, dialogue over on-screen text), but SubRip carries no positioning, so Media3 pinned every
+  cue to the same spot and rendered them one over the other — Media3 does the stacking in its WebVTT
+  *parser* (`line = -1 - i`) and has no equivalent pass for SubRip. A `SubtitleParser` for SubRip now
+  splits the cue timeline at every boundary and merges the cues active in each slice into a single
+  multi-line cue, ordered like WebVTT: the cue that started earliest sits at the bottom. This also
+  makes Android match the iOS output, which already stacked because sideloaded SRT is converted to
+  WebVTT there. Cues with explicit `{\anN}` positioning are left untouched.
+- **Android:** selecting a `subtitleTrack` whose id is not among the available tracks no longer
+  leaves the previously selected track on screen. The cleared track-selection parameters were only
+  applied when a matching track was found, so an unmatched assignment silently did nothing; the
+  selection is now cleared and a warning is logged.
+- **Android:** `subtitleStyle.bottomOffset` is reset to the default when it is omitted, instead of
+  keeping the value from a previously applied style.
+
+## 0.1.1
+
+### Fixed
+
+- **Android:** `subtitleStyle.fontFamily` now resolves custom fonts bundled with the app, the same way
+  React Native resolves a `<Text>` component's `fontFamily`. It is looked up as an Android font
+  resource (`res/font`, where `expo-font`'s config plugin puts fonts) and then through React Native's
+  font manager, which covers the `assets/fonts/<name>.ttf` convention and fonts registered at runtime.
+  Previously only the built-in system families worked: `Typeface.create` silently fell back to the
+  default typeface for any bundled font, so `fontFamily` appeared to do nothing on Android while
+  working on iOS.
+
+### Documentation
+
+- Document font support and the silent-fallback behaviour for unresolved family names.
+
+## 0.1.0
 
 Initial release. Based on `expo-video` **56.1.4** (Expo SDK 56).
 

package/FORK.md

@@ -23,7 +23,8 @@ 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` | 98 | Record → `CaptionStyleCompat`; hex colour parsing. |
+| `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. |
 | `FORK.md`, `LICENSE` | — | This guide; MIT licence (upstream copyright preserved). |
 
 ### Modified — upstream files carrying fork edits (re-apply these after a sync)
@@ -40,9 +41,11 @@ 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. |
+| `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/…/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/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. |
 | `package.json` | — | Fork identity + build scripts — see §3. |
 | `expo-module.config.json` | — | **Android `publication` block removed** — see §3. |
@@ -60,6 +63,14 @@ Measured against the published `expo-video@56.1.4` tarball. `+`/`-` are added/re
 > 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.
 
+### External API coupling to watch
+
+`SubtitleStyle.kt` imports `com.facebook.react.common.assets.ReactFontManager` to resolve
+`fontFamily` the same way `<Text>` does. React Native moved this class from
+`com.facebook.react.views.text` to `com.facebook.react.common.assets` (the old path is deprecated but
+still present in RN 0.85). If a React Native upgrade breaks that import, update the package path — the
+call itself, `getTypeface(family, style, assetManager)`, has been stable.
+
 ---
 
 ## 2. Syncing a newer `expo-video`

package/README.md

@@ -103,6 +103,32 @@ Pass a `subtitleStyle` prop to `VideoView`. It applies to whichever subtitle tra
 
 > **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.
 
+### Fonts
+
+`fontFamily` accepts the same name you would give a `<Text>` component, so a font bundled with your
+app can be used for subtitles:
+
+```tsx
+<VideoView player={player} subtitleStyle={{ fontFamily: 'Inter-Regular', bold: true }} />
+```
+
+The simplest way to make a custom font available on both platforms is `expo-font`'s config plugin,
+which bundles the file into `res/font` on Android and registers it via `UIAppFonts` on iOS:
+
+```json
+["expo-font", { "fonts": ["./assets/fonts/Inter-Regular.ttf"] }]
+```
+
+| Font source | Android | iOS |
+| --- | --- | --- |
+| Built-in system families (`sans-serif`, `serif`, `monospace`, `cursive`, …) | ✅ | ✅ (use iOS names, e.g. `Helvetica Neue`) |
+| Bundled via `expo-font` config plugin | ✅ resolved from `res/font` | ✅ resolved from `UIAppFonts` |
+| React Native convention (`assets/fonts/<name>.ttf`) | ✅ via RN's font manager | — |
+
+> A font name that matches nothing falls back to the default typeface **silently** — neither platform
+> reports an unresolved family. If the font doesn't change, check the spelling first: the name is the
+> font's family name, not the filename.
+
 ## License
 
 MIT. Based on [`expo-video`](https://github.com/expo/expo/tree/main/packages/expo-video) by 650 Industries, Inc.

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

@@ -1,5 +1,6 @@
 package expo.modules.video.player
 
+import android.util.Log
 import androidx.annotation.OptIn
 import androidx.media3.common.C
 import androidx.media3.common.Format
@@ -86,15 +87,24 @@ class VideoPlayerSubtitles(owner: VideoPlayer) : VideoPlayerListener {
     val format = formatsToGroups.keys.firstOrNull {
       it.id == subtitleTrack.id
     }
-    format?.let {
-      formatsToGroups[it]?.let { subtitlePair ->
-        val override = TrackSelectionOverride(subtitlePair.first, subtitlePair.second)
-        newParameters = newParameters.buildUpon().addOverride(override).build()
-        player.trackSelectionParameters = newParameters
-        setSubtitlesEnabled(true)
-        currentOverride = override
-      }
+    val subtitlePair = format?.let { formatsToGroups[it] }
+
+    if (subtitlePair == null) {
+      // The requested track isn't among the available ones. The cleared parameters still have to be
+      // applied, otherwise the previously selected track keeps rendering and the assignment looks
+      // like it was silently ignored.
+      Log.w("ExpoVideo", "Subtitle track with id '${subtitleTrack.id}' is not available; clearing the current selection")
+      player.trackSelectionParameters = newParameters
+      setSubtitlesEnabled(false)
+      currentOverride = null
+      return
     }
+
+    val override = TrackSelectionOverride(subtitlePair.first, subtitlePair.second)
+    newParameters = newParameters.buildUpon().addOverride(override).build()
+    player.trackSelectionParameters = newParameters
+    setSubtitlesEnabled(true)
+    currentOverride = override
   }
 
   private fun findSelectedSubtitleFormat(): Format? {

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

@@ -1,10 +1,13 @@
 package expo.modules.video.records
 
+import android.content.Context
 import android.graphics.Color
 import android.graphics.Typeface
 import androidx.annotation.OptIn
+import androidx.core.content.res.ResourcesCompat
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.ui.CaptionStyleCompat
+import com.facebook.react.common.assets.ReactFontManager
 import expo.modules.kotlin.records.Field
 import expo.modules.kotlin.records.Record
 import java.io.Serializable
@@ -29,22 +32,52 @@ class SubtitleStyle(
    * Builds a [CaptionStyleCompat], falling back to [base] for any unspecified property so that
    * partial styles compose on top of the system/default caption style.
    */
-  fun toCaptionStyle(base: CaptionStyleCompat): CaptionStyleCompat {
+  fun toCaptionStyle(base: CaptionStyleCompat, context: Context): CaptionStyleCompat {
     return CaptionStyleCompat(
       parseColor(textColor) ?: base.foregroundColor,
       parseColor(backgroundColor) ?: base.backgroundColor,
       parseColor(windowColor) ?: base.windowColor,
       parseEdgeType() ?: base.edgeType,
       parseColor(edgeColor) ?: base.edgeColor,
-      resolveTypeface() ?: base.typeface
+      resolveTypeface(context) ?: base.typeface
     )
   }
 
-  private fun resolveTypeface(): Typeface? {
+  /**
+   * Resolves [fontFamily] the same way React Native resolves `<Text style={{ fontFamily }} />`, so a
+   * font bundled with the app can be used for subtitles under the same name.
+   *
+   * Lookup order:
+   *  1. An Android font resource (`res/font/<name>`), which is where `expo-font`'s config plugin puts fonts.
+   *  2. [ReactFontManager], which covers the React Native convention (`assets/fonts/<name>.ttf`) and any
+   *     font registered at runtime, and itself falls back to the built-in system families.
+   *
+   * A name that matches nothing still falls back to the default typeface — Android provides no way to
+   * detect that, so an unknown family fails silently rather than throwing.
+   */
+  private fun resolveTypeface(context: Context): Typeface? {
     val style = if (bold) Typeface.BOLD else Typeface.NORMAL
-    fontFamily?.let { return Typeface.create(it, style) }
-    if (bold) return Typeface.DEFAULT_BOLD
-    return null
+    val family = fontFamily?.takeIf { it.isNotBlank() }
+      ?: return if (bold) Typeface.DEFAULT_BOLD else null
+
+    resolveFontResource(context, family)?.let { return Typeface.create(it, style) }
+
+    return try {
+      ReactFontManager.getInstance().getTypeface(family, style, context.assets)
+    } catch (e: Exception) {
+      // Never let font resolution break subtitle rendering.
+      Typeface.create(family, style)
+    }
+  }
+
+  private fun resolveFontResource(context: Context, family: String): Typeface? {
+    return try {
+      @Suppress("DiscouragedApi") // Font names arrive at runtime, so they can't be compile-time resource ids.
+      val resId = context.resources.getIdentifier(family.lowercase(), "font", context.packageName)
+      if (resId == 0) null else ResourcesCompat.getFont(context, resId)
+    } catch (e: Exception) {
+      null
+    }
   }
 
   private fun parseEdgeType(): Int? = when (edgeType?.lowercase()) {

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

@@ -13,6 +13,7 @@ import androidx.media3.exoplayer.source.DefaultMediaSourceFactory
 import androidx.media3.exoplayer.source.MediaSource
 import expo.modules.video.records.VideoSource
 import expo.modules.video.managers.VideoManager
+import expo.modules.video.utils.ExpoVideoSubtitleParserFactory
 import okhttp3.OkHttpClient
 
 @OptIn(UnstableApi::class)
@@ -54,7 +55,11 @@ fun buildCacheDataSourceFactory(context: Context, videoSource: VideoSource): Dat
 }
 
 fun buildMediaSourceFactory(context: Context, dataSourceFactory: DataSource.Factory): MediaSource.Factory {
-  return DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
+  return DefaultMediaSourceFactory(context)
+    .setDataSourceFactory(dataSourceFactory)
+    // Lays out simultaneous SubRip cues as one stacked block instead of drawing them on top of
+    // each other. See `StackingSubripParser`.
+    .setSubtitleParserFactory(ExpoVideoSubtitleParserFactory())
 }
 
 @OptIn(UnstableApi::class)

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

@@ -0,0 +1,211 @@
+package expo.modules.video.utils
+
+import androidx.annotation.OptIn
+import androidx.media3.common.C
+import androidx.media3.common.Format
+import androidx.media3.common.MimeTypes
+import androidx.media3.common.text.Cue
+import androidx.media3.common.util.Consumer
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.extractor.text.CuesWithTiming
+import androidx.media3.extractor.text.DefaultSubtitleParserFactory
+import androidx.media3.extractor.text.SubtitleParser
+import androidx.media3.extractor.text.subrip.SubripParser
+
+/**
+ * A [SubtitleParser] for SubRip (`.srt`) that lays out simultaneous cues as a single stacked block
+ * instead of drawing them on top of each other.
+ *
+ * ### Why this is needed
+ *
+ * SubRip carries no positioning information, so every cue Media3's [SubripParser] produces has
+ * `line == Cue.DIMEN_UNSET`. `SubtitlePainter` pins every such cue to the same spot
+ * (`parentBottom - textHeight - parentHeight * bottomPaddingFraction`) and `CanvasSubtitleOutput`
+ * gives each painter the identical layout box, so two cues that are on screen at the same time are
+ * rendered in exactly the same place. Media3 performs no collision avoidance: for WebVTT the
+ * stacking is done by the *parser* (which assigns `line = -1 - i` per the WebVTT spec), and the
+ * SubRip path simply has no equivalent pass. `.srt` files with overlapping timestamps are perfectly
+ * legal and common (two speakers, dialogue plus on-screen signs), so the fix belongs here.
+ *
+ * ### Approach
+ *
+ * The cue timeline is split at every start/end boundary into non-overlapping segments, and the cues
+ * active in a segment are merged into one multi-line cue. Merging rather than assigning `line`
+ * values is deliberate: `SubtitlePainter` advances `LINE_TYPE_NUMBER` positions by the height of a
+ * cue's *first* line, so a two-line cue at line -1 would still collide with a cue at line -2, and
+ * a parser cannot predict where text will wrap. One merged cue is laid out as a single block, which
+ * cannot self-overlap, keeps line spacing uniform and lets the text layout handle wrapping.
+ *
+ * Ordering matches WebVTT (and therefore the iOS behaviour of this package): the cue that started
+ * earliest sits at the bottom and later cues stack above it.
+ *
+ * Cues that *do* carry explicit positioning (SubRip's `{\anN}` tags) are passed through untouched —
+ * they were placed deliberately and must not be merged.
+ */
+@OptIn(UnstableApi::class)
+class StackingSubripParser : SubtitleParser {
+  private val delegate = SubripParser()
+
+  // Every emitted segment is a complete description of what should be on screen for its interval,
+  // so segments replace each other rather than being merged by the renderer.
+  override fun getCueReplacementBehavior(): Int = Format.CUE_REPLACEMENT_BEHAVIOR_REPLACE
+
+  override fun reset() {
+    delegate.reset()
+  }
+
+  override fun parse(
+    data: ByteArray,
+    offset: Int,
+    length: Int,
+    outputOptions: SubtitleParser.OutputOptions,
+    output: Consumer<CuesWithTiming>
+  ) {
+    val entries = mutableListOf<Entry>()
+    // Always ask the delegate for everything; `outputOptions` is applied to the merged result below,
+    // because a segment can span cues that fall on both sides of the requested start time.
+    delegate.parse(data, offset, length, SubtitleParser.OutputOptions.allCues()) { cuesWithTiming ->
+      val startUs = cuesWithTiming.startTimeUs
+      val endUs = resolveEndUs(cuesWithTiming)
+      for (cue in cuesWithTiming.cues) {
+        entries.add(Entry(cue, startUs, endUs, entries.size))
+      }
+    }
+
+    if (entries.isEmpty()) {
+      return
+    }
+
+    val segments = buildSegments(entries)
+    emit(segments, outputOptions, output)
+  }
+
+  private fun resolveEndUs(cuesWithTiming: CuesWithTiming): Long {
+    val durationUs = cuesWithTiming.durationUs
+    return if (durationUs == C.TIME_UNSET || durationUs <= 0) {
+      // Without a duration there is nothing sensible to overlap against; treat it as instantaneous
+      // so it never swallows later cues.
+      cuesWithTiming.startTimeUs
+    } else {
+      cuesWithTiming.startTimeUs + durationUs
+    }
+  }
+
+  /** Splits the timeline at every cue boundary and merges the cues active within each slice. */
+  private fun buildSegments(entries: List<Entry>): List<CuesWithTiming> {
+    val boundaries = sortedSetOf<Long>()
+    for (entry in entries) {
+      boundaries.add(entry.startUs)
+      boundaries.add(entry.endUs)
+    }
+
+    val ordered = boundaries.toList()
+    val segments = mutableListOf<CuesWithTiming>()
+
+    for (i in 0 until ordered.size - 1) {
+      val segmentStart = ordered[i]
+      val segmentEnd = ordered[i + 1]
+      if (segmentEnd <= segmentStart) {
+        continue
+      }
+
+      // Earliest first, falling back to file order for cues that start together.
+      val active = entries
+        .filter { it.startUs <= segmentStart && it.endUs > segmentStart }
+        .sortedWith(compareBy({ it.startUs }, { it.order }))
+
+      if (active.isEmpty()) {
+        continue
+      }
+
+      val cues = mergeActiveCues(active)
+      if (cues.isNotEmpty()) {
+        segments.add(CuesWithTiming(cues, segmentStart, segmentEnd - segmentStart))
+      }
+    }
+
+    return segments
+  }
+
+  private fun mergeActiveCues(active: List<Entry>): List<Cue> {
+    val positioned = active.filter { it.cue.hasExplicitPosition() }
+    val unpositioned = active.filter { !it.cue.hasExplicitPosition() }
+
+    if (unpositioned.isEmpty()) {
+      return positioned.map { it.cue }
+    }
+    if (unpositioned.size == 1) {
+      return positioned.map { it.cue } + unpositioned.first().cue
+    }
+
+    // Reversed so the most recent cue is the first rendered line (the top of the block) and the
+    // earliest stays at the bottom, matching how WebVTT stacks with line = -1 - i.
+    val mergedText = unpositioned
+      .asReversed()
+      .mapNotNull { it.cue.text?.toString()?.takeIf(String::isNotBlank) }
+      .joinToString("\n")
+
+    if (mergedText.isEmpty()) {
+      return positioned.map { it.cue }
+    }
+
+    // Build from the bottom-most cue so any styling it carries survives the merge.
+    val template = unpositioned.first().cue
+    val merged = template.buildUpon().setText(mergedText).build()
+    return positioned.map { it.cue } + merged
+  }
+
+  private fun emit(
+    segments: List<CuesWithTiming>,
+    outputOptions: SubtitleParser.OutputOptions,
+    output: Consumer<CuesWithTiming>
+  ) {
+    val startTimeUs = outputOptions.startTimeUs
+    if (startTimeUs == C.TIME_UNSET) {
+      segments.forEach(output::accept)
+      return
+    }
+
+    // Cues still visible at, or starting after, the requested time come first.
+    segments.filter { it.endTimeUs > startTimeUs }.forEach(output::accept)
+    if (outputOptions.outputAllCues) {
+      segments.filter { it.endTimeUs <= startTimeUs }.forEach(output::accept)
+    }
+  }
+
+  private fun Cue.hasExplicitPosition(): Boolean =
+    line != Cue.DIMEN_UNSET || position != Cue.DIMEN_UNSET
+
+  private data class Entry(
+    val cue: Cue,
+    val startUs: Long,
+    val endUs: Long,
+    /** Preserves file order so cues sharing a start time keep a stable, deterministic layout. */
+    val order: Int
+  )
+}
+
+/**
+ * Routes SubRip through [StackingSubripParser] so simultaneous cues stack, and delegates every other
+ * subtitle format to Media3's default handling.
+ */
+@OptIn(UnstableApi::class)
+class ExpoVideoSubtitleParserFactory : SubtitleParser.Factory {
+  private val defaultFactory = DefaultSubtitleParserFactory()
+
+  override fun supportsFormat(format: Format): Boolean =
+    format.isSubrip() || defaultFactory.supportsFormat(format)
+
+  override fun getCueReplacementBehavior(format: Format): Int =
+    if (format.isSubrip()) {
+      Format.CUE_REPLACEMENT_BEHAVIOR_REPLACE
+    } else {
+      defaultFactory.getCueReplacementBehavior(format)
+    }
+
+  override fun create(format: Format): SubtitleParser =
+    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/SubtitleUtils.kt

@@ -5,6 +5,7 @@ import android.util.TypedValue
 import android.view.accessibility.CaptioningManager
 import androidx.media3.ui.CaptionStyleCompat
 import androidx.media3.ui.PlayerView
+import androidx.media3.ui.SubtitleView
 import expo.modules.video.records.SubtitleStyle
 
 object SubtitleUtils {
@@ -29,10 +30,14 @@ object SubtitleUtils {
 
       if (customStyle != null) {
         val base = userStyle?.let { CaptionStyleCompat.createFromCaptionStyle(it) } ?: CaptionStyleCompat.DEFAULT
-        setStyle(customStyle.toCaptionStyle(base))
+        setStyle(customStyle.toCaptionStyle(base, context))
         // On Android `fontSize` is an absolute sp value; when omitted, fall back to the accessibility-scaled base.
         setFixedTextSize(TypedValue.COMPLEX_UNIT_SP, customStyle.fontSize ?: (baseFontSize * fontScale))
-        customStyle.bottomOffset?.let { setBottomPaddingFraction(it.coerceIn(0f, 1f)) }
+        // Always assign, so clearing `bottomOffset` restores the default instead of leaving the
+        // previously applied fraction in place.
+        setBottomPaddingFraction(
+          customStyle.bottomOffset?.coerceIn(0f, 1f) ?: SubtitleView.DEFAULT_BOTTOM_PADDING_FRACTION
+        )
       } else if (userStyle != null) {
         // Apply system accessibility caption style but with reasonable base font size
         setStyle(CaptionStyleCompat.createFromCaptionStyle(userStyle))

package/build/VideoView.types.d.ts

@@ -225,6 +225,20 @@ export type SubtitleStyle = {
     fontSize?: number;
     /**
      * The name of the font family used to render the subtitles.
+     *
+     * Custom fonts bundled with the app are supported, using the same name you would pass to a
+     * `<Text>` component's `fontFamily`:
+     * - On Android the font is looked up as an Android font resource (`res/font`, where `expo-font`'s
+     *   config plugin places fonts) and then through React Native's font manager, which covers the
+     *   `assets/fonts/<name>.ttf` convention and fonts registered at runtime.
+     * - On iOS the font must be registered with the system, which is what bundling it through
+     *   `expo-font`'s config plugin (`UIAppFonts`) does.
+     *
+     * The built-in system families always work — for example `sans-serif`, `sans-serif-medium`,
+     * `serif`, `monospace` and `cursive` on Android.
+     *
+     * > A name that matches no font falls back to the default typeface silently: neither platform
+     * > reports an unresolved font family, so double-check the spelling if nothing changes.
      */
     fontFamily?: string;
     /**

package/build/VideoView.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VideoView.types.d.ts","sourceRoot":"","sources":["../src/VideoView.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC;AAExD,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAE5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;IAE7B;;OAEG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;;OAIG;IACH,eAAe,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE/C;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IAErC;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpC;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,mCAAmC,CAAC,EAAE,OAAO,CAAC;IAE9C;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAE/B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAE9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAEhC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAAC;IAE9C;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAC7B,SAAS,GACT,UAAU,GACV,YAAY,GACZ,cAAc,GACd,WAAW,GACX,eAAe,GACf,gBAAgB,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,+BAA+B,CAAC;CAC3D,CAAC"}
+{"version":3,"file":"VideoView.types.d.ts","sourceRoot":"","sources":["../src/VideoView.types.ts"],"names":[],"mappings":"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"}

package/build/VideoView.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"VideoView.types.js","sourceRoot":"","sources":["../src/VideoView.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ViewProps } from 'react-native';\n\nimport type { VideoPlayer } from './VideoPlayer.types';\n\n/**\n * Describes how a video should be scaled to fit in a container.\n * - `contain`: The video maintains its aspect ratio and fits inside the container, with possible letterboxing/pillarboxing.\n * - `cover`: The video maintains its aspect ratio and covers the entire container, potentially cropping some portions.\n * - `fill`: The video stretches/squeezes to completely fill the container, potentially causing distortion.\n */\nexport type VideoContentFit = 'contain' | 'cover' | 'fill';\n\n/**\n * Describes the type of the surface used to render the video.\n * - `surfaceView`: Uses the `SurfaceView` to render the video. This value should be used in the majority of cases. Provides significantly lower power consumption, better performance, and more features.\n * - `textureView`: Uses the `TextureView` to render the video. Should be used in cases where the SurfaceView is not supported or causes issues (for example, overlapping video views).\n *\n * You can learn more about surface types in the official [ExoPlayer documentation](https://developer.android.com/media/media3/ui/playerview#surfacetype).\n * @platform android\n */\nexport type SurfaceType = 'textureView' | 'surfaceView';\n\nexport interface VideoViewProps extends ViewProps {\n  /**\n   * A video player instance. Use [`useVideoPlayer()`](#usevideoplayersource-setup) hook to create one.\n   */\n  player?: VideoPlayer | null;\n\n  /**\n   * Determines whether native controls should be displayed or not.\n   *\n   * > **Note**: Due to platform limitations, the native controls are always enabled in fullscreen mode.\n   * @default true\n   */\n  nativeControls?: boolean;\n\n  /**\n   * Describes how the video should be scaled to fit in the container.\n   * Options are `'contain'`, `'cover'`, and `'fill'`.\n   * @default 'contain'\n   */\n  contentFit?: VideoContentFit;\n\n  /**\n   * Determines the fullscreen mode options.\n   */\n  fullscreenOptions?: FullscreenOptions;\n\n  /**\n   * Determines whether the timecodes should be displayed or not.\n   * @default true\n   * @platform ios\n   */\n  showsTimecodes?: boolean;\n\n  /**\n   * Determines whether the player allows the user to skip media content.\n   * @default false\n   * @platform android\n   * @platform ios\n   */\n  requiresLinearPlayback?: boolean;\n\n  /**\n   * Configuration for controlling the visibility of player control buttons.\n   * @platform android\n   */\n  buttonOptions?: ButtonOptions;\n\n  /**\n   * Customizes the appearance of the rendered subtitles/captions (text color, background, font, edge, and position).\n   *\n   * The style is applied to whatever subtitle track is currently displayed, regardless of whether it comes\n   * from an embedded (`HLS`/`DASH`) track or an external one attached through\n   * [`VideoSource.subtitleTracks`](#videosourcesubtitletracks).\n   *\n   * > **Note (iOS):** styling relies on `AVPlayerItem.textStyleRules`, which only affects `WebVTT` captions that\n   * > the system renders itself. The OS-level *Settings → Accessibility → Subtitles & Captioning* preferences\n   * > take precedence over these values when the user has enabled them.\n   *\n   * @platform android\n   * @platform ios\n   */\n  subtitleStyle?: SubtitleStyle;\n\n  /**\n   * Determines the type of the surface used to render the video.\n   * > This prop should not be changed at runtime.\n   * @default 'surfaceView'\n   * @platform android\n   */\n  surfaceType?: SurfaceType;\n\n  /**\n   * Determines the position offset of the video inside the container.\n   * @default { dx: 0, dy: 0 }\n   * @platform ios\n   */\n  contentPosition?: { dx?: number; dy?: number };\n\n  /**\n   * A callback to call after the video player enters Picture in Picture (PiP) mode.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  onPictureInPictureStart?: () => void;\n\n  /**\n   * A callback to call after the video player exits Picture in Picture (PiP) mode.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  onPictureInPictureStop?: () => void;\n\n  /**\n   * Determines whether the player allows Picture in Picture (PiP) mode.\n   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)\n   * > has to be configured for the PiP to work.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  allowsPictureInPicture?: boolean;\n\n  /**\n   * Determines whether a video should be played \"inline\", that is, within the element's playback area.\n   * @platform web\n   */\n  playsInline?: boolean;\n\n  /**\n   * Determines whether the player should start Picture in Picture (PiP) automatically when the app is in the background.\n   * > **Note:** Only one player can be in Picture in Picture (PiP) mode at a time.\n   *\n   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)\n   * > has to be configured for the PiP to work.\n   *\n   * @default false\n   * @platform android 12+\n   * @platform ios\n   */\n  startsPictureInPictureAutomatically?: boolean;\n\n  /**\n   * Specifies whether to perform video frame analysis (Live Text in videos).\n   * Check official [Apple documentation](https://developer.apple.com/documentation/avkit/avplayerviewcontroller/allowsvideoframeanalysis) for more details.\n   * @default true\n   * @platform ios 16.0+\n   */\n  allowsVideoFrameAnalysis?: boolean;\n\n  /**\n   * A callback to call after the video player enters fullscreen mode.\n   */\n  onFullscreenEnter?: () => void;\n\n  /**\n   * A callback to call after the video player exits fullscreen mode.\n   */\n  onFullscreenExit?: () => void;\n\n  /**\n   * A callback to call after the mounted `VideoPlayer` has rendered the first frame into the `VideoView`.\n   * This event can be used to hide any cover images that conceal the initial loading of the player.\n   * > **Note:** This event may also be called during playback when the current video track changes (for example when the player switches video quality).\n   */\n  onFirstFrameRender?: () => void;\n\n  /**\n   * Determines whether the player should use the default ExoPlayer shutter that covers the `VideoView` before the first video frame is rendered.\n   * Setting this property to `false` makes the Android behavior the same as iOS.\n   *\n   * @platform android\n   * @default false\n   */\n  useExoShutter?: boolean;\n\n  /**\n   * Determines the [cross origin policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) used by the underlying native view on web.\n   * If `undefined` (default), does not use CORS at all. If set to `'anonymous'`, the video will be loaded with CORS enabled.\n   * Note that some videos may not play if CORS is enabled, depending on the CDN settings.\n   * If you encounter issues, consider adjusting the `crossOrigin` property.\n   *\n   *\n   * @platform web\n   * @default undefined\n   */\n  crossOrigin?: 'anonymous' | 'use-credentials';\n\n  /**\n   * Use Audio Nodes for sound playback. When the same player is playing in multiple video views the audio won't increase in volume\n   * as the number of players increases.\n   *\n   * > **Note**: This property is experimental, when enabled it is known to break audio for some sources. Do not change this property at runtime.\n   *\n   * @experimental\n   * @default false\n   * @platform web\n   */\n  useAudioNodePlayback?: boolean;\n}\n\n/**\n * Describes the edge (outline) effect drawn around subtitle text.\n * - `none`: No edge effect.\n * - `outline`: A solid outline around each glyph.\n * - `dropShadow`: A drop shadow behind the text.\n * - `raised`: The text appears raised from the background.\n * - `depressed`: The text appears pressed into the background.\n */\nexport type SubtitleEdgeType = 'none' | 'outline' | 'dropShadow' | 'raised' | 'depressed';\n\n/**\n * Describes the visual style applied to the rendered subtitles/captions.\n *\n * Colors accept a hex string in the form `#RGB`, `#RRGGBB`, or `#RRGGBBAA` (an alpha suffix controls opacity).\n *\n * @platform android\n * @platform ios\n */\nexport type SubtitleStyle = {\n  /**\n   * The color of the subtitle text.\n   * @default '#FFFFFF'\n   */\n  textColor?: string;\n\n  /**\n   * The background color drawn directly behind the text glyphs (the caption \"box\").\n   * Use an alpha suffix (for example `#000000A0`) for a translucent box.\n   * @default 'transparent'\n   */\n  backgroundColor?: string;\n\n  /**\n   * The background color of the whole cue region (the \"window\" behind the whole line).\n   * @default 'transparent'\n   */\n  windowColor?: string;\n\n  /**\n   * The subtitle font size.\n   *\n   * > The unit differs per platform: on Android this is an absolute size in `sp`; on iOS it is a percentage\n   * > relative to the default caption size (`100` = default, `150` = 1.5×).\n   *\n   * @platform android\n   * @platform ios\n   */\n  fontSize?: number;\n\n  /**\n   * The name of the font family used to render the subtitles.\n   */\n  fontFamily?: string;\n\n  /**\n   * Whether the subtitle text should be rendered in bold.\n   * @default false\n   */\n  bold?: boolean;\n\n  /**\n   * The edge (outline) effect drawn around the text.\n   * @default 'none'\n   */\n  edgeType?: SubtitleEdgeType;\n\n  /**\n   * The color of the edge effect. Only has an effect when `edgeType` is not `'none'`.\n   */\n  edgeColor?: string;\n\n  /**\n   * The distance of the subtitles from the bottom of the video, expressed as a fraction of the view height (`0`–`1`).\n   * @platform android\n   */\n  bottomOffset?: number;\n};\n\n/**\n * Configuration for controlling the visibility of player control buttons.\n *\n * > The fullscreen button should be controlled with [`fullscreenOptions.enable`](#fullscreenoptions).\n *\n * @platform android\n */\nexport type ButtonOptions = {\n  /**\n   * Whether to show the next button.\n   * @default false\n   */\n  showNext?: boolean;\n  /**\n   * Whether to show the previous button.\n   * @default false\n   */\n  showPrevious?: boolean;\n  /**\n   * Whether to show the seek forward button.\n   * @default true\n   */\n  showSeekForward?: boolean;\n  /**\n   * Whether to show the seek backward button.\n   * @default true\n   */\n  showSeekBackward?: boolean;\n  /**\n   * Whether to show the subtitles button.\n   * - `true`: Button is always visible\n   * - `false`: Button is never visible\n   * - `undefined`: Button is visible only when subtitles are available (default behavior)\n   * @default undefined\n   */\n  showSubtitles?: boolean | null;\n  /**\n   * Whether to show the settings button.\n   * @default true\n   */\n  showSettings?: boolean;\n  /**\n   * Whether to show the play/pause button.\n   * @default true\n   */\n  showPlayPause?: boolean;\n  /**\n   * Whether to show the bottom control bar (containing time, progress bar, and buttons).\n   * When set to `false`, the entire bottom bar including the progress bar will be hidden.\n   *\n   * > **Note**: The bottom bar is always visible in fullscreen mode to allow users to exit fullscreen.\n   *\n   * @default true\n   */\n  showBottomBar?: boolean;\n};\n\n/**\n * Describes the orientation of the video in fullscreen mode. Available values are:\n * - `default`: The video is displayed in any of the available device rotations.\n * - `portrait`: The video is displayed in one of two available portrait orientations and rotates between them.\n * - `portraitUp`: The video is displayed in the portrait orientation - the notch of the phone points upwards.\n * - `portraitDown`: The video is displayed in the portrait orientation - the notch of the phone points downwards.\n * - `landscape`: The video is displayed in one of two available landscape orientations and rotates between them.\n * - `landscapeLeft`: The video is displayed in the left landscape orientation - the notch of the phone is in the left palm of the user.\n * - `landscapeRight`: The video is displayed in the right landscape orientation - the notch of the phone is in the right palm of the user.\n */\nexport type FullscreenOrientation =\n  | 'default'\n  | 'portrait'\n  | 'portraitUp'\n  | 'portraitDown'\n  | 'landscape'\n  | 'landscapeLeft'\n  | 'landscapeRight';\n\n/**\n * Determines whether the player keeps fullscreen when Picture in Picture (PiP) stops.\n * Only has an effect if the player was in fullscreen when PiP started.\n * - `'always'`: Always re-enter fullscreen when PiP stops.\n * - `'autoEnter'`: Re-enter fullscreen only when PiP was started automatically by the app going to the background.\n * - `'never'`: Do not re-enter fullscreen when PiP stops.\n */\nexport type KeepFullscreenOnPiPStopBehavior = 'always' | 'autoEnter' | 'never';\n\n/**\n * Describes the options for fullscreen video mode.\n */\nexport type FullscreenOptions = {\n  /**\n   * Specifies whether the fullscreen mode should be available to the user. When `false`, the fullscreen button will be hidden in the player.\n   * @default true\n   */\n  enable: boolean;\n  /**\n   * Specifies the orientation of the video in fullscreen mode.\n   * @default 'default'\n   * @platform android\n   * @platform ios\n   */\n  orientation?: FullscreenOrientation;\n  /**\n   * Specifies whether the app should exit fullscreen mode when the device is rotated to a different orientation than the one specified in the `orientation` prop.\n   * For example, if the `orientation` prop is set to `landscape` and the device is rotated to `portrait`, the app will exit fullscreen mode.\n   *\n   * > This prop will have no effect if the `orientation` prop is set to `default`.\n   * > The `VideoView` will never auto-exit fullscreen when the device auto-rotate feature has been disabled in settings.\n   *\n   * @default false\n   * @platform android\n   * @platform ios\n   */\n  autoExitOnRotate?: boolean;\n\n  /**\n   * Determines whether the player keeps fullscreen when Picture in Picture (PiP) stops.\n   * Only has an effect if the player was in fullscreen when PiP started.\n   *\n   * @default 'autoEnter'\n   * @platform ios\n   */\n  keepFullscreenOnPiPStop?: KeepFullscreenOnPiPStopBehavior;\n};\n"]}
+{"version":3,"file":"VideoView.types.js","sourceRoot":"","sources":["../src/VideoView.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ViewProps } from 'react-native';\n\nimport type { VideoPlayer } from './VideoPlayer.types';\n\n/**\n * Describes how a video should be scaled to fit in a container.\n * - `contain`: The video maintains its aspect ratio and fits inside the container, with possible letterboxing/pillarboxing.\n * - `cover`: The video maintains its aspect ratio and covers the entire container, potentially cropping some portions.\n * - `fill`: The video stretches/squeezes to completely fill the container, potentially causing distortion.\n */\nexport type VideoContentFit = 'contain' | 'cover' | 'fill';\n\n/**\n * Describes the type of the surface used to render the video.\n * - `surfaceView`: Uses the `SurfaceView` to render the video. This value should be used in the majority of cases. Provides significantly lower power consumption, better performance, and more features.\n * - `textureView`: Uses the `TextureView` to render the video. Should be used in cases where the SurfaceView is not supported or causes issues (for example, overlapping video views).\n *\n * You can learn more about surface types in the official [ExoPlayer documentation](https://developer.android.com/media/media3/ui/playerview#surfacetype).\n * @platform android\n */\nexport type SurfaceType = 'textureView' | 'surfaceView';\n\nexport interface VideoViewProps extends ViewProps {\n  /**\n   * A video player instance. Use [`useVideoPlayer()`](#usevideoplayersource-setup) hook to create one.\n   */\n  player?: VideoPlayer | null;\n\n  /**\n   * Determines whether native controls should be displayed or not.\n   *\n   * > **Note**: Due to platform limitations, the native controls are always enabled in fullscreen mode.\n   * @default true\n   */\n  nativeControls?: boolean;\n\n  /**\n   * Describes how the video should be scaled to fit in the container.\n   * Options are `'contain'`, `'cover'`, and `'fill'`.\n   * @default 'contain'\n   */\n  contentFit?: VideoContentFit;\n\n  /**\n   * Determines the fullscreen mode options.\n   */\n  fullscreenOptions?: FullscreenOptions;\n\n  /**\n   * Determines whether the timecodes should be displayed or not.\n   * @default true\n   * @platform ios\n   */\n  showsTimecodes?: boolean;\n\n  /**\n   * Determines whether the player allows the user to skip media content.\n   * @default false\n   * @platform android\n   * @platform ios\n   */\n  requiresLinearPlayback?: boolean;\n\n  /**\n   * Configuration for controlling the visibility of player control buttons.\n   * @platform android\n   */\n  buttonOptions?: ButtonOptions;\n\n  /**\n   * Customizes the appearance of the rendered subtitles/captions (text color, background, font, edge, and position).\n   *\n   * The style is applied to whatever subtitle track is currently displayed, regardless of whether it comes\n   * from an embedded (`HLS`/`DASH`) track or an external one attached through\n   * [`VideoSource.subtitleTracks`](#videosourcesubtitletracks).\n   *\n   * > **Note (iOS):** styling relies on `AVPlayerItem.textStyleRules`, which only affects `WebVTT` captions that\n   * > the system renders itself. The OS-level *Settings → Accessibility → Subtitles & Captioning* preferences\n   * > take precedence over these values when the user has enabled them.\n   *\n   * @platform android\n   * @platform ios\n   */\n  subtitleStyle?: SubtitleStyle;\n\n  /**\n   * Determines the type of the surface used to render the video.\n   * > This prop should not be changed at runtime.\n   * @default 'surfaceView'\n   * @platform android\n   */\n  surfaceType?: SurfaceType;\n\n  /**\n   * Determines the position offset of the video inside the container.\n   * @default { dx: 0, dy: 0 }\n   * @platform ios\n   */\n  contentPosition?: { dx?: number; dy?: number };\n\n  /**\n   * A callback to call after the video player enters Picture in Picture (PiP) mode.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  onPictureInPictureStart?: () => void;\n\n  /**\n   * A callback to call after the video player exits Picture in Picture (PiP) mode.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  onPictureInPictureStop?: () => void;\n\n  /**\n   * Determines whether the player allows Picture in Picture (PiP) mode.\n   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)\n   * > has to be configured for the PiP to work.\n   * @platform android\n   * @platform ios\n   * @platform web\n   */\n  allowsPictureInPicture?: boolean;\n\n  /**\n   * Determines whether a video should be played \"inline\", that is, within the element's playback area.\n   * @platform web\n   */\n  playsInline?: boolean;\n\n  /**\n   * Determines whether the player should start Picture in Picture (PiP) automatically when the app is in the background.\n   * > **Note:** Only one player can be in Picture in Picture (PiP) mode at a time.\n   *\n   * > **Note:** The `supportsPictureInPicture` property of the [config plugin](#configuration-in-app-config)\n   * > has to be configured for the PiP to work.\n   *\n   * @default false\n   * @platform android 12+\n   * @platform ios\n   */\n  startsPictureInPictureAutomatically?: boolean;\n\n  /**\n   * Specifies whether to perform video frame analysis (Live Text in videos).\n   * Check official [Apple documentation](https://developer.apple.com/documentation/avkit/avplayerviewcontroller/allowsvideoframeanalysis) for more details.\n   * @default true\n   * @platform ios 16.0+\n   */\n  allowsVideoFrameAnalysis?: boolean;\n\n  /**\n   * A callback to call after the video player enters fullscreen mode.\n   */\n  onFullscreenEnter?: () => void;\n\n  /**\n   * A callback to call after the video player exits fullscreen mode.\n   */\n  onFullscreenExit?: () => void;\n\n  /**\n   * A callback to call after the mounted `VideoPlayer` has rendered the first frame into the `VideoView`.\n   * This event can be used to hide any cover images that conceal the initial loading of the player.\n   * > **Note:** This event may also be called during playback when the current video track changes (for example when the player switches video quality).\n   */\n  onFirstFrameRender?: () => void;\n\n  /**\n   * Determines whether the player should use the default ExoPlayer shutter that covers the `VideoView` before the first video frame is rendered.\n   * Setting this property to `false` makes the Android behavior the same as iOS.\n   *\n   * @platform android\n   * @default false\n   */\n  useExoShutter?: boolean;\n\n  /**\n   * Determines the [cross origin policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) used by the underlying native view on web.\n   * If `undefined` (default), does not use CORS at all. If set to `'anonymous'`, the video will be loaded with CORS enabled.\n   * Note that some videos may not play if CORS is enabled, depending on the CDN settings.\n   * If you encounter issues, consider adjusting the `crossOrigin` property.\n   *\n   *\n   * @platform web\n   * @default undefined\n   */\n  crossOrigin?: 'anonymous' | 'use-credentials';\n\n  /**\n   * Use Audio Nodes for sound playback. When the same player is playing in multiple video views the audio won't increase in volume\n   * as the number of players increases.\n   *\n   * > **Note**: This property is experimental, when enabled it is known to break audio for some sources. Do not change this property at runtime.\n   *\n   * @experimental\n   * @default false\n   * @platform web\n   */\n  useAudioNodePlayback?: boolean;\n}\n\n/**\n * Describes the edge (outline) effect drawn around subtitle text.\n * - `none`: No edge effect.\n * - `outline`: A solid outline around each glyph.\n * - `dropShadow`: A drop shadow behind the text.\n * - `raised`: The text appears raised from the background.\n * - `depressed`: The text appears pressed into the background.\n */\nexport type SubtitleEdgeType = 'none' | 'outline' | 'dropShadow' | 'raised' | 'depressed';\n\n/**\n * Describes the visual style applied to the rendered subtitles/captions.\n *\n * Colors accept a hex string in the form `#RGB`, `#RRGGBB`, or `#RRGGBBAA` (an alpha suffix controls opacity).\n *\n * @platform android\n * @platform ios\n */\nexport type SubtitleStyle = {\n  /**\n   * The color of the subtitle text.\n   * @default '#FFFFFF'\n   */\n  textColor?: string;\n\n  /**\n   * The background color drawn directly behind the text glyphs (the caption \"box\").\n   * Use an alpha suffix (for example `#000000A0`) for a translucent box.\n   * @default 'transparent'\n   */\n  backgroundColor?: string;\n\n  /**\n   * The background color of the whole cue region (the \"window\" behind the whole line).\n   * @default 'transparent'\n   */\n  windowColor?: string;\n\n  /**\n   * The subtitle font size.\n   *\n   * > The unit differs per platform: on Android this is an absolute size in `sp`; on iOS it is a percentage\n   * > relative to the default caption size (`100` = default, `150` = 1.5×).\n   *\n   * @platform android\n   * @platform ios\n   */\n  fontSize?: number;\n\n  /**\n   * The name of the font family used to render the subtitles.\n   *\n   * Custom fonts bundled with the app are supported, using the same name you would pass to a\n   * `<Text>` component's `fontFamily`:\n   * - On Android the font is looked up as an Android font resource (`res/font`, where `expo-font`'s\n   *   config plugin places fonts) and then through React Native's font manager, which covers the\n   *   `assets/fonts/<name>.ttf` convention and fonts registered at runtime.\n   * - On iOS the font must be registered with the system, which is what bundling it through\n   *   `expo-font`'s config plugin (`UIAppFonts`) does.\n   *\n   * The built-in system families always work — for example `sans-serif`, `sans-serif-medium`,\n   * `serif`, `monospace` and `cursive` on Android.\n   *\n   * > A name that matches no font falls back to the default typeface silently: neither platform\n   * > reports an unresolved font family, so double-check the spelling if nothing changes.\n   */\n  fontFamily?: string;\n\n  /**\n   * Whether the subtitle text should be rendered in bold.\n   * @default false\n   */\n  bold?: boolean;\n\n  /**\n   * The edge (outline) effect drawn around the text.\n   * @default 'none'\n   */\n  edgeType?: SubtitleEdgeType;\n\n  /**\n   * The color of the edge effect. Only has an effect when `edgeType` is not `'none'`.\n   */\n  edgeColor?: string;\n\n  /**\n   * The distance of the subtitles from the bottom of the video, expressed as a fraction of the view height (`0`–`1`).\n   * @platform android\n   */\n  bottomOffset?: number;\n};\n\n/**\n * Configuration for controlling the visibility of player control buttons.\n *\n * > The fullscreen button should be controlled with [`fullscreenOptions.enable`](#fullscreenoptions).\n *\n * @platform android\n */\nexport type ButtonOptions = {\n  /**\n   * Whether to show the next button.\n   * @default false\n   */\n  showNext?: boolean;\n  /**\n   * Whether to show the previous button.\n   * @default false\n   */\n  showPrevious?: boolean;\n  /**\n   * Whether to show the seek forward button.\n   * @default true\n   */\n  showSeekForward?: boolean;\n  /**\n   * Whether to show the seek backward button.\n   * @default true\n   */\n  showSeekBackward?: boolean;\n  /**\n   * Whether to show the subtitles button.\n   * - `true`: Button is always visible\n   * - `false`: Button is never visible\n   * - `undefined`: Button is visible only when subtitles are available (default behavior)\n   * @default undefined\n   */\n  showSubtitles?: boolean | null;\n  /**\n   * Whether to show the settings button.\n   * @default true\n   */\n  showSettings?: boolean;\n  /**\n   * Whether to show the play/pause button.\n   * @default true\n   */\n  showPlayPause?: boolean;\n  /**\n   * Whether to show the bottom control bar (containing time, progress bar, and buttons).\n   * When set to `false`, the entire bottom bar including the progress bar will be hidden.\n   *\n   * > **Note**: The bottom bar is always visible in fullscreen mode to allow users to exit fullscreen.\n   *\n   * @default true\n   */\n  showBottomBar?: boolean;\n};\n\n/**\n * Describes the orientation of the video in fullscreen mode. Available values are:\n * - `default`: The video is displayed in any of the available device rotations.\n * - `portrait`: The video is displayed in one of two available portrait orientations and rotates between them.\n * - `portraitUp`: The video is displayed in the portrait orientation - the notch of the phone points upwards.\n * - `portraitDown`: The video is displayed in the portrait orientation - the notch of the phone points downwards.\n * - `landscape`: The video is displayed in one of two available landscape orientations and rotates between them.\n * - `landscapeLeft`: The video is displayed in the left landscape orientation - the notch of the phone is in the left palm of the user.\n * - `landscapeRight`: The video is displayed in the right landscape orientation - the notch of the phone is in the right palm of the user.\n */\nexport type FullscreenOrientation =\n  | 'default'\n  | 'portrait'\n  | 'portraitUp'\n  | 'portraitDown'\n  | 'landscape'\n  | 'landscapeLeft'\n  | 'landscapeRight';\n\n/**\n * Determines whether the player keeps fullscreen when Picture in Picture (PiP) stops.\n * Only has an effect if the player was in fullscreen when PiP started.\n * - `'always'`: Always re-enter fullscreen when PiP stops.\n * - `'autoEnter'`: Re-enter fullscreen only when PiP was started automatically by the app going to the background.\n * - `'never'`: Do not re-enter fullscreen when PiP stops.\n */\nexport type KeepFullscreenOnPiPStopBehavior = 'always' | 'autoEnter' | 'never';\n\n/**\n * Describes the options for fullscreen video mode.\n */\nexport type FullscreenOptions = {\n  /**\n   * Specifies whether the fullscreen mode should be available to the user. When `false`, the fullscreen button will be hidden in the player.\n   * @default true\n   */\n  enable: boolean;\n  /**\n   * Specifies the orientation of the video in fullscreen mode.\n   * @default 'default'\n   * @platform android\n   * @platform ios\n   */\n  orientation?: FullscreenOrientation;\n  /**\n   * Specifies whether the app should exit fullscreen mode when the device is rotated to a different orientation than the one specified in the `orientation` prop.\n   * For example, if the `orientation` prop is set to `landscape` and the device is rotated to `portrait`, the app will exit fullscreen mode.\n   *\n   * > This prop will have no effect if the `orientation` prop is set to `default`.\n   * > The `VideoView` will never auto-exit fullscreen when the device auto-rotate feature has been disabled in settings.\n   *\n   * @default false\n   * @platform android\n   * @platform ios\n   */\n  autoExitOnRotate?: boolean;\n\n  /**\n   * Determines whether the player keeps fullscreen when Picture in Picture (PiP) stops.\n   * Only has an effect if the player was in fullscreen when PiP started.\n   *\n   * @default 'autoEnter'\n   * @platform ios\n   */\n  keepFullscreenOnPiPStop?: KeepFullscreenOnPiPStopBehavior;\n};\n"]}

package/package.json

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

package/plugin/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/withexpovideo.ts"],"version":"5.9.3"}

package/src/VideoView.types.ts

@@ -253,6 +253,20 @@ export type SubtitleStyle = {
 
   /**
    * The name of the font family used to render the subtitles.
+   *
+   * Custom fonts bundled with the app are supported, using the same name you would pass to a
+   * `<Text>` component's `fontFamily`:
+   * - On Android the font is looked up as an Android font resource (`res/font`, where `expo-font`'s
+   *   config plugin places fonts) and then through React Native's font manager, which covers the
+   *   `assets/fonts/<name>.ttf` convention and fonts registered at runtime.
+   * - On iOS the font must be registered with the system, which is what bundling it through
+   *   `expo-font`'s config plugin (`UIAppFonts`) does.
+   *
+   * The built-in system families always work — for example `sans-serif`, `sans-serif-medium`,
+   * `serif`, `monospace` and `cursive` on Android.
+   *
+   * > A name that matches no font falls back to the default typeface silently: neither platform
+   * > reports an unresolved font family, so double-check the spelling if nothing changes.
    */
   fontFamily?: string;