Capture SDK
@capturly/capture-sdk records on your user’s own device, from inside your own
product. It is the browser half of the
capture request flow: your backend creates the request
and mints a per-person link, and the SDK records against it.
npm install @capturly/capture-sdkPublic package with no dependencies. The recording engine is bundled in.
Where the credentials live
Your secret key never reaches a browser. It grants your whole organization.
What the browser gets is the per-person capability from
POST /v1/capture-requests/{id}/contacts — the contact id and the k query
parameter of the returned URL. That capability is scoped to one person,
revocable by removing the contact, and dead once the request’s deadline passes.
For a link anyone can use, take the request’s openLink.url and pass
{ mode: 'open', campaignId, key } instead. See Open links.
Hosting on your own site
The SDK calls capturly.app from your page, so your page’s origin has to be
on the capture request’s allowed sites. Set them when you create the request:
body: JSON.stringify({
title: 'Customer stories',
prompt: 'How did it go?',
status: 'active',
allowedOrigins: ['https://example.com', 'https://staging.example.com'],
}),Or set an organization-wide list once, on the Capture requests page under
Sites that can embed your requests. A request with no allowedOrigins of
its own uses that list. When the organization has a list, a request’s own
allowedOrigins can only narrow it: every origin it names must already be on
the organization’s list, or the create or update is refused with 400
origin_not_in_organization_list. With no organization list, the request’s own
list applies as given. Each entry is an origin, https://host[:port], with no path.
Takes upload straight from the page to Capturly’s storage, which accepts
only sites Capturly has enabled. Ask us to enable each site before you go
live; until then its uploads fail even when the request lists it. Test from
an enabled, deployed site rather than http://localhost, which is never
enabled.
A page that is not listed gets origin_not_allowed. The list decides which
sites may embed your requests; it is not what keeps them private. That is the
per-person key, so keep treating it like a password.
Calls carry no cookies or credentials, and baseUrl stays
https://capturly.app unless Capturly gave you another.
Open links
An open link records anyone who has it, with no roster. Turn it on with
openLinkEnabled: true; the request’s openLink.url is then
https://capturly.app/c/open/<campaignId>?k=<key>. Pass those two values:
const client = new CaptureClient({ access: { mode: 'open', campaignId, key } });
// ...
await client.submit({ releaseAccepted: true, displayName: 'Jane Doe' });An open link has no contact to name the take, so submit needs displayName;
without it, submit throws nothing_to_submit before anything uploads. Open links are capped per
request and rate-limited per IP more tightly than personal links; for a room
full of people on one network, give each person a contact.
Recording
import { CaptureClient } from '@capturly/capture-sdk';
if (!CaptureClient.isSupported()) {
// No amount of retrying fixes this. Offer another browser.
}
const client = new CaptureClient({
access: { mode: 'contact', contactId, key },
});
const stream = await client.preview(); // triggers the permission prompt
videoEl.srcObject = stream;
await client.start();
// …
const take = await client.stop(); // nothing has left the browser yet
previewEl.src = take.previewUrl; // let them watch it back
await client.submit({
releaseAccepted: true,
onProgress: (fraction) => setBar(fraction),
});
client.destroy();preview() is separate from start() so people can see themselves before
anything records. Between stop() and submit() the file sits in the
browser’s own storage, so a take can be reviewed and re-recorded with
discard() without anything reaching a server.
Capture requests need the respondent on camera. preview({ audioOnly: true })
is deprecated and logs a warning: an audio-only take is refused at submit
with camera_required.
Call destroy() on unmount, or the camera light stays on after the person has
navigated away.
Consent
If the request requires a release, read its release.text from the API and
show it before recording, then pass releaseAccepted: true only if the person
actually accepted it.
A consent record is written only when the request requires a release and you
pass true. Passing true without showing them anything records an agreement
that never happened, which is worse than none. Passing false on a request
that requires a release refuses the submission rather than storing an
unconsented take.
Errors
Every failure is a CaptureError with a code. What matters is whether
retrying can work, and who has to act:
| Code | Meaning | Retry? |
|---|---|---|
unsupported_browser | No MP4 recording in this browser | No — offer another browser |
permission_denied | Camera or microphone refused | No — your user must allow it |
no_devices | No camera or microphone found | No — your user must connect one |
not_recording, nothing_to_submit | Called out of order | No — fix the call sequence |
invalid_request | The call or its payload was rejected — missing release, missing name, take too long | No — fix the input |
link_expired | Unknown link, or a key that no longer matches | No |
origin_not_allowed | This page’s site is not on the request’s allowed sites | No — add it (see above) |
request_closed | The capture request is closed, past its deadline, revoked, or the workspace has lapsed | No |
superseded | Another take for this person landed first | No — their other submission is the live one |
quota_exceeded | No room right now: take too large, or the request is at its cap | No — the workspace owner must act |
camera_required | The take has no video; capture requests need the camera | No — record again with the camera on |
aborted | You aborted submit with its AbortSignal; the take stays in local storage | Yes, when you choose to submit again |
unknown | Capturly sent a response the SDK could not read. After submit, the take may already have landed | Not blindly — check the request’s submissions first |
rate_limited | Too many requests | Yes, after a pause |
upload_failed | Storage or the API failed server-side | Yes |
network | The request never reached Capturly | Yes |
Only the last three are worth retrying as-is. Retrying anything above them (other than a take you aborted yourself) re-uploads the whole take to fail the same way.
What it does not do
Multi-participant sessions. One person at a time. A room where several people record at once needs signaling, TURN and a join ceremony, and is not part of this package. Use the sessions API and the hosted recorder for that.
UI. You get a MediaStream and state events; you render the interface.
Transcription. Capturly delivers masters; transcription is your pipeline’s.
Learning that a take landed
The SDK is not told the recording id, and your backend should not trust the
browser for it. Use the capture_request.submission_received
webhook, or read
GET /v1/capture-requests/{id}/submissions, then download through
GET /v1/recordings/{id}.
Browser support
CaptureClient.isSupported() is the check to run before showing a record
button. It tests capabilities, not browser names or versions: it needs MP4
recording (MP4 MediaRecorder, or WebCodecs with MediaStreamTrackProcessor),
OPFS, and getUserMedia, which requires a secure context. Current Chrome, Edge
and Safari 16.4+ pass it. Firefox lacks both MP4 paths today, so it returns
false there.
In-app browsers
isSupported() reports what the browser actually exposes. Many in-app
browsers, the ones social and QR-scanner apps open links in, hide the camera
or local storage, so it returns false there. Offer a link that opens the page
in the device’s own browser. The iOS Camera app’s QR scanner opens Safari,
which works.