Web SDK Overview

Overview

The @cephable/cephable-web npm package lets you embed Cephable's private, on-device personal assistant into any web application. Voice recognition, camera-based face and gesture detection, and all AI inference run entirely on the user's device — no audio, video, or biometric data is sent to external servers. Your app receives only the resulting command strings. Access requires a valid Cephable license.

Installation

npm install @cephable/cephable-web

Services

CephableService

The central integration point. Manages authentication, device profiles, voice, and camera with automatic profile switching.

import { CephableService } from '@cephable/cephable-web';

const cephableService = new CephableService({
    authenticationConfiguration: {
        clientId: 'your-client-id',
        clientSecret: 'your-client-secret',
        redirectUri: location.href,
        autoRefresh: true,
    },
    deviceName: 'your-device-name',
    deviceTypeId: 'your-device-type-id',
    locale: 'en-US',
    includeDefaultControls: true,
    customControls: [],
    enableRemoteControls: false,
});

AuthenticationService

Manages OAuth flows, guest authentication, and automatic token refreshing.

import { AuthenticationService } from '@cephable/cephable-web';

const authService = new AuthenticationService({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: location.href,
    autoRefresh: true,
});

authService.startUserAuth(false); // false = existing user, true = new user

VoiceService

Real-time, on-device speech recognition. Audio is processed entirely in the browser — nothing is sent to a cloud speech API.

import { VoiceService } from '@cephable/cephable-web';

const voiceService = new VoiceService({
    locale: 'en-US',
    modelPath: 'path-to-hosted-model',
    audioWorkletPath: './RecognizerAudioProcessor.js',
    onPartialResult: (result) => console.log('Partial:', result),
    onFinalResult: (result) => console.log('Final:', result),
});

voiceService.startVoiceControls([]);

CameraService

On-device webcam capture and real-time face/gesture detection using BlazeFace. All inference runs in the browser — no video frames leave the user's device.

import { CameraService } from '@cephable/cephable-web';

const cameraService = new CameraService({
    modelDirectoryPath: 'path-to-remote-models',
    isDrawingEnabled: true,
    videoElementId: 'video',
    canvasElementId: 'canvas',
    faceLinesColor: 'red',
    baselineFaceLinesColor: 'blue',
    onGesturesRecognized: (gestures) => { /* handle gestures */ },
    onFaceProcessed: (face) => { /* handle face data */ },
});

cameraService.startCameraControls();

Required HTML elements:

<video id="video" style="display: none"></video>
<canvas id="canvas"></canvas>

DOMInteractiveService

DOM interaction utilities — scrolling, typing, navigation, and fuzzy element search.

import { DomInteractionService } from '@cephable/cephable-web';

const domService = new DomInteractionService({
    excludedSelectors: ['a', '.navigation'],
    excludeHidden: true,
    stricterAutoThreshold: 0.2,
});

domService.scrollToElementByDisplayValue('Button one');
domService.focusElementByDisplayValue('Button two');
domService.clickElementByDisplayValue('Button three');

DeviceProfileService

Manages user device profiles, macros, and keybindings.

import { DeviceProfileService } from '@cephable/cephable-web';

const profileService = new DeviceProfileService(authService);
await profileService.loadProfiles();

profileService.currentProfile = {
    name: 'my-profile',
    configuration: {
        macros: [],
        keybindings: [],
        audioEvents: [],
        dictationCommands: ['type'],
    },
};

Intelligent voice commands

Enable natural language understanding with custom entities:

new CephableService({
    enableIntelligentCommands: true,
    includeBuiltinEntities: true,
    customControls: [
        {
            id: 'navigate',
            defaultCommands: ['navigate to @page', 'go to @page'],
            description: 'Navigate to a specific page',
        },
    ],
    customEntities: {
        page: {
            options: {
                schedule: ['schedule', 'calendar'],
                map: ['map'],
                speakers: ['speakers', 'presenters'],
            },
        },
    },
    onCustomControlAction: (control, command, additionalInput, intent, entities) => {
        // Handle custom control actions
    },
});

Text input data attributes

Use data-* attributes on input elements to customize typing behavior:

Attribute	Effect
data-cephable-no-spell	Disable spelling mode
data-cephable-sentence-case	Auto sentence casing
data-cephable-title-case	Capitalize first letter of each word
data-cephable-optimistic	Enable optimistic mode
data-cephable-alt	Alternative search terms
data-cephable-ignore-auto	Exclude from automatic interactions

Next steps

• Web Quick Start
• API Reference
• Swagger UI