NitroPlay

Native-first video player for React Native with shared HLS transport, stream cache, and first-frame preview utilities.

Installation

yarn add @noma4i/nitro-play react-native-nitro-modules

npm install @noma4i/nitro-play react-native-nitro-modules

pnpm add @noma4i/nitro-play react-native-nitro-modules

react-native-nitro-modules >= 0.35.0 is a required peer dependency. React and React Native come from your app.

iOS

cd ios && pod install

Android

No extra steps - standard React Native 0.77+ autolinking handles the module.

Installing a specific tag from GitHub

If you need a tag or branch before it is published to npm:

yarn add @noma4i/nitro-play@github:noma4i/nitro-player#v1.0.0

Quick Start

import React from 'react';
import { NitroPlayerView } from '@noma4i/nitro-play';

export function FeedCard() {
  return (
    <NitroPlayerView
      source={{
        uri: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
        startup: 'lazy',
        transport: { mode: 'auto' },
        retention: {
          preload: 'metadata',
          offscreen: 'metadata',
          feedPoolEligible: true
        },
        preview: { mode: 'listener', autoThumbnail: true }
      }}
      resizeMode="contain"
      keepScreenAwake
      style={{ width: '100%', aspectRatio: 16 / 9 }}
    />
  );
}

Core API

Surface	Purpose
NitroPlayerView	Declarative native view with fullscreen, attach, and event props
NitroPlayer	Imperative player with properties, methods, and addEventListener
createNitroSource(config)	URI normalization and hybrid source factory
streamCache	Prefetch, header-aware stats, cache clear
videoPreview	Generated and cache-only first-frame lookup
usePlaybackState(player)	Subscribes to onPlaybackState and returns latest snapshot
useEvent(player, event, listener)	Managed event subscription helper

Deep-dive reference lives in docs/player-api.md.

Source DSL

Top-level NitroSourceConfig fields:

Field	Type	Purpose
uri	string | number	Network URL, local file:// URI, absolute local file path, or React Native asset
headers	Record<string, string>	Request headers (part of cache/preview identity)
metadata	NitroSourceMetadata	Player-facing media metadata
startup	'eager' | 'lazy'	Startup strategy (default eager)
buffer	BufferConfig	Explicit buffering policy
retention	NitroSourceRetentionConfig	Preload, offscreen retention, trim, feed eligibility
transport	NitroSourceTransportConfig	Transport routing policy
preview	NitroSourcePreviewConfig	First-frame generation policy

NitroSourceMetadata

All fields optional.

Field	Type
title	string
subtitle	string
description	string
artist	string
imageUri	string

NitroSourceRetentionConfig

Field	Type	Purpose
preload	'none' | 'metadata' | 'buffered'	Initial preload depth
offscreen	'cold' | 'metadata' | 'hot'	Offscreen retention level
trimDelayMs	number	Delayed trim window
feedPoolEligible	boolean	Participate in native feed hot pool

NitroSourceTransportConfig

Field	Type	Purpose
mode	'auto' | 'direct' | 'proxy'	Transport routing (default auto)

auto prefers the shared HLS proxy and falls back to direct when the proxy cannot be readied for the active source generation. direct skips proxy routing. proxy forces proxy routing.

NitroSourcePreviewConfig

Field	Type	Default	Purpose
mode	'listener' | 'always' | 'manual'	listener	Automatic first-frame behavior
autoThumbnail	boolean	true	Native auto-thumbnail placeholder for attached views
maxWidth	number	480	Output width hint
maxHeight	number	480	Output height hint
quality	number	70	JPEG quality hint

See docs/source-config.md for source profiles and identity rules, and docs/buffer-config.md for BufferConfig (Android minBufferMs, maxBufferMs, iOS preferredForwardBufferDurationMs, preferredPeakBitRate, shared livePlayback).

NitroPlayerView

Prop	Type	Notes
source	NitroSourceConfig	Required
playerDefaults	NitroPlayerDefaults	Declarative startup state
controls	boolean	Native controls
resizeMode	ResizeMode	contain | cover | stretch | none
keepScreenAwake	boolean	Screen wake lock
surfaceType	'surface' | 'texture'	Android only
style	ViewStyle	Inherited from ViewProps
onAttached	(player: NitroPlayer) => void	View attached
onDetached	() => void	View detached
onFullscreenChange	(value: boolean) => void	Fullscreen state changed
willEnterFullscreen	() => void	Pre-enter hook
willExitFullscreen	() => void	Pre-exit hook

NitroPlayerViewRef

Member	Type	Notes
player	NitroPlayer	Imperative player backing the view
isAttached	boolean	Native attach state
enterFullscreen()	void	Enter fullscreen
exitFullscreen()	void	Exit fullscreen
addEventListener(event, listener)	ListenerSubscription	View events only

NitroPlayer

Properties

Property	Type	Get	Set
source	NitroPlayerSource	yes	no
status	NitroPlayerStatus	yes	no
playbackState	PlaybackState	yes	no
memorySnapshot	MemorySnapshot	yes	no
duration	number	yes	no
currentTime	number	yes	yes
volume	number	yes	yes
muted	boolean	yes	yes
loop	boolean	yes	yes
rate	number	yes	yes
isPlaying	boolean	yes	no
isBuffering	boolean	yes	no
isVisualReady	boolean	yes	no
bufferDuration	number	yes	no
bufferedPosition	number	yes	no
mixAudioMode	MixAudioMode	yes	yes
ignoreSilentSwitchMode	IgnoreSilentSwitchMode	yes	yes
playInBackground	boolean	yes	yes
playWhenInactive	boolean	yes	yes

Methods

Method	Returns	Notes
play()	void	Start playback; valid before onLoad
pause()	void	Pause playback
seekTo(seconds)	void	Absolute seek
seekBy(seconds)	void	Relative seek
initialize()	Promise<void>	Manual initialization
preload()	Promise<void>	Warm source without starting playback
replaceSourceAsync(source)	Promise<void>	Swap active source
clearSourceAsync()	Promise<void>	Clear source and keep player reusable
release()	void	Terminal teardown
addEventListener(event, listener)	ListenerSubscription	Subscribe to a player event

PlaybackState

Field	Type	Notes
status	NitroPlayerStatus	idle | loading | buffering | playing | paused | ended | error
currentTime	number	Seconds
duration	number	Seconds
bufferDuration	number	Seconds buffered ahead
bufferedPosition	number	Absolute buffered position
rate	number	Effective playback rate
isPlaying	boolean	Native playing state
isBuffering	boolean	Native buffering state
isVisualReady	boolean	First visual frame readiness
error	PlaybackError | null	Present when status === 'error'
nativeTimestampMs	number	Native event timestamp

Player Events

Event	Payload
onPlaybackState	PlaybackState
onLoadStart	onLoadStartData
onLoad	onLoadData
onError	PlaybackError
onFirstFrame	onFirstFrameData
onBandwidthUpdate	BandwidthData
onVolumeChange	onVolumeChangeData

Subscribe directly on the player instance:

const sub = player.addEventListener('onPlaybackState', state => {
  console.log(state.status, state.currentTime);
});
// later
sub.remove();

Stream Cache & Preview

API	Returns	Purpose
streamCache.prefetch(source)	Promise<void>	Warm transport and first segment cache
streamCache.getStats()	Promise<StreamCacheStats>	Total cache stats
streamCache.getStats(source)	Promise<StreamSourceCacheStats>	Per-source stats, header-aware
streamCache.clear()	Promise<boolean>	Clear stream disk cache
videoPreview.getFirstFrame(source)	Promise<string | null>	Cached or generated first-frame path
videoPreview.peekFirstFrame(source)	Promise<string | null>	Cached-only lookup (no generation)
videoPreview.clear()	Promise<boolean>	Clear preview artifacts

All source-taking methods accept either a URL string or { uri, headers }. Use the object form whenever headers are part of request identity. See docs/stream-runtime.md.

Hooks

Hook	Signature	Purpose
usePlaybackState	(player: NitroPlayer | null | undefined) => PlaybackState | null	Subscribes to onPlaybackState and returns latest snapshot
useEvent	<T extends keyof AllNitroPlayerEvents>(player, event, callback) => void	Managed event subscription with automatic cleanup

createNitroSource

import { createNitroSource } from '@noma4i/nitro-play';

const source = createNitroSource({ uri: require('./intro.mp4') });

Resolves React Native asset references via Image.resolveAssetSource, validates the URI, and returns a hybrid NitroPlayerSource. Usually you do not need to call this manually: NitroPlayerView and NitroPlayer accept a plain NitroSourceConfig and normalize it internally. Call createNitroSource explicitly when you want to reuse the same native source object across multiple replaceSourceAsync calls.

Common Types

Type	Values / Shape	Purpose
NitroPlayerStatus	idle | loading | buffering | playing | paused | ended | error	Player status
ResizeMode	contain | cover | stretch | none	View scaling
MixAudioMode	mixWithOthers | doNotMix | duckOthers | auto	Audio session mix behavior
IgnoreSilentSwitchMode	auto | ignore | obey	iOS silent switch handling
PreloadLevel	none | metadata | buffered	Initial preload depth
OffscreenRetention	cold | metadata | hot	Offscreen retention level
MemoryRetentionState	cold | metadata | hot	Retention snapshot value
MemorySnapshot	{ playerBytes, sourceBytes, totalBytes, preloadLevel, retentionState, isAttachedToView, isPlaying }	Current player memory footprint
NitroPlayerDefaults	{ loop?, muted?, volume?, rate?, mixAudioMode?, ignoreSilentSwitchMode?, playInBackground?, playWhenInactive? }	Declarative startup state for NitroPlayerView.playerDefaults
NitroPlayerError	Discriminated on LibraryError | PlayerError | SourceError | NitroPlayerViewError | UnknownError	Typed error hierarchy used by onError and thrown runtime errors

Runtime Contract

Area	Behavior
Early play	play() before onLoad is canonical
Playback state	Built from native readiness, buffering, and actual playing state
HLS startup	Native runtime uses lazy startup and bounded startup recovery
Proxy fallback	transport.mode='auto' may fall back to direct URL if proxy is unavailable
First frame	onFirstFrame is sticky per active source generation
Preview policy	preview.mode='listener' auto-captures for attached views when autoThumbnail !== false; always warms preview automatically; manual disables background auto-warmup
Mounted-view reveal	Attached NitroPlayerView owns native auto-thumbnail/first-frame placeholder by default; app code should not require JS poster swapping for active playback surfaces
Manual preview	videoPreview.getFirstFrame(source) returns cached/generated frame path
Cached preview reuse	videoPreview.peekFirstFrame(source) returns only an existing cached frame path and never starts generation
Stream/preview identity	{ uri, headers } is the canonical identity for cache stats and preview artifacts
Stream cache	streamCache.prefetch(source) is safe to call repeatedly

Absolute local file paths are accepted on both iOS and Android and are normalized internally to file:// URLs. App code should prefer canonical file:// URIs when it owns freshly recorded media paths.

Example App

The local example is a runtime lab, not just a smoke test.

It covers:

• hero playback switching between transport.mode='auto', header-isolated HLS, and direct MP4
• streamCache.prefetch/getStats/clear and videoPreview.getFirstFrame/peekFirstFrame/clear
• a three-player feed stress block with the same HLS URL under different headers
• live observation of onLoad, onError, onFirstFrame, bandwidth, attach state, and isVisualReady

Documentation

File	Purpose
docs/player-api.md	Public player, view, events, hooks
docs/source-config.md	Source DSL and normalized source model
docs/buffer-config.md	buffer tuning
docs/lifecycle-guide.md	retention model and startup intent
docs/memory-management.md	Retention states, snapshots, feed pool
docs/stream-runtime.md	Shared transport runtime, streamCache, videoPreview
docs/migration-1.0.md	Migration to the current beta DSL

Requirements

Dependency	Version
React Native	>= 0.77.0
react-native-nitro-modules	>= 0.35.0

License

MIT