A screen recording API that turns screen + camera into one finished video

What the screen recording API does

Screen recordings are usually two recordings: the screen, and the person talking over it. The API takes both and produces one video, with the camera drawn over or beside the screen and both audio tracks mixed in sync. Both inputs are mapped onto one frame grid at the faster input's frame rate (never below 20 fps, which copes with the sparse frames of a screen capture), the camera overlay is drawn at the top quality level, and it is then scaled down for the lower levels.

You can record in the browser with the <video-piper-recorder> web component, which handles the screen picker, the camera, the countdown and the upload for you, or build your own capture and call the API directly.

Layouts

• Picture-in-picture (the default): the camera sits in a corner of the screen. Set {"type": "pip", "position": "bottom-right", "size": "medium"}, where the position is bottom-right, bottom-left, top-right or top-left and the size is small, medium or large. The plain string "pip" means bottom-right, medium.
• Side by side: the screen takes about 70% and the camera about 30%, next to each other on a dark background. Use {"type": "side-by-side", "screen": "left"} or "right".

Changed your mind? Reprocess the video with another layout; nothing is uploaded again. Redaction regions, if you use them, refer to the combined picture, so the camera bubble can be blurred too.

Create a screen + camera video

Create the video with the screen file, the layout and the camera file. The response adds camera.partSize and camera.partCount; request the camera's part URLs with "file": "camera", upload both files, then call complete once.

POST /videos
{ "fileName": "screen.webm", "sizeBytes": 209715200,
  "layout": { "type": "pip", "position": "top-left", "size": "small" },
  "camera": { "fileName": "camera.webm", "sizeBytes": 52428800 } }

Record both in the same session so they line up. Browser recordings are WebM, which is fully supported.

Upload while recording

For live takes, the API can start work before the recording ends. Create the video with "streaming": true (no sizeBytes) and "prestart": true, so a processing container boots and waits while the person records. Then:

1. Request each part's URL with its exact size. Every part except the last must be at least 5 MiB; the web component uploads about every 8 MiB.
2. While recording, send POST /videos/{id}/heartbeat about every 10 seconds. If heartbeats stop for 2 minutes the waiting job gives up.
3. When the recording ends, call complete with the totals: {"source": {"sizeBytes": …, "partCount": …}}. To cancel instead, call abort, which deletes the parts and removes the record.

A prewarmed container waits up to 5 minutes. For longer recordings it stands down and starts normally when you complete, about 30 to 60 seconds later. When it all lines up, a one-minute recording was ready about a minute after Stop.

Or use the recorder component

If you don't want to write capture code, the <video-piper-recorder> element does the browser side and uses a one-video upload token, so your API key never reaches the page. It offers screen + camera, screen, camera and file modes, a layout picker whose live preview matches the layout the video is made with, review and retake, and events such as vp-uploaded and vp-ready. See the embeddable video recorder for the attributes, the token flow and a copy-ready example.

After the recording

Because the result is an ordinary video, everything else in the API applies: trim and edit it, redact it, caption it (Pro and Scale), and play it with the embeddable player. A video.ready webhook tells your server when it is done, carrying the metadata you attached to the upload token.

Which plans include screen recording

Screen recording, screen + camera and upload-while-recording are Pro and Scale features. Plain camera recording, uploading a file and everything else in the core API are on every plan.

Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.

In the documentation

• Screen + camera
• Uploading while recording
• The video-piper-recorder web component
• Upload tokens
• Uploads from a browser

Frequently asked questions