Video
@symbiote-native/video wraps expo-video, so
every SymbioteNative adapter can play video, not just React.
Installation
Section titled “Installation”npm install @symbiote-native/videoScaffolding 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 />;<script setup lang="ts">import { VideoView, useVideoPlayer } from '@symbiote-native/video/vue';
const player = useVideoPlayer( () => 'https://example.com/video.mp4', instance => { instance.loop = true; instance.play(); },);</script>
<template> <VideoView :player="player" :style="{ width: 320, height: 180 }" :nativeControls="true" /></template>import { Component } from '@angular/core';import { VideoView, injectVideoPlayer } from '@symbiote-native/video/angular';
@Component({ standalone: true, imports: [VideoView], template: ` <VideoView [player]="player()" [style]="{ width: 320, height: 180 }" [nativeControls]="true" /> `,})export class Clip { readonly player = injectVideoPlayer( () => 'https://example.com/video.mp4', instance => { instance.loop = true; instance.play(); }, );}<script lang="ts"> import { VideoView, useVideoPlayer } from '@symbiote-native/video/svelte';
const player = useVideoPlayer( () => 'https://example.com/video.mp4', instance => { instance.loop = true; instance.play(); }, );</script>
<VideoView player={player.current} style={{ width: 320, height: 180 }} nativeControls />import { VideoView, useVideoPlayer } from '@symbiote-native/video/solid';
const player = useVideoPlayer( () => 'https://example.com/video.mp4', instance => { instance.loop = true; instance.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.
Reaching the view functions
Section titled “Reaching the view functions”| 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.
Module functions
Section titled “Module functions”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
VideoViewon 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. useVideoPlayerreleases the player for you. It disposes of it when the component unmounts, and a changed source or options make a new one. A player fromcreateVideoPlayeris yours: callrelease()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: trueon 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
setVideoCacheSizeAsyncandclearVideoCacheAsyncbefore you create one. useEventanduseEventListenercome from the adapter, not from this package. See the aside above.
Common questions
Section titled “Common questions”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 docs: Video
- expo/expo#35012 black screen when reusing a player on Android
- expo/expo#31248 one player in several VideoViews on Android
- expo/expo#31722 contentFit cover overlaps on Android
- androidx/media#1107 the ExoPlayer bug behind it
- expo/expo#30275 VideoView ignores zIndex on Android
- expo/expo#34630 touch events on VideoView on Android
- expo/expo#33804 player not released on unmount
- expo/expo#9899 fullscreen orientation on Android
How the wrapper works
Section titled “How the wrapper works”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).