Node.js Setup - Lokutor

Requirements

Requirement	Why
Node.js 22 or later	The SDK uses the global `WebSocket`, which Node has without a flag from version 22
`speaker` and `node-record-lpcm16` (optional)	Microphone and speaker for a voice agent in a terminal. Not needed for TTS or transcription of files.
No user gesture	You can call `connect()` immediately

On a server, the API key can be used directly (apiKey: process.env.LOKUTOR_API_KEY). Never send it to a browser: give browsers tickets (Secure browser setup).

Setup

npm install @lokutor/sdk
# only for microphone and speaker:
npm install speaker node-record-lpcm16

node-record-lpcm16 needs SoX (brew install sox, sudo apt install sox); speaker may need ALSA headers on Linux (sudo apt install libasound2-dev).

Voice agent in a terminal

NodeAudioManager connects the microphone and the speaker for you:

// agent.mjs — node agent.mjs
import { VoiceAgentClient, NodeAudioManager } from '@lokutor/sdk';

const client = new VoiceAgentClient({
  apiKey: process.env.LOKUTOR_API_KEY,
  prompt: 'You are a terminal assistant. Keep answers short.',
});

client.on('transcription', (text) => console.log('You:', text));
client.on('response', (text) => console.log('Agent:', text));
client.on('error', (err) => console.error(err.code, err.message));

await client.connect(new NodeAudioManager());

process.on('SIGINT', () => {
  client.disconnect();
  process.exit(0);
});

There is no echo cancellation in this path: use headphones, or the agent hears itself through the speakers. To route audio yourself (for example from a telephony bridge), connect without an audio manager, send 16 kHz Int16 mono PCM with client.sendAudio(chunk), and play the 44.1 kHz Int16 mono PCM that arrives on client.on('audio', …).

Save TTS to a file

// tts.mjs — node tts.mjs
import { TTSClient, VoiceStyle, Language } from '@lokutor/sdk';
import fs from 'node:fs';

const client = new TTSClient({ apiKey: process.env.LOKUTOR_API_KEY });
const chunks = [];

await client.synthesize({
  text: 'Hello from Node.js',
  voice: VoiceStyle.F1,
  language: Language.ENGLISH,
  onAudio: (data) => chunks.push(Buffer.from(data)),
});

fs.writeFileSync('output.raw', Buffer.concat(chunks));
// Convert: ffmpeg -f s16le -ar 44100 -ac 1 -i output.raw output.wav

For a WAV file in one request with no SDK, use POST /tts/synthesize.