VideoDB Desktop SDK

A Node.js SDK for local recording and live transcription in Electron applications. Capture meetings, screens, and audio with real-time transcription powered by VideoDB.

Installation

npm install @videodb/relay-node

Quick Start

const VideoDBDesktopSDK = require('@videodb/relay-node');

// 1. Initialize the SDK
await VideoDBDesktopSDK.init({ 
  apiUrl: 'https://api.videodb.io'
});

// 2. Request Permissions (macOS only)
await VideoDBDesktopSDK.requestPermission('microphone');
await VideoDBDesktopSDK.requestPermission('screen-capture');

// 3. Listen for Events
VideoDBDesktopSDK.addEventListener('meeting-detected', async (evt) => {
  console.log('Meeting detected:', evt.window.title);
  
  // Start recording with session token from your backend
  await VideoDBDesktopSDK.startRecording({
    sessionId: 'unique-session-id',
    sessionToken: 'session-token-from-backend',
    config: { transcription: { enabled: true } }
  });
});

// 4. Handle Real-time Transcripts
VideoDBDesktopSDK.addEventListener('transcript-segment', (data) => {
  console.log(`[${data.speaker}]: ${data.text}`);
});

Usage

Initialization

Initialize the SDK at application startup:

await VideoDBDesktopSDK.init({
  apiUrl: 'https://api.videodb.io',  // Your VideoDB API endpoint
  dev: false                          // Set true to use mock binary for testing
});

Permissions (macOS)

On macOS, request system permissions before recording:

await VideoDBDesktopSDK.requestPermission('microphone');
await VideoDBDesktopSDK.requestPermission('screen-capture');
await VideoDBDesktopSDK.requestPermission('accessibility');

Listen for permission status:

VideoDBDesktopSDK.addEventListener('permission-status', (evt) => {
  console.log(`${evt.permission}: ${evt.status}`);
});

Starting a Recording

Obtain a session token from your backend, then start recording:

await VideoDBDesktopSDK.startRecording({
  sessionId: 'session-123',           // Required: Unique session identifier
  sessionToken: 'session-token',          // Required: Auth token from backend
  callbackUrl: 'https://...',         // Optional: Webhook URL for upload events
  config: {                           // Optional: Recording configuration
    transcription: { enabled: true }
  }
});

Stopping a Recording

await VideoDBDesktopSDK.stopRecording('session-123');

Pausing and Resuming Tracks

Temporarily mute audio or video streams during a recording without stopping the session:

// Pause the microphone
await VideoDBDesktopSDK.pauseTracks({ tracks: ['mic'] });

// Pause system audio and screen
await VideoDBDesktopSDK.pauseTracks({ tracks: ['system_audio', 'screen'] });

// Resume tracks
await VideoDBDesktopSDK.resumeTracks({ tracks: ['mic', 'system_audio', 'screen'] });

Valid track types: mic, system_audio, screen

Note: These commands only affect the active recording. Use them when you need to temporarily mute specific inputs (e.g., during a private conversation) without stopping the entire recording session.

Cleanup

Gracefully shutdown the SDK when your app closes:

await VideoDBDesktopSDK.shutdown();

API Reference

Methods

| Method | Parameters | Description | |--------|------------|-------------| | init(options) | { apiUrl, dev? } | Initialize the SDK and spawn the native binary | | requestPermission(type) | 'microphone' \| 'screen-capture' \| 'accessibility' | Request system permissions (macOS) | | startRecording(options) | { sessionId, sessionToken, callbackUrl?, config? } | Start a recording session | | stopRecording(sessionId) | string | Stop the recording and trigger upload | | pauseTracks(options) | { tracks: string[] } | Pause specific tracks (mic, system_audio, screen) | | resumeTracks(options) | { tracks: string[] } | Resume specific tracks (mic, system_audio, screen) | | shutdown() | - | Gracefully terminate the SDK | | addEventListener(event, callback) | string, Function | Subscribe to SDK events | | removeEventListener(event, callback) | string, Function | Unsubscribe from SDK events |

Events

| Event | Payload | Description | |-------|---------|-------------| | meeting-detected | MeetingDetectedEvent | Meeting window detected | | permissions-granted | {} | All required permissions granted | | permission-status | { permission, status } | Permission status update | | recording-started | { sessionId } | Recording started successfully | | transcript-segment | { sessionId, text, speaker } | Real-time transcription segment | | recording-stopped | { sessionId } | Recording stopped | | recording-complete | { sessionId, uploadId } | Upload completed | | error | { type, message } | Error occurred |

meeting-detected Reference Payload

The meeting-detected event contains detailed information about the active meeting window. Here is the standardized schema:

{
  "platform": "google_meet",
  "meetingID": "eve-fnjm-wkv",
  "meetingURL": "https://meet.google.com/eve-fnjm-wkv",
  "timestamp": "2025-12-19T10:33:06.744Z",
  "started_at": "2025-12-19T10:33:06.744Z",
  "uiState": {
    "participantCount": 1,
    "micMuted": true
  },
  "window": {
    "title": "Meet – eve-fnjm-wkv",
    "ownerBundleID": "com.google.Chrome",
    "bounds": { "x": 1795, "y": 25, "width": 1728, "height": 995 }
  }
}

Backend Integration

Session Tokens

Your backend must generate session tokens by calling the VideoDB API. Never hardcode API keys in your Electron app.

Webhooks (Optional)

Provide a callbackUrl in startRecording() to receive server-side notifications:

• sdk_upload.uploading - Upload started
• sdk_upload.complete - Upload finished successfully
• sdk_upload.failed - Upload failed

Note: Real-time events (like transcription) are delivered directly to the SDK via addEventListener, not to the webhook.

Development

For contributors and binary implementers, see CONTRIBUTING.md for:

• Project architecture
• Binary protocol specification
• Testing with mock binary
• Release process