Build a custom recorder with DadanRecorder

DadanRecorder is the SDK’s headless recorder. It captures the screen, camera or microphone, reports what is happening through events and uploads the result, but it draws nothing. You build the interface. Use it when the built-in studio cannot match your design, or when recording has to fit inside an existing screen.

If you only want to adjust colors or hide a few controls, customizing the built-in studio is less work.

npm install @dadan-io/record-sdk

DadanRecorder has no React dependency. It is also re-exported by the React, Vue and Angular packages, so you can import it from those if you already use one.

import { DadanRecorder } from "@dadan-io/record-sdk";

const recorder = await DadanRecorder.create({
  publicAppId: import.meta.env.VITE_DADAN_PUBLIC_APP_ID,
  mode: "both",
  videoTitle: "Walkthrough",
  folderId: "123456",
  recordingQuality: "1080p",
  maxDurationSeconds: 300,
});

create() resolves with the recorder and then emits ready. Subscribing to ready after await still works: late listeners are called once.

The recorder moves through these states, which you can read at any time with recorder.getState():

Drive your interface from events rather than polling the state.

const preview = document.querySelector<HTMLVideoElement>("#preview")!;
const startButton = document.querySelector<HTMLButtonElement>("#start")!;
const stopButton = document.querySelector<HTMLButtonElement>("#stop")!;

recorder.on("preview.ready", ({ stream }) => {
  preview.srcObject = stream;
});

recorder.on("recording.started", () => {
  startButton.hidden = true;
  stopButton.hidden = false;
});

recorder.on("upload.progress", ({ percent }) => {
  stopButton.textContent = `Uploading ${Math.round(percent)}%`;
});

recorder.on("recording.completed", ({ video }) => {
  if (video) console.info("Ready to watch:", video.sharedUrl);
});

startButton.addEventListener("click", () => {
  void recorder.start();
});

stopButton.addEventListener("click", () => {
  void recorder.stop();
});

• Call start() from a click. Browsers only open the screen picker in response to a user action.
• Mute the preview. Give the preview element the muted, autoplay and playsinline attributes so it does not echo the microphone and plays on iOS.
• start() accepts { mode, cameraDeviceId, micDeviceId } to override the mode or devices for that take.
• Other controls: pause(), resume(), cancel() (discard the take), restart() (new take after a stop) and getDuration() (elapsed milliseconds).

Set autoUpload: false and the recorder keeps the file after stop(). Show it, then upload when the person confirms:

const reviewRecorder = await DadanRecorder.create({
  publicAppId: import.meta.env.VITE_DADAN_PUBLIC_APP_ID,
  mode: "camera",
  autoUpload: false,
});

async function finishTake(player: HTMLVideoElement) {
  await reviewRecorder.stop();
  const blob = reviewRecorder.getBlob();
  if (blob) player.src = URL.createObjectURL(blob);
}

async function sendTake() {
  const video = await reviewRecorder.retryUpload();
  console.info("Uploaded", video.id);
}

Despite its name, retryUpload() is also how you start the first upload when autoUpload is off. Call URL.revokeObjectURL on the preview URL once you no longer need it.

const { cameras, mics } = await recorder.getDevices();
if (cameras[0]) await recorder.setCamera(cameras[0].deviceId);
if (mics[0]) await recorder.setMicrophone(mics[0].deviceId);

recorder.setMicrophoneEnabled(false);
recorder.setCameraEnabled(true);

recorder.on("devices.changed", ({ cameras, mics }) => {
  console.info(`${cameras.length} cameras, ${mics.length} microphones`);
});

• setMicrophoneEnabled and setCameraEnabled work before start(). The choice is applied when capture begins.
• Muting the microphone in screen modes mutes only the microphone, not the system or tab audio.
• Devices cannot be switched while recording (cannot_switch_device_while_recording).
• getAudioLevels() returns { level } for a microphone meter, and getPermissions() gives a best-effort view of camera and microphone permissions.

Hooks run before an action and can stop it. Return false, or reject, to block the action:

const guardedRecorder = await DadanRecorder.create({
  publicAppId: import.meta.env.VITE_DADAN_PUBLIC_APP_ID,
  mode: "screen",
  hooks: {
    beforeStart: async () =>
      window.confirm(
        "Recording will include everything on the screen you share. Continue?",
      ),
    beforeCancel: async () => window.confirm("Discard this recording?"),
    beforeUpload: async () => navigator.onLine,
  },
});

Hooks fail closed: if one throws, returns false or takes longer than hookTimeoutMs (10 seconds by default), the action does not happen. When beforeStart blocks, start() rejects with hook_rejected, no error event is emitted, the state returns to ready and any shared screen is released.

With maxDurationSeconds, the recorder emits recording.limitReached and stops on its own when the limit is reached. Change the limit later with recorder.setMaxDuration(seconds).

Subscribe with recorder.on(name, handler), which returns a function that removes the listener. once and off are also available.

• Uploads are resumable and retried automatically. upload.retrying tells you when.
• If an upload fails, stop() rejects with a DadanSdkError and the take stays available. Call retryUpload() to try again.
• cancelUpload(), cancel() and destroy() stop an upload in progress and delete the unfinished video.
• An unfinished take can be kept in the browser for up to 24 hours. See Record SDK production checklist.

Call recorder.destroy() when the view that owns the recorder goes away. It releases the camera, microphone and screen, removes listeners and stops any upload in progress.

For complete control, @dadan-io/record-sdk also exports the building blocks DadanRecorder uses, such as startHeadlessCapture, listMediaDevices, attachMediaStream and uploadRecording, plus persistPendingTake and recoverPendingTake for keeping unsent takes. Most apps never need them; start with DadanRecorder and only drop down if you hit a limit.