Desktop SDK Raw Media

Desktop SDK Raw Media brings bot-quality capture to the Desktop Recording SDK without adding a standard recording bot tile to the meeting. It provides more consistent media quality while reducing CPU and memory usage on the user's computer.

Your existing Desktop SDK integration remains the same: detect a meeting, create a Desktop SDK Upload, and call startRecording. The SDK automatically uses Raw Media when it is enabled and its platform and permission requirements are met. Otherwise, it uses local capture.

Why use Raw Media?

When Raw Media is active:

• Recording uses substantially less CPU and memory on the user's computer.
• Participant video and screenshare quality do not depend on the meeting window's size, position, or visibility.
• Video capture continues when the meeting window is covered, minimized, or on another macOS desktop space.
• Separate participant audio is available for accurate speaker attribution and diarization.
• Realtime transcripts and participant events are more consistent because they are not derived from the visible meeting layout.
• Microsoft Teams meeting URLs are available through meeting-updated without Full Disk Access.

Availability and billing

Raw Media supports:

Requirements:

• macOS 13 or later
• Apple Silicon Mac
• Raw Media enabled for your workspace by your Recall.ai account team
• The standard accessibility permission for meeting detection
• The relevant automation permission granted before a meeting begins

For Google Meet, one of the supported browsers must be the user's default browser before you request browser-automation.

Raw Media is not currently available for:

• Windows
• Google Meet in Safari
• Google Meet in Chrome Beta
• Google Meet Progressive Web Apps
• Unsupported Chromium-based browsers

Unsupported configurations continue to use local capture. See Desktop Recording SDK Supported Platforms for general Desktop SDK platform support.

Desktop SDK Raw Media recordings are billed at meeting bot rates, not Desktop Recording SDK rates.

Set up automation access

Raw Media requires one additional macOS permission for each supported meeting platform:

• Microsoft Teams: teams-automation
• Google Meet: browser-automation

Request this permission from a user-initiated onboarding or settings flow before the user joins a meeting.

Do not request automation access automatically at application startup or while a meeting is in progress. These permissions are not requested through acquirePermissionsOnStartup.

const RecallAiSdk = require("@recallai/desktop-sdk");

await RecallAiSdk.init({
  apiUrl: "https://us-west-2.recall.ai",
  acquirePermissionsOnStartup: [],
});

RecallAiSdk.addEventListener("permission-status", ({ permission, status }) => {
  if (
    permission === "teams-automation" ||
    permission === "browser-automation"
  ) {
    console.log(`${permission}: ${status}`);
  }
});

// Call the relevant method from an explicit user interaction.
async function enableTeamsRawMedia() {
  await RecallAiSdk.requestPermission("teams-automation");
}

async function enableGoogleMeetRawMedia() {
  await RecallAiSdk.requestPermission("browser-automation");
}

Request only the permission for the meeting platforms your application supports.

Recommended permission UX

Before calling requestPermission, explain that:

• macOS may ask the user to allow your application to control Teams or their browser.
• The meeting application or browser may restart once during setup.
• Open browser tabs and the user's current session will be restored automatically.
• Setup must be completed before the meeting begins.

Use a dedicated action such as Enable Teams recording or Enable Google Meet recording so the user can choose when setup occurs.

Permission states

Listen for permission-status to update your onboarding UI.

For Google Meet, automation access is browser-specific. If the user changes their default browser, ask them to complete setup again.

Keep local capture permissions

Continue requesting the standard Desktop SDK recording permissions:

• accessibility
• microphone
• screen-capture, or system-audio for audio-only recording

These permissions allow the SDK to record locally when Raw Media is unavailable.

Apple Events usage description

Add an NSAppleEventsUsageDescription entry to your app's Info.plist:

NSAppleEventsUsageDescription: "Allow this app to prepare supported meeting applications for high-quality recording."

See macOS Permissions for the complete permission setup and required Info.plist entries.

Start recording

There is no separate Raw Media API. Continue using startRecording:

RecallAiSdk.addEventListener("meeting-detected", async (evt) => {
  const upload = await createDesktopSdkUploadOnYourBackend();

  await RecallAiSdk.startRecording({
    windowId: evt.window.id,
    uploadToken: upload.upload_token,
  });
});

The SDK selects Raw Media automatically when it is enabled for the workspace and available for the detected meeting.

Disable Raw Media for a recording

Raw Media is enabled by default when it is available in your Recall.ai workspace. To disable it for a specific recording and use local capture, set disableRawMedia to true:

await RecallAiSdk.startRecording({
  windowId: evt.window.id,
  uploadToken: upload.upload_token,
  disableRawMedia: true,
});

disableRawMedia defaults to false. It disables Raw Media when Raw Media is enabled and available in your Recall.ai workspace. Keep the standard local capture permissions configured when using this option.

Confirm whether Raw Media is active

Read rawMedia from the recording-started event to determine how that recording is being captured:

• true: the recording is using Desktop SDK Raw Media.
• false: the recording is using local capture, including after a fallback.

RecallAiSdk.addEventListener("recording-started", ({ window, rawMedia }) => {
  console.log(
    `Recording ${window.id} is using ${rawMedia ? "Raw Media" : "local capture"}`,
  );
});

Use this field as the source of truth for the active recording.

Pause, resume, and stop recording

Use the standard Desktop SDK recording controls for both Raw Media and local recordings:

await RecallAiSdk.pauseRecording({ windowId });
await RecallAiSdk.resumeRecording({ windowId });
await RecallAiSdk.stopRecording({ windowId });

You do not need a separate lifecycle implementation for Raw Media.

Send chat messages

While a Raw Media recording is active, use sendChatMessage to send a message to the meeting chat through the same recording:

await RecallAiSdk.sendChatMessage({
  windowId,
  message: "This meeting is being recorded.",
});

sendChatMessage accepts:

This method is available for active Microsoft Teams and Google Meet Raw Media recordings. It is not available when the SDK is using local capture. Check recording-started.rawMedia before showing chat controls or calling this method.

Local fallback

The SDK selects the capture method when startRecording is called. If the Raw Media prerequisites are unavailable at that time, the SDK uses local capture when the standard recording permissions are available. Common reasons include:

• The meeting platform, browser, or operating system is unsupported.
• Automation access has not been granted.
• Google Meet is open in a browser other than the configured default browser.
• Required meeting details are not available when recording begins.
• Raw Media is not enabled for the workspace or cannot be started for the meeting.

Check recording-started.rawMedia to determine whether fallback occurred. The SDK does not change capture methods in the middle of a recording.

Events, outputs, and webhooks

Raw Media uses the same Desktop SDK Upload and recording configuration as local capture. Your existing event listeners, realtime endpoints, callbacks, artifact downloads, and upload webhooks continue to work.

This includes:

• Mixed audio and video artifacts
• Realtime transcripts and participant events
• Separate participant audio for accurate speaker attribution and diarization
• Desktop SDK callbacks, including audio_mixed_raw.data
• Desktop SDK Upload completion and failure webhooks

To receive separate participant audio, include audio_separate_raw in the Desktop SDK Upload's recording_config. You can also subscribe to audio_separate_raw.data through a desktop_sdk_callback realtime endpoint. Separate participant audio is available only when the recording uses Raw Media; the configuration is ignored if the recording falls back to local capture.

Frequently asked questions

Is a meeting bot visible?

No standard recording bot tile is added to the meeting.

Does Raw Media require Full Disk Access?

Raw Media does not require Full Disk Access for media capture. Teams Raw Media can also provide meeting URLs through meeting-updated without Full Disk Access.

If your application relies on local Teams URL detection or local fallback, follow the existing Full Disk Access guidance for those features.

What happens if the user does not grant automation access?

The SDK uses local capture, provided the standard recording permissions are available.

Will the browser restart?

The supported browser may restart once while browser-automation is being configured. The SDK restores the browser session so users do not lose their open tabs or place.

The SDK will not restart the browser while a Google Meet call is active.

Can users record Google Meet in Safari?

Yes. Safari remains supported through local capture on macOS, but does not currently use Raw Media.

Does Raw Media work on Windows?

Not currently. Windows continues to use local Desktop SDK capture.