The Desktop Recording SDK allows for recording Zoom, MS Teams, and Google Meet calls locally, within an Electron application on Windows and Apple Silicon Macs.

Curious about our platform support or supported languages? See our platform support matrices.

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, and returns the upload token to your desktop application.
4. Your desktop code calls startRecording with the upload token.
5. Once the meeting is over, call uploadRecording.
6. Wait for the sdk_upload.complete webhook
7. Run async transcription (optional)
8. 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.

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.

Clone the sample app here.

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:

# Stable channel
npm install @recallai/desktop-sdk

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

Usage

Starting the SDK

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

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:

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.

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 page.

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;
});

🚧

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 for an up-to-date list of the platforms and languages we support.

Recording a Meeting

To actually start recording a meeting, you'll need to call the Create Desktop SDK Upload 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.

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

{
   "id": "4abf29fc-36b5-4853-9f84-a9990b9e354b",
   "upload_token": "96472e47-a78c-4774-a9a2-9349327d398d"
}

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.

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

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
  });
});

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 request
2. Listen for events in your desktop app using the realtime-event listener (see this section 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:

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 for a full walkthrough.

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));

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:

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:

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('sdk-state-change', async (evt) => {
  switch (evt.sdk.state.code) {
    case 'recording':
      console.log("SDK is recording");
      break;
    case 'idle':
      console.log("SDK is idle");
      break;
  }
});

RecallAiSdk.addEventListener('recording-ended', async (evt) => {
  RecallAiSdk.uploadRecording({ windowId: evt.window.id });
});

RecallAiSdk.addEventListener('upload-progress', async (evt) => {
  console.log(`Uploaded ${evt.progress}%`);
});

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. You can subscribe to these webhooks from the Recall transcription dashboard.

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

You can read more about these webhooks in this section of the docs.

Retrieving the recording & transcript after the upload completes

After receiving the sdk_upload.complete webhook you can retrieve the recorded video file using the Retrieve Recording endpoint with the recording_id field from the webhook:

Endpoint

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

{
  "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",
      }
    }
  }
}

Note when building for production

🚧

By default, Electron Forge's code signing tool, osx-sign, has issues signing the Desktop SDK. Recall.ai provides a fork of 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 with this already configured!

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

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

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

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.