API reference

UMD global: WebRec · Default export / class: ScreenCapture · Full types: assets/sdk/webrec.d.ts

class ScreenCapture

Member	Description
`constructor(options?)`	Create recorder instance
`static isSupported()`	Minimum feature check
`static getCapabilities()`	Detailed capability object (includes `documentPictureInPicture`)
`static checkMimeType(type?)`	MIME support + fallback (`{ supported, mimeType }`)
`on / off`	Event subscription
`setOptions(partial)`	Merge configuration (also syncs toolbar float options)
`start(override?)`	Begin capture (opens float controls when `controlsPiP`)
`pause / resume`	Pause controls
`stop()`	Finalize Blob + URL → `RecordingResult`
`cancel()`	Discard session
`restart()`	Cancel + start
`getDisplayStream()`	Raw display `MediaStream` or `null`
`getMixedStream()`	Mixed stream fed to MediaRecorder, or `null`
`getPreview()`	In-progress preview `{ url, blob, duration }`
`screenshot()`	Capture live display stream; stores in `lastScreenshots`
`thumbnail(blob?)`	Generate poster image
`extractFrames(options?)`	Sample frames from last recording (or `blob`)
`openFrameGallery(index?)`	Open extracted frames in the lightGallery lightbox
`openScreenshotGallery(index?)`	Open captured screenshots in the lightGallery lightbox
`clearScreenshots()`	Clear `lastScreenshots` (revokes URLs by default)
`openControlsPiP()`	Open floating controls (slim popup or Document PiP)
`closeControlsPiP()`	Close floating controls
`download(filename?)`	Trigger file download
`share(opts?)`	Web Share API (native share sheet) when the browser can share files
`static canShare(blob?, filename?)`	Whether Web Share can send a video file
`listRecoverableSessions()`	IndexedDB sessions
`recover(sessionId)`	Rebuild Blob from chunks
`clearRecovery(sessionId?)`	Clear stored chunks
`use(plugin)`	Install plugin
`trim?(blob, opts)`	Present after `Trimmer` plugin
`convert?(blob, opts?)`	Present after `FFmpegConvert` plugin
`destroy()`	Teardown everything
`state`	`'idle' \| 'recording' \| 'paused' \| 'stopped'`
`lastResult` / `lastFrames` / `lastScreenshots`	Last stop result / extracted frames / live screenshots

ScreenCaptureOptions

Option	Default	Notes
`ui`	`'vanilla'`	`'vanilla' \| 'bootstrap' \| false` — `false` hides in-page toolbar
`theme`	`'light'`	`light \| dark \| minimal \| glass` (or custom)
`video`	—	`frameRate`, `width`, `height`, `bitrate`
`audio`	—	`microphone`, `systemAudio`, `deviceId`, `echoCancellation`, `noiseSuppression`, `bitrate`
`camera`	—	`enabled`, `width`, `height`, `deviceId`, `mirrored`, `includeInRecording`
`mimeType`	auto	Preferred MIME; falls back via `checkMimeType`
`timeslice`	`1000`	MediaRecorder chunk interval (ms)
`persistChunks`	`true`	IndexedDB crash recovery (`webrec` DB)
`shortcuts`	`true`	Install keyboard shortcuts plugin
`preferCurrentTab`	—	Chrome share-picker hint for current tab
`displaySurface`	—	`'monitor' \| 'window' \| 'browser'` hint
`excludeMonitorSurfaces`	—	`true` hides Entire Screen in the picker
`controlsPiP`	`false`	Open floating controls when recording starts
`countdown`	`0`	Seconds after the share picker before MediaRecorder starts. Float / Document PiP shows the timer off-page when enabled; screenshots are blocked during countdown.
`toolbar.preferDocumentPiP`	`false`	`false` = slim popup. `true` = always-on-top Document PiP
`toolbar.pictureInPicture`	—	Enable float / PiP behavior on toolbar
`toolbar.pipWidth / pipHeight`	—	Requested Document PiP size
`previewOnStop`	—	Show preview modal after stop when UI is enabled
`plugins`	`[]`	Plugins installed at construct time
`target`	—	Mount element for in-page toolbar

Events

Event	Notes
`start` `pause` `resume` `cancel` `destroy`	Lifecycle
`stop`	`RecordingResult`
`progress`	Elapsed / size while recording
`chunk`	`{ blob, index, size }`
`error` `warning` `info`	Diagnostics (`error` → `ScreenCaptureError`)
`screenshot` `screenshots`	Live captures
`thumbnail` `frames`	Poster / extracted frames
`controls:pip`	Float bar state
`countdown:start` `countdown` `countdown:end` `countdown:cancel`	Pre-record delay (`{ remaining, total }`)
`share`	Web Share completed
`recover`	IndexedDB recovery
`plugin:install`	Plugin installed

Errors

ScreenCaptureError / normalizeError(err) — codes: PERMISSION_DENIED, UNSUPPORTED, UNSUPPORTED_MIME, INVALID_STATE, DEVICE_NOT_FOUND, NOT_SECURE_CONTEXT, RECORDING_FAILED, STORAGE_ERROR, CANCELLED, UNKNOWN

Built-in plugins

Plugin	Notes
`KeyboardShortcuts()`	Also via `shortcuts: true`
`ChunkUploader({ upload, concurrency? })`	`upload(chunk, ctx)` per chunk
`ThumbnailPlugin({ auto?, width?, height? })`	Poster on stop when `auto`
`ScreenshotPlugin()` / `takeScreenshot(recorder)`	Screenshot helpers
`Trimmer()`	Adds `recorder.trim(blob, { start, end? })`
`WaveformPlugin({ container, … })`	Peer: wavesurfer.js (self-hosted)
`FFmpegConvert({ coreURL, wasmURL })`	Local FFmpeg under `assets/libraries/ffmpeg/core/` (no CDN). Adds `recorder.convert()`. Studio also uses `assets/js/convert-to-mp4.js` for one-click Download MP4.

UI & helpers

FloatingToolbar — slim popup / Document PiP float bar
PreviewModal — post-stop preview
CameraPip — webcam overlay bubble
BootstrapUI — toast(), settingsFormHtml(), readSettingsForm()
MediaEngine.listDevices() — enumerate mic/camera devices
FrameGallery — lightGallery-based lightbox
Utils: formatDuration, formatBytes, downloadBlob, extensionForBlob, defaultRecordingFilename, captureFrame, generateThumbnail, extractFrames, formatFrameTime, uid

Studio Download MP4

Flagship Studio records WebM by default, then Download MP4 converts in-browser with self-hosted FFmpeg.wasm (assets/libraries/ffmpeg/ + assets/js/convert-to-mp4.js). See Download & MP4 convert in the docs.

FrameGallery

lightGallery-based lightbox for frames and screenshots (bundled under its free, open-source GPLv3 license). See CREDITS.md.

Use cases & guidelines → · Documentation → · Browse examples → · Recovery · Errors · Floating controls · Studio