Video stream API
Scoped camera preview, controls, and QR detection.
Native enablement is internalPlugins.videoStream. The dependency is @capgo/camera-preview@8.14.2. pluginOptions.VideoStream.usageDescription is required.
Session contract
startVideoStream(options) returns Effect<VideoStreamSession, VideoStreamError, Bridge | BrowserVideoStream | Scope>. The caller's scope owns preview presentation, camera resources, and listeners. Closing the scope stops the session.
| Option | Type | Default |
|---|---|---|
viewfinder | HTMLElement, required | Mounted element with nonzero size. |
facing | "front" or "rear" | "rear" |
onDetect | Callback receiving a string | Omitted. Receives QR values. |
The session exposes Effect values info and switchCamera, plus setZoom(level) and setTorch(enabled) returning Effects. Controls require Bridge.
videoStreamLive(effect) provides BrowserVideoStreamLive. BrowserVideoStream is the injectable browser service.
Status fields
VideoStreamInfoSchema validates VideoStreamInfo:
| Field | Type |
|---|---|
facing | "front" or "rear" |
zoom | Optional { min, max, current }, all finite numbers |
torch | Boolean |
torchAvailable | Boolean |
frameRate | Optional finite number |
detectionAvailable | Boolean |
| Capability | Android | iOS | Browser |
|---|---|---|---|
| Preview | Behind transparent WebView cut-out | Behind transparent WebView cut-out | getUserMedia |
| QR detection | Native preview detector | Native preview detector | Requires BarcodeDetector |
| Video file recording | Not exposed | Not exposed | Not exposed |
Errors and hook
| Error | Meaning |
|---|---|
BridgeError | Transport or validation failure; native sessions require listener support |
PermissionDenied | Native cameraPermissionDenied |
Unavailable | Includes missing mounted viewfinder in the hook |
useVideoStream({ viewfinder, facing?, onDetect? }) accepts a React ref rather than an element. It returns start, stop, switchCamera, setZoom, setTorch, running, loading, value, and error. Unmount and provider replacement release the session.
Source: video implementation.