tivi

tivi is the browser voice layer of SmartChats: the useTivi React hook, a Tivi component, a VoiceSelector and device-local voice settings. It runs Silero VAD v5 with onnxruntime-web in the browser, wraps the Web Speech API for recognition, and plays TTS through an interruptible queue.

Turn-taking (deciding when the user has finished speaking) runs through vie by default. The behaviour is described in Voice engine.

Exports

The package entry (src/index.ts) exports:

CalibrationPanel, useCalibration and the lower-level pieces in src/lib/ (TTS queue, ack cache, Smart Turn predictor) are not exported from the entry. The SmartChats app imports CalibrationPanel by source path.

Quick start

import { useTivi } from 'tivi';
 
function Mic() {
  const tivi = useTivi({
    onTranscription: (text) => console.log('user said:', text),
    onInterrupt: () => console.log('user interrupted TTS'),
  });
 
  return (
    <button onClick={tivi.isListening ? tivi.stopListening : tivi.startListening}>
      {tivi.isListening ? 'Stop' : 'Start'} listening
    </button>
  );
}

To speak:

await tivi.speak('Hello.');          // optional second argument: rate
tivi.cancelSpeech();

With enableInterruption on, speech detected while TTS plays stops playback and calls onInterrupt.

UseTiviOptions

The most used options. Defaults are the hook’s own. The SmartChats app passes values from getTiviSettings().

See types.ts for the full list, including the queue, recognizer and legacy state machine callbacks.

UseTiviReturn includes isListening, isSpeaking, transcription, interimResult, audioLevelRef, speechProbRef, error, mode, startListening, stopListening, speak, cancelSpeech, clearTranscription, pauseVADProcessing, resumeVADProcessing, warmupVAD, ttsQueue, getVie and voiceEngine.

Modes

TiviMode controls how speech recognition starts:

Interruption is a separate switch (enableInterruption).

Settings

Settings are device-local, stored in localStorage under tivi-settings. TIVI_DEFAULTS holds the defaults:

Fields ending in _applied are one-time migration markers.

import { getTiviSettings, updateTiviSettings, resetTiviSettings, useTiviSettings } from 'tivi';
 
const current = getTiviSettings();          // a copy
updateTiviSettings({ playbackRate: 1.2 });  // partial merge, saved and broadcast
resetTiviSettings();
 
// in a component:
const { settings, updateSettings, resetSettings } = useTiviSettings();

Common pitfalls

See also

• Voice engine for turn-taking behaviour
• vie for the turn-taking API
• llm-service for the server verdict
• Source: packages/tivi/src/index.ts