The official Neuphonic Typescript (Javascript) library providing simple, convenient access to the Neuphonic text-to-speech websocket API from any Node.js or browser application.
For comprehensive guides and official documentation, check out https://docs.neuphonic.com. For the Python SDK visit PyNeuphonic. If you need support or want to join the community, visit our Discord!
Example applications can be found in a separate repository: https://github.com/neuphonic/neuphonic-js-examples.
Install this package into your environment using your chosen package manager:
npm install @neuphonic/neuphonic-jsGet your API key from the Neuphonic website.
The following API requires an API key and is primarily intended for server-side use.
The following parameters are examples of parameters which can be adjusted. Ensure that the selected combination of model, language, and voice is valid. For details on supported combinations, refer to the Models and Voices pages.
-
lang_codeLanguage code for the desired language.Default:
'en'Examples:'en','es','de','nl' -
voice_idThe voice ID for the desired voice. Ensure this voice ID is available for the selected model and language.Default:
NoneExamples:'8e9c4bc8-3979-48ab-8626-df53befc2090' -
speedPlayback speed of the audio.Default:
1.0Examples:0.7,1.0,1.5
import fs from 'fs';
import { createClient, toWav } from '@neuphonic/neuphonic-js';
const client = createClient();
const msg = `Hello how are you?<STOP>`;
const sse = await client.tts.sse({
speed: 1.15,
lang_code: 'en'
});
const res = await sse.send(msg);
// Saving data to file
const wav = toWav(res.audio);
fs.writeFileSync(__dirname + 'sse.wav', wav);import fs from 'fs';
import { createClient, toWav } from '@neuphonic/neuphonic-js';
const client = createClient();
const msg = `Hello how are you?<STOP>`;
const ws = await client.tts.websocket({
speed: 1.15,
lang_code: 'en'
});
let byteLen = 0;
const chunks = [];
// Websocket allow us to get chunk of the data as soon as they ready
// which can make API more responsve
for await (const chunk of ws.send(msg)) {
// here you can send the data to the client
// or collect it in array and save as a file
chunks.push(chunk.audio);
byteLen += chunk.audio.byteLength;
}
// Merging all chunks into single Uint8Array array
let offset = 0;
const allAudio = new Uint8Array(byteLen);
chunks.forEach(chunk => {
allAudio.set(chunk, offset);
offset += chunk.byteLength;
})
// Saving data to file
const wav = toWav(allAudio);
fs.writeFileSync(__dirname + '/data/ws.wav', wav);
await ws.close(); // closing the socket if we don't want to send anythingThe client-side API enables you to build applications with Neuphonic directly in the browser.
Client-side authentication is handled using JWT tokens. To obtain a token, use the server-side client as follows:
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.jwt()
);To get all available voices you can run the following snippet.
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(await client.voices.list());To get information about an existing voice please call.
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.voices.get({ id: '<VOICE_ID>' })
);To clone a voice based on a audio file, you can run the following snippet.
import fs from 'fs';
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
// Providing the file name
console.log(
await client.voices.clone({
voiceName: 'Voice name',
voiceFilePath: __dirname + '/data.wav',
voiceTags: ['Tag 1']
})
);
// Providing the readable stream
const voiceStream = fs.createReadStream(__dirname + '/data.wav');
console.log(
await client.voices.clone({
voiceName: 'Voice name',
voiceFilePath: voiceStream,
voiceFileName: 'data.wav',
voiceTags: ['Tag 1']
})
);If you have successfully cloned a voice, the voice id will be returned. Once cloned, you can use this voice just like any of the standard voices when calling the TTS (Text-to-Speech) service.
To see a list of all available voices, including cloned ones, use client.voices.list().
Note: Your voice reference clip must meet the following criteria: it should be at least 6 seconds long, in .mp3 or .wav format, and no larger than 10 MB in size.
You can update any of the attributes of a voice: name, tags and the reference audio file the voice
was cloned on.
You can select which voice to update using either it's voice_id or it's name.
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
// Providing the file name
console.log(
await client.voices.update({
id: '<VOICE_ID>', // you can also use voice 'name' here instead of id
newVoiceName: 'New name',
newVoiceFilePath: __dirname + '/data.wav',
newVoiceTags: ['Tag 2']
})
);
// Providing the readable stream
const voiceStream = fs.createReadStream(__dirname + '/data.wav');
console.log(
await client.voices.update({
id: '<VOICE_ID>', // you can also use voice 'name' here instead of id
newVoiceName: 'New name',
newVoiceFilePath: voiceStream,
newVoiceFileName: 'data.wav'
newVoiceTags: ['Tag 2']
})
);Note: Your voice reference clip must meet the following criteria: it should be at least 6 seconds long, in .mp3 or .wav format, and no larger than 10 MB in size.
To delete a cloned voice:
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.voices.delete({
id: '<VOICE_ID>'
})
);With Agents, you can create, manage, and interact with intelligent AI assistants.
import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.agents.create({
name: 'My Agent',
prompt: 'Hey',
greeting: 'Greet',
})
);import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.agents.list()
);import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.agents.get({ id: '<AGENT ID>' })
);import { createClient } from '@neuphonic/neuphonic-js';
const client = createClient();
console.log(
await client.agents.delete({
id: '<AGENT ID>'
})
);The Agent API allows you to build real-time voice communication applications directly in the browser.
import { createBrowserClient } from '@neuphonic/neuphonic-js/browser';
const client = createBrowserClient();
// Pass the token from the server
client.jwt('<JWT TOKEN>');
const agent = client.createAgent({ agent_id: '<AGENT ID>' });
// The Agent will try to access the mic and listen
const chat = await agent.current.start();
// Transcribed messages and agent replies are available through the onText callback.
chat.onText((role, text) => {
addMessage(text, role);
});
// Event triggered upon audio playback start or stop
chat.onAudio(async (audio) => {
// Indicates whether audio is currently playing (true) or not (false)
console.log(audio);
});You can connect MCP servers to your Agent to provide it with any functionality you need.
client.createAgent({ agent_id: '<AGENT ID>', mcp_servers: ['https://f745add9e6f1.ngrok-free.app/sse'] });