Skip to content

Video

@symbiote-native/video wraps expo-video, so every SymbioteNative adapter can play video, not just React.

Terminal window
npm install @symbiote-native/video

Scaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --video (or add --video in an existing app) installs and wires this for you.

import { VideoView, useVideoPlayer } from '@symbiote-native/video/react';
const player = useVideoPlayer('https://example.com/video.mp4', player => {
player.loop = true;
player.play();
});
<VideoView player={player} style={{ width: 320, height: 180 }} nativeControls />;

The player is the native VideoPlayer object, the framework supplies only how it is created and released.

Adapter Player
React useVideoPlayer(source, setup?, options?)
Vue useVideoPlayer(source, setup?, options?), a computed ref
Solid useVideoPlayer(() => source, setup?, () => options), an accessor
Svelte useVideoPlayer(() => source, setup?, () => options).current
Angular injectVideoPlayer(() => source, setup?, () => options), a signal

setup runs once on each new player, a changed source or options make a new one. createVideoPlayer(source, options?) makes a player that you release yourself.

Adapter How
React ref gets an IVideoViewHandle
Solid ref={handle => ...} gets the handle
Vue a template ref, the functions are exposed
Svelte bind:this, the component exports the functions
Angular @ViewChild(VideoView), the functions are members

The functions are enterFullscreen, exitFullscreen, startPictureInPicture and stopPictureInPicture. On Android exitFullscreen works only from a native listener, the JS runtime sleeps in fullscreen.

isPictureInPictureSupported(), setVideoCacheSizeAsync(bytes), clearVideoCacheAsync() and getCurrentVideoCacheSize(). The cache functions work only while no player exists.

Background playback and Picture in Picture

Section titled “Background playback and Picture in Picture”

The package writes nothing by default. For iOS add audio to UIBackgroundModes in Info.plist. For Android choose the “Background video playback” bundle (the foreground service and its permissions), and give the main activity android:supportsPictureInPicture="true" for Picture in Picture.

The web build is not ported.

  • One player, one VideoView on Android. Mounting several views with the same player does not work there, a platform limitation. iOS accepts it. Create a player per visible view, or move the player to the new view only after the old one is gone.
  • useVideoPlayer releases the player for you. It disposes of it when the component unmounts, and a changed source or options make a new one. A player from createVideoPlayer is yours: call release() when you are done, or it leaks.
  • Android renders on a surface by default. surfaceType="surfaceView" is the efficient choice, surfaceType="textureView" composes like an ordinary view and costs more performance.
  • Caching is per source. Set useCaching: true on the source object. The cache is persistent and trimmed least-recently-used, 1 GB by default, and works offline for what it holds. iOS cannot cache HLS, and DRM-protected video is not cached on either platform.
  • The cache functions work only while no player exists, so call setVideoCacheSizeAsync and clearVideoCacheAsync before you create one.
  • useEvent and useEventListener come from the adapter, not from this package. See the aside above.

The screen is black on Android though the controls show. The usual cause is one player rendered in more than one VideoView, or a player moved from one view to another while both still exist. Android supports a player in a single view at a time. Keep one VideoView per player, and unmount the old view before the new one takes the player.

Two videos overlap or one is drawn out of bounds on Android. With contentFit="cover", two overlapping views trigger a bug in ExoPlayer itself. Set surfaceType="textureView" on the views. It composes like a normal view, so overlap and stacking behave, at some cost in performance.

A VideoView ignores zIndex on Android. Reported for the default surface, where a video is drawn above everything around it. If you stack videos or put views over one, such as a deck of cards, try surfaceType="textureView".

Touch handlers on the VideoView do not fire on Android. Reported upstream. Put the handler on a plain view that wraps or sits over the player instead of on the native view itself.

Audio keeps playing after the screen closes, or the player is never released. A player made with useVideoPlayer is released when its component unmounts. One made with createVideoPlayer is not: call player.release() yourself, for example in your cleanup. If you do not want playback to continue in the background, leave staysActiveInBackground off.

Fullscreen will not rotate on Android. Android follows the app’s orientation lock, while iOS’s fullscreen player rotates on its own. Unlock the orientation for the fullscreen session with @symbiote-native/screen-orientation and lock it again when the player closes.

How do I cache a video? Pass { uri, useCaching: true } as the source. Use setVideoCacheSizeAsync(bytes) to set the limit, getCurrentVideoCacheSize() to read the size, and clearVideoCacheAsync() to empty it.

How do I play audio in the background or in Picture in Picture? It needs native setup first, see Background playback and Picture in Picture. That means audio in UIBackgroundModes on iOS, the background-playback bundle on Android, and android:supportsPictureInPicture="true" on the main activity.

Sources:

expo-video’s JS is hand-ported into this package’s core/. The player is the native VideoPlayer shared object, and useVideoPlayer and injectVideoPlayer create and release it through createVideoPlayerController, built on the engine’s createJsonKeyedResourceController so a changed source or options make a new player. VideoView is one component per platform: the native VideoView on iOS, and SurfaceVideoView or TextureVideoView on Android, with the view functions following whichever surface the last render chose. VideoAirPlayButton is a plain view off iOS. Every adapter only hands over its host node, and the shared createVideoView does the rest. The native code is never vendored: expo-modules-autolinking resolves it from node_modules (see the native setup guide).