Privacy Controls

Desktop capture handles sensitive data. Nothing records without explicit user consent. This page covers permission patterns, storage controls, and privacy-first design.

Desktop capture currently supports macOS and Windows.

Quick Example

from videodb.capture import CaptureClient

client = CaptureClient(client_token=token)

# Request explicit permissions (OS dialogs appear)
await client.request_permission("microphone")
await client.request_permission("screen_capture")

# User must grant permission before capture can start
channels = await client.list_channels()

import { CaptureClient } from 'videodb/capture';

const client = new CaptureClient({ sessionToken: token });

// Request explicit permissions (OS dialogs appear)
await client.requestPermission('microphone');
await client.requestPermission('screen-capture');

// User must grant permission before capture can start
const channels = await client.listChannels();

Trust Model

Two-Component Architecture

Security is built into the architecture:

Component	Has API Key	Can See Media
Backend	Yes	No (receives events only)
Desktop Client	No (uses token)	Yes (captures locally)

API key never leaves your backend
Desktop client uses short-lived tokens (10-15 min expiry recommended)
Compromised tokens have limited blast radius

Token Pattern

# Backend (holds API key)
conn = videodb.connect()  # Uses VIDEO_DB_API_KEY

# Generate short-lived token for client
token = conn.generate_client_token(expires_in=600)  # 10 minutes

# Send token to desktop app (never send API key)

// Backend (holds API key)
const conn = connect();  // Uses VIDEO_DB_API_KEY

// Generate short-lived token for client
const token = await conn.generateClientToken(600);  // 10 minutes

// Send token to desktop app (never send API key)

Permission Handling

Request Before Capture

# Each permission triggers an OS dialog
await client.request_permission("microphone")
await client.request_permission("screen_capture")

// Each permission triggers an OS dialog
await client.requestPermission('microphone');
await client.requestPermission('screen-capture');

Required UX Elements

Your desktop client must include:

Recording indicator - Visual cue that capture is active
Pause button - Let users temporarily stop
Stop button - Let users end the session

Storage Control

Ephemeral Mode

Process in real-time without persisting media:

channels = await client.list_channels()
selected = [
    channel
    for channel in (
        channels.mics.default,
        channels.displays.default,
        channels.system_audio.default,
    )
    if channel
]
for channel in selected:
    channel.store = False

await client.start_session(
    capture_session_id=cap_id,
    channels=selected,
)

const channels = await client.listChannels();
const selectedChannels = [
    channels.mics.default,
    channels.displays.default,
    channels.systemAudio.default,
]
    .filter(Boolean)
    .map(channel => ({ channelId: channel.id, type: channel.type, store: false }));

await client.startSession({
    sessionId: capId,
    channels: selectedChannels,
});

Use ephemeral mode when:

Processing sensitive content
Storage isn’t needed
Privacy regulations require it
Building real-time assistants only

Selective Storage

Store only what you need:

channels = await client.list_channels()
mic = channels.mics.default
display = channels.displays.default
system_audio = channels.system_audio.default

if mic:
    mic.store = True
if display:
    display.store = False
if system_audio:
    system_audio.store = True

selected = [channel for channel in (mic, display, system_audio) if channel]
await client.start_session(
    capture_session_id=cap_id,
    channels=selected,
)

const channels = await client.listChannels();
const mic = channels.mics.default;
const display = channels.displays.default;
const systemAudio = channels.systemAudio.default;
const selectedChannels = [
    [mic, true],
    [display, false],
    [systemAudio, true],
]
    .filter(([channel]) => Boolean(channel))
    .map(([channel, store]) => ({ channelId: channel.id, type: channel.type, store }));

await client.startSession({
    sessionId: capId,
    channels: selectedChannels,
});

Data Retention

Default Behavior

Tell users which selected channels may be stored and for how long.
Define a retention schedule and access policy in your product before capture starts.
Keep the records needed to honor consent, access, and deletion requests.

Data Subject Requests

Provide authenticated ways for people to request access to or deletion of their data, and document how your application maps those requests to its stored media. Coordinate the provider-side lifecycle with your retention process.

Python supports list_capture_sessions(collection_id="default", status=None). It does not support an end_user_id filter or CaptureSession.delete(), so keep per-user mapping and deletion orchestration in your application until a supported lifecycle API is available.

Compliance Patterns

Document processing purposes and the data captured for each purpose.
Provide a clear process for access and deletion requests.
Minimize collection by selecting only the channels your workflow requires.

HIPAA and Sensitive Data

Apply strict access controls and audit access to sensitive captures.
Minimize captured and stored data, and follow your organization’s applicable compliance program.
Consult your legal, privacy, and security teams for the deployment requirements that apply to your use case.

General Best Practices

Practice	Implementation
Never expose API keys	Use client tokens
Default to ephemeral	Only persist when needed
Short token lifetimes	10-15 minutes
Support data requests	Define an authenticated application workflow
Get consent	Permission dialogs before capture
Show indicators	Recording visible to user

Summary

Key principles:

Nothing records without explicit user permission
Storage is optional per-channel (store: false)
Visible recording indicators are required
API key never leaves backend
Tokens are short-lived and limited scope

Start Here

Core Concepts

Ingest

Understand

Act

Automate

MCP Server

Open Source Frameworks

Quick Example

Trust Model

Two-Component Architecture

Token Pattern

Permission Handling

Request Before Capture

Required UX Elements

Storage Control

Ephemeral Mode

Selective Storage

Data Retention

Default Behavior

Data Subject Requests

Compliance Patterns

HIPAA and Sensitive Data

General Best Practices

Summary

Next Steps

Capture Overview

Real-time Context

​Quick Example

​Trust Model

​Two-Component Architecture

​Token Pattern

​Permission Handling

​Request Before Capture

​Required UX Elements

​Storage Control

​Ephemeral Mode

​Selective Storage

​Data Retention

​Default Behavior

​Data Subject Requests

​Compliance Patterns

​GDPR

​HIPAA and Sensitive Data

​General Best Practices

​Summary

​Next Steps

Capture Overview

Real-time Context

Quick Example

Trust Model

Two-Component Architecture

Token Pattern

Permission Handling

Request Before Capture

Required UX Elements

Storage Control

Ephemeral Mode

Selective Storage

Data Retention

Default Behavior

Data Subject Requests

Compliance Patterns

GDPR

HIPAA and Sensitive Data

General Best Practices

Summary

Next Steps