---
updatedAt: 2026-10-27T12:02:11.000Z
agentTools:
  projectIndex: https://docs.recall.ai/llms.txt
---

# Desktop Recording SDK Overview

Integrate the Desktop Recording SDK to detect and record meetings and retrieve recordings and transcripts in your Electron app without adding a standard recording bot tile to the call.

<Embed title="" typeOfEmbed="youtube" url="https://www.youtube.com/watch?v=KSxm-Dupc88" href="https://www.youtube.com/watch?v=KSxm-Dupc88" html="%3Ciframe%20class%3D%22embedly-embed%22%20src%3D%22%2F%2Fcdn.embedly.com%2Fwidgets%2Fmedia.html%3Fsrc%3Dhttps%253A%252F%252Fwww.youtube.com%252Fembed%252FKSxm-Dupc88%253Ffeature%253Doembed%26display_name%3DYouTube%26url%3Dhttps%253A%252F%252Fwww.youtube.com%252Fwatch%253Fv%253DKSxm-Dupc88%26image%3Dhttps%253A%252F%252Fi.ytimg.com%252Fvi%252FKSxm-Dupc88%252Fhqdefault.jpg%26type%3Dtext%252Fhtml%26schema%3Dyoutube%22%20width%3D%22854%22%20height%3D%22480%22%20scrolling%3D%22no%22%20title%3D%22YouTube%20embed%22%20frameborder%3D%220%22%20allow%3D%22autoplay%3B%20fullscreen%3B%20encrypted-media%3B%20picture-in-picture%3B%22%20allowfullscreen%3D%22true%22%3E%3C%2Fiframe%3E" />

<br />

The Desktop Recording SDK allows an Electron application to record Zoom, Microsoft Teams, and Google Meet calls on Windows and Apple Silicon Macs without adding a standard recording bot tile to the call.

On supported macOS meeting platforms, the SDK can use [Desktop SDK Raw Media](https://docs.recall.ai/docs/desktop-recording-sdk-raw-media) when it has been enabled for your workspace. Otherwise, the SDK records locally.

Curious about our platform support or supported languages? See our [platform support matrices](https://docs.recall.ai/reference/support).

# Desktop Recording SDK Lifecycle

The lifecycle of a Desktop Recording SDK recording is as follows:

1. The Desktop Recording SDK notifies your code that a meeting has started locally.
2. Your code makes a request to your backend for an upload token.
3. Your backend [creates a new Desktop SDK Upload using the Recall.ai API](https://docs.recall.ai/reference/sdk_upload_create), and returns the upload token to your desktop application.
4. Your desktop code calls `startRecording` with the upload token.
5. Wait for the `sdk_upload.complete` webhook
6. Run async transcription (optional)
7. Download the recording video and transcription

That's it! Once the call finishes, a recording will be created on the Recall API and your backend will be notified via webhook.

Now that you understand the DSDK recording lifecycle, you should also familiarize yourself with [when the DSDK will capture video successfully](https://docs.recall.ai/docs/desktop-recording-sdk-faq#when-will-the-dsdk-capture-video-successfully).

# Quickstart

Before integrating the Desktop Recording SDK into your app, we recommend cloning and running our sample application. Without writing any code, you'll see how you can use the SDK to automatically detect, record, and transcribe meetings in real time.

<Callout icon="📘" theme="info">
  ## [Clone the Muesli sample app here](https://github.com/recallai/muesli-public)
</Callout>

# Installation

Once you've explored the sample app and are ready to integrate the Desktop Recording SDK into to your own app, install the SDK:

```shell
# Stable channel
npm install @recallai/desktop-sdk

# Nightly channel (bleeding edge, but potentially less stable)
npm install @recallai/desktop-sdk@nightly
```

<Callout icon="📘" theme="info">
  ### Installing with Bun

  If you're using Bun, you'll need to add the Desktop Recording SDK to Bun's trustedDependencies list for it to install properly. Add this to your package.json:

  ```
  {
    ...,
    "trustedDependencies": ["@recallai/desktop-sdk"]
  }
  ```
</Callout>

<br />

# Usage

## Starting the SDK

To get started, you'll need to initialize the Desktop Recording SDK. This should be called once at startup.

```javascript
const RecallAiSdk = require('@recallai/desktop-sdk');

RecallAiSdk.init({
  apiUrl: "https://us-west-2.recall.ai"
});
```

You must set the following parameter when initializing the SDK:

`apiUrl`: The URL corresponding to the region your Recall.ai workspace belongs to. See the table below for the correct mapping of region to base URL:

| Region             | Base URL                           |
| :----------------- | :--------------------------------- |
| US (Pay-as-you-go) | <https://us-west-2.recall.ai>      |
| US (Monthly plan)  | <https://us-east-1.recall.ai>      |
| EU                 | <https://eu-central-1.recall.ai>   |
| Japan              | <https://ap-northeast-1.recall.ai> |

## Requesting system permissions (MacOS)

The Desktop Recording SDK does not require any additional permissions to work on windows machines. On MacOS, you will need to request specific system permissions from the user before you're able to detect and record meetings.  At minimum, you should request the `microphone`, `accessibility`, and `screen-capture` permissions. You can find a full list of supported permissions [here](https://docs.recall.ai/docs/macos-permissions#/).

```javascript
const RecallAiSdk = require('@recallai/desktop-sdk');

RecallAiSdk.init({
  apiUrl: "https://us-west-2.recall.ai"
});

RecallAiSdk.requestPermission("accessibility");
RecallAiSdk.requestPermission("microphone");
RecallAiSdk.requestPermission("screen-capture");
```

## Adding Event Listeners

The SDK monitors for a variety of different events that you'll be able to subscribe to in your application.

At minimum, you'll likely want to listen for `permissions-granted` event (for MacOS) and the `meeting-detected` event so that your application can start recording once a meeting begins. For a more detailed list of the different event types and their definitions, see the [Desktop Recording SDK Event Types](https://docs.recall.ai/docs/desktop-recording-sdk-event-types#/) page.

```javascript
RecallAiSdk.addEventListener("permissions-granted", async (evt) => {
  // The user has granted all the required permsisions to start recording
});

RecallAiSdk.addEventListener("meeting-detected", async (evt) => {
  const { window } = evt;
});
```

<Callout icon="🚧" theme="warn">
  ### Meeting detection will fail for unsupported platforms and languages

  If you notice that the SDK is not detecting meetings, it's possible that you are using a platform or language that we do not yet support. Refer to our [support documentation](https://docs.recall.ai/docs/dsdk-supported-platforms) for an up-to-date list of the platforms and languages we support.
</Callout>

# Recording a Meeting

To actually start recording a meeting, you'll need to call the [Create Desktop SDK Upload](https://docs.recall.ai/reference/sdk_upload_create) endpoint. The Desktop Recording SDK can capture many different kinds of data including video, audio, participant data, and more. When calling the Create Desktop SDK Upload endpoint, you'll be able to configure which data to capture and specify what data to receive in real time.

## Custom Recording Configurations

### Minimal Request (Defaults)

By default, the SDK will record video of the meeting and capture participant events (e.g., when a participant joins or leaves the call) without any additional configuration required.

```javascript
const url = 'https://us-west-2.recall.ai/api/v1/sdk_upload/';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: 'YOUR_API_KEY'
  }
};

fetch(url, options)
```

#### Response

```json json
{
   "id": "4abf29fc-36b5-4853-9f84-a9990b9e354b",
   "upload_token": "FEv5Ri9MdKmFwbEMSiHbobHcHBotEFBE"
}
```

You'll receive an `upload_token` in the response from this endpoint. You will pass this token to the `RecallAiSdk.startRecording()` function in your desktop application to initiate a recording. You can read more about the available SDK methods [here](doc:desktop-recording-sdk-methods#/).

Here's a code sample demonstrating how you would implement the "meeting detected" to "recording started" flow in practice:

```javascript
import RecallAiSdk from '@recallai/desktop-sdk';

RecallAiSdk.init({
  api_url: "https://us-west-2.recall.ai"
});

RecallAiSdk.addEventListener('meeting-detected', async (evt) => {
  // make a request to your application's backend to hit the Create Desktop SDK Upload endpoint
  const res = await Backend.fetch(`/api/create_sdk_recording`, AppState.client_token);
  const payload = await res.json();
	
  await RecallAiSdk.startRecording({
    windowId: evt.window.id,
    uploadToken: res.upload_token
  });
});

```

<Callout icon="📘" theme="info">
  #### What is a window id?

  The `windowId` tells the SDK which window or audio source to record when you call `startRecording()`:

  - For meeting platforms (Zoom, Teams, Google Meet, etc.), a `windowId` identifies a specific meeting window (e.g. Zoom app meeting window, Google Meets tab in chrome, etc.) on your desktop, provided by the SDK via the `meeting-detected` event
  - For adhoc/in-person meetings, a `windowId` is generated by calling `prepareDesktopAudioRecording()` and represents the system's audio streams rather than a visual window
</Callout>

## Receiving Real-Time Events

The Desktop Recording SDK allows you to access meeting data as the meeting happens: transcripts, participant activities, raw audio, and video frames can all be delivered live through the SDK's event listener.

To receive real-time events, you need to:

1. Configure which events you want to receive when creating the SDK upload by configuring `recording_config.realtime_endpoints` in your [Create Desktop SDK Upload](https://docs.recall.ai/reference/sdk_upload_create) request
2. Listen for events in your desktop app using the `realtime-event` listener (see [this section](https://docs.recall.ai/docs/desktop-sdk#addeventlistenereventtype-listener) for more info)

The events you specify in step 1 will determine what data flows to your application during the recording. Below are the events that you can listen for:

| Event                                | Description                                                                                                                                                            | Payload                                                       |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `participant_events.join`            | A participant joined.                                                                                                                                                  | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `participant_events.update`          | A participant updated their details.                                                                                                                                   | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `participant_events.speech_on`       | A participant started speaking.                                                                                                                                        | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `participant_events.speech_off`      | A participant stopped speaking.                                                                                                                                        | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `participant_events.screenshare_on`  | A participant started screen sharing.                                                                                                                                  | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `participant_events.screenshare_off` | A participant stopped screen sharing.                                                                                                                                  | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#participant_events)     |
| `transcript.data`                    | A transcript utterance was generated (see [Real-time Transcription](https://docs.recall.ai/docs/real-time-transcription).                                              | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#transcriptdata)         |
| `transcript.partial_data`            | A partial transcript utterance was generated (see [Real-time Transcription](https://docs.recall.ai/docs/real-time-transcription).                                      | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#transcriptdata)         |
| `transcript.provider_data`           | Transcript data was generated in the raw format from the transcription provider. (see [Real-time Transcription](https://docs.recall.ai/docs/real-time-transcription) . |                                                               |
| `video_separate_png.data`            | A separate video buffer was generated from the call.                                                                                                                   | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#video_separate_pngdata) |
| `audio_mixed_raw.data`               | A mixed audio buffer was generated from the call.                                                                                                                      | [Schema](https://docs.recall.ai/docs/real-time-event-payloads#audio_mixed_rawdata)    |

<br />

### Example: Real-Time Transcription

One of the most common uses for real-time events is receiving live transcripts during the meeting. To enable this, you need to configure both a transcript provider and the transcript events you want to receive.
Below is an example of how to set up real-time transcription with AssemblyAI. Check out this guide on [real-time transcription with the Desktop Recording SDK](doc:dsdk-realtime-transcription#/) for a full walkthrough.

```javascript
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    recording_config: {
      transcript: {
        provider: {
          assembly_ai_v3_streaming: {
             // include any supported parameters for Assembly's real-time models
             // https://www.assemblyai.com/docs/api-reference/streaming-api/streaming-api
          }
        }
      },
      realtime_endpoints: [
        {
          type: 'desktop_sdk_callback',
          events: ['participant_events.join',       // know who's in the meeting
                   'transcript.data'                // receive transcript in real time
                  ]
        }
      ]
    }
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

<br />

### Example: Real-Time Audio

If you're interested in using your own model to transcribe the conversation, you'll want to subscribe to the raw audio stream of the meeting.
Below is an example request demonstrating how to subscribe to stream raw audio from the meeting in real time:

```javascript
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    recording_config: {
      realtime_endpoints: [
        {
          type:   'desktop_sdk_callback',
          events: ['audio_mixed_raw.data',          // receive raw audio data
                   'participant_events.speech_on',  // track who's speaking
                   'participant_events.speech_off',
                   'participant_events.update'
                  ]
        }
      ]
    }
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

The audio will be returned as a base64 encoded, mono channel of 16K samples of S16LE.

# Putting it all together

This is a minimal example demonstrating how to use all the functionality described above together:

```javascript
import RecallAiSdk from '@recallai/desktop-sdk';

RecallAiSdk.init({
  api_url: "https://us-west-2.recall.ai"
});

RecallAiSdk.requestPermission("accessibility");
RecallAiSdk.requestPermission("microphone");
RecallAiSdk.requestPermission("screen-capture");

RecallAiSdk.addEventListener('meeting-detected', async (evt) => {
  const res = await Backend.fetch(`/api/create_sdk_recording`, AppState.client_token);
  const payload = await res.json();
	
  await RecallAiSdk.startRecording({
    windowId: evt.window.id,
    uploadToken: res.upload_token
  });
});

RecallAiSdk.addEventListener('recording-ended', async (evt) => {
  console.log(`Uploaded evt.window.id `);
});

```

<Callout icon="🚧" theme="warn">
  Before shipping, read [SDK Safe Shutdown and Recovery](https://docs.recall.ai/docs/dsdk-safe-shutdown) to avoid losing media when your app quits or the network drops.
</Callout>

# SDK Upload Webhooks

You can choose to receive webhooks notifying you about the status of recordings produced with the Desktop Recording SDK. You can listen to these to decide when to download the video recording from Recall or [kick off an async transcription job](doc:async-transcription#/). You can subscribe to these webhooks from the Recall transcription dashboard.

> 📘 View the webhooks dashboard
>
> * <Anchor label="(US) us-east-1" target="_blank" href="https://us-east-1.recall.ai/dashboard/webhooks/">(US) us-east-1</Anchor>
> * <Anchor label="(Pay-as-you-go) us-west-2" target="_blank" href="https://us-west-2.recall.ai/dashboard/webhooks/">(Pay-as-you-go) us-west-2</Anchor>
> * <Anchor label="(EU) eu-central-1" target="_blank" href="https://eu-central-1.recall.ai/dashboard/webhooks/">(EU) eu-central-1</Anchor>
> * <Anchor label="(JP) ap-northeast-1" target="_blank" href="https://ap-northeast-1.recall.ai/dashboard/webhooks/">(JP) ap-northeast-1</Anchor>

Below are the webhooks that you're currently able to subscribe to:

| Event                  | Description                                                |
| :--------------------- | :--------------------------------------------------------- |
| `sdk_upload.complete`  | SDK Upload has finished successfully                       |
| `sdk_upload.failed`    | SDK Upload has finished unsuccessfully                     |
| `sdk_upload.uploading` | SDK upload has started uploading to the Recall.ai platform |

You can read more about these webhooks in [this section of the docs](doc:desktop-recording-sdk-webhooks#/).

# Retrieving the recording & transcript after the upload completes

After receiving the `sdk_upload.complete` webhook you can retrieve the recorded video (and transcript, if real time transcription was configured) file using the [Retrieve Recording](ref:recording_retrieve#/) endpoint with the `recording_id` field from the webhook:

#### Endpoint

```shell
curl --request GET \
     --url https://us-east-1.recall.ai/api/v1/recording/71f4d556-4c8c-4627-a253-61344e8f22f7 \
     --header 'Authorization: Token your-recall-api-token' \
     --header 'content-type: application/json' 
```

#### Response

```json
{
  "id": "71f4d556-4c8c-4627-a253-61344e8f22f7",
  "media_shortcuts": {
    "video_mixed": {
      "status": {
        "code": "done"
      },
      "data": {
        "download_url": "https://some-download-endpoint",
      }
    },
    "transcript": {
      "status": {
        "code": "done"
      },
      "data": {
        "download_url": "https://some-download-endpoint",
      }
    }
  }
}
```

<br />

### Note when building for production

<Callout icon="🚧" theme="warn">
  By default, Electron Forge's code signing tool, `osx-sign`, has issues signing the Desktop SDK. Recall.ai [provides a fork of `osx-sign`](https://github.com/recallai/osx-sign) you can use to correctly sign the package when you're building your application for release. If you don't want to worry about configuring this, try [our sample project](https://github.com/recallai/muesli-public) with this already configured!
</Callout>

# Next steps

Now that you have a sense of how to work with the Desktop Recording SDK, here are a few things to try next:

### [Real-time transcription](https://docs.recall.ai/docs/dsdk-realtime-transcription)

This will allow your app to transcribe conversations in real-time, allowing you to react to conversation data as soon as it's spoken.

### [Asynchronous transcription](https://docs.recall.ai/docs/async-transcription)

This will allow you to transcribe conversations after they've ended. Async transcription tends to be more accurate than real-time transcription, so choose this option if you don't need the data in real time.

### [Recording In-Person Meetings](https://docs.recall.ai/docs/adhoc-meetings-in-person-meetings)

You can also record meetings that take place outside of meeting platforms using the Desktop Recording SDK! Learn how to add this functionality to your app.

<br />