Interpreter SDK

npm install @vitalvoice/interpreter

curl -X POST https://api.vitalvoice.ai/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetLanguages": ["es", "fr", "de"],
    "maxDurationSeconds": 300
  }'

{
  "sessionToken": "sess_ephemeral_abc123...",
  "expiresAt": "2025-01-15T12:05:00Z",
  "sessionId": "sess_def456"
}

import { Interpreter } from '@vitalvoice/interpreter';
 
// Fetch token from your backend
const { sessionToken } = await fetch('/api/interpret-session', {
  method: 'POST',
  credentials: 'include'
}).then(r => r.json());
 
// Initialize interpreter
const interpreter = Interpreter.create({
  sessionToken,
  container: document.querySelector('.interpreter-container'),
  mode: 'standard'
});
 
await interpreter.connect();

const interpreter = Interpreter.create({
  sessionToken,
  container: document.querySelector('.interpreter-container'),
  mode: 'standard',
  targetLanguages: ['es', 'fr', 'de']
});
 
await interpreter.connect();

Interpreter.create({
  // Required
  sessionToken: string,
  container: HTMLElement,
  mode: 'standard',
 
  // Language settings
  sourceLanguage: string,        // Auto-detect if omitted
  targetLanguages: string[],     // Required
 
  // Appearance
  theme: 'light' | 'dark' | ThemeConfig,
 
  // Transcript popover
  transcript: {
    position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left',
    defaultExpanded: boolean,    // Default: true
  }
});

Interpreter.create({
  // ...
  theme: {
    primaryColor: '#6366f1',
    backgroundColor: '#ffffff',
    textColor: '#1f2937',
    borderRadius: '8px',
    fontFamily: 'Inter, system-ui, sans-serif'
  }
});

const interpreter = Interpreter.create({
  sessionToken,
  container: document.querySelector('.hidden-container'),
  mode: 'headless',
  targetLanguages: ['es', 'fr']
});
 
// Listen for events
interpreter.on('interpretation', ({ original, interpreted, targetLanguage, isFinal }) => {
  // Render in your UI
  updateTranscript(original, interpreted);
});
 
interpreter.on('stateChange', (state) => {
  updateConnectionStatus(state);
});
 
interpreter.on('error', (error) => {
  showErrorMessage(error.message);
});
 
await interpreter.connect();
 
// Wire up your UI controls
document.querySelector('.mic-button').addEventListener('click', () => {
  if (interpreter.isListening) {
    interpreter.stopListening();
  } else {
    interpreter.startListening();
  }
});

const interpreter = Interpreter.create(options);

await interpreter.connect();    // Establish connection
interpreter.disconnect();       // End session gracefully
interpreter.destroy();          // Clean up all resources

interpreter.startListening();   // Begin capturing audio
interpreter.stopListening();    // Stop capturing audio
interpreter.mute();             // Mute microphone (stay connected)
interpreter.unmute();           // Unmute microphone
 
// Input device selection
const devices = await interpreter.getInputDevices();
await interpreter.setInputDevice(deviceId);

interpreter.state        // 'disconnected' | 'connecting' | 'connected' | 'error'
interpreter.isListening  // boolean
interpreter.isMuted      // boolean

// Connection state changes
interpreter.on('stateChange', (state: State) => {});
 
// Interpretation results
interpreter.on('interpretation', (event: InterpretationEvent) => {});
 
// Audio input level (for visualizers)
interpreter.on('audioLevel', (level: number) => {});
 
// Errors
interpreter.on('error', (error: InterpreterError) => {});

interface InterpretationEvent {
  original: string;           // Original speech text
  interpreted: string;        // Interpreted text
  sourceLanguage: string;     // Detected or configured source
  targetLanguage: string;     // Interpretation target
  isFinal: boolean;           // false = partial, true = final
  confidence?: number;        // 0-1 confidence score
}

interpreter.expandTranscript();
interpreter.collapseTranscript();
interpreter.isTranscriptExpanded;  // boolean

npm install @vitalvoice/interpreter-react

import { useInterpreter } from '@vitalvoice/interpreter-react';
 
function InterpretationUI() {
  const {
    interpreter,
    state,
    isListening,
    isMuted,
    interpretations,
    error
  } = useInterpreter({
    sessionToken,
    targetLanguages: ['es', 'fr'],
    mode: 'headless'
  });
 
  return (
    <div>
      <button onClick={() => isListening ? interpreter.stopListening() : interpreter.startListening()}>
        {isListening ? 'Stop' : 'Start'}
      </button>
 
      <div className="transcript">
        {interpretations.map((t, i) => (
          <p key={i}>{t.interpreted}</p>
        ))}
      </div>
    </div>
  );
}

npm install @vitalvoice/interpreter-angular

import { InterpreterService } from '@vitalvoice/interpreter-angular';
 
@Component({
  selector: 'app-interpretation',
  template: `
    <button (click)="toggle()">
      {{ (isListening$ | async) ? 'Stop' : 'Start' }}
    </button>
 
    <div class="transcript">
      <p *ngFor="let t of interpretations$ | async">{{ t.interpreted }}</p>
    </div>
  `
})
export class InterpretationComponent implements OnInit, OnDestroy {
  constructor(private interpreterService: InterpreterService) {}
 
  state$ = this.interpreterService.state$;
  isListening$ = this.interpreterService.isListening$;
  interpretations$ = this.interpreterService.interpretations$;
 
  async ngOnInit() {
    await this.interpreterService.initialize({
      sessionToken: this.sessionToken,
      targetLanguages: ['es', 'fr'],
      mode: 'headless'
    });
  }
 
  toggle() {
    this.interpreterService.toggleListening();
  }
 
  ngOnDestroy() {
    this.interpreterService.destroy();
  }
}

npm install @vitalvoice/interpreter-svelte

<script>
  import { createInterpreter } from '@vitalvoice/interpreter-svelte';
  import { onMount, onDestroy } from 'svelte';
 
  export let sessionToken;
 
  const interpreter = createInterpreter({
    sessionToken,
    targetLanguages: ['es', 'fr'],
    mode: 'headless'
  });
 
  const { state, isListening, interpretations } = interpreter.stores;
 
  onMount(() => interpreter.connect());
  onDestroy(() => interpreter.destroy());
</script>
 
<button on:click={() => interpreter.toggleListening()}>
  {$isListening ? 'Stop' : 'Start'}
</button>
 
<div class="transcript">
  {#each $interpretations as t}
    <p>{t.interpreted}</p>
  {/each}
</div>

{
  "event": "session.ended",
  "sessionId": "sess_def456",
  "durationSeconds": 142,
  "languagePair": {
    "source": "es",
    "target": "en"
  },
  "metadata": {
    "userId": "user_123",
    "facility": "memorial_hospital"
  },
  "timestamp": "2025-01-15T12:07:22Z"
}

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface InterpreterError {
  code: string;
  message: string;
  recoverable: boolean;
}

interpreter.on('error', (error) => {
  if (error.recoverable) {
    showRetryPrompt(error.message);
  } else if (error.code === 'AUTH_INVALID') {
    // Token expired, get a new one
    refreshSessionToken().then(token => {
      interpreter.destroy();
      initializeNewInterpreter(token);
    });
  } else {
    showErrorMessage(error.message);
  }
});

curl https://api.vitalvoice.ai/v1/usage \
  -H "Authorization: Bearer sk_live_..."

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "usage": {
    "minutes": 1423,
    "sessions": 847
  },
  "quota": {
    "minutes": 5000,
    "remaining": 3577
  }
}

{
  "targetLanguages": ["es"],
  "metadata": {
    "department": "emergency",
    "facility_id": "hospital_123",
    "encounter_type": "intake"
  }
}

const interpreter = Interpreter.create({
  sessionToken,
  container,
  mode: 'headless',
  debug: true  // Logs connection events, audio levels, and timing
});