@soniox/speech-to-text-web
Version:
Javascript client library for Soniox Speech-to-Text websocket API
162 lines (113 loc) • 6.31 kB
Markdown
Soniox Speech-to-Text Web is a Javascript client library for **real-time low-latency** automatic speech-to-text using [Soniox Speech-to-Text Service](https://soniox.com/docs/speech-to-text/get-started).
```bash
npm install @soniox/speech-to-text-web
```
Create new `RecordTranscribe` object:
```ts
const recordTranscribe = new RecordTranscribe({
apiKey: '<SONIOX_API_KEY>',
});
```
And start transcription:
```ts
recordTranscribe.start({
model: 'stt-rt-preview',
onError: (status, message) => {
console.error(status, message);
},
onPartialResult(result) {
console.log('partial result', result.words);
},
});
```
`RecordTranscribe` object will transcribe the audio input from microphone or a custom audio stream and return the transcribed data by calling the `onPartialResult` callback.
Stop or cancel transcription:
```ts
recordTranscribe.stop();
// or
recordTranscribe.cancel();
```
The difference between `stop()` and `cancel()` is that `stop()` will wait for the transcription to finish receiving all final results, while `cancel()` will stop the transcription immediately.
For example, when user clicks the "stop" button, you can call `stop()` to wait for the transcription to finish. When you need to cancel the transcription immediately (for example, on component unmount), you can call `cancel()`.
### Additional parameters
You can pass additional model parameters to the `RecordTranscribe` constructor, such as `context` and `languageHints`. To learn more about those parameters, check the [Soniox Documentation](https://speechdev.soniox.com/docs/speech-to-text/guides).
```ts
recordTranscribe.start({
model: 'stt-rt-preview',
// Additional model parameters
context: 'This is a context',
languageHints: ['en', 'fr'],
...
});
```
If you want to avoid exposing your API key to the client, you can use temporary API keys. To generate a temporary API key, you can use [temporary API key endpoint](https://soniox.com/docs/speech-to-text/api-reference/openapi/auth/create_temporary_api_key) in the Soniox API.
If you want to fetch a temporary API key only when recording starts, you can pass a function to the `apiKey` option. The function will be called when the recording starts and should return the API key.
```ts
const recordTranscribe = new RecordTranscribe({
apiKey: async () => {
// Call your backend to generated a temporary API key there.
const response = await fetch('/api/get-temporary-api-key', {
method: 'POST',
});
const { apiKey } = await response.json();
return apiKey;
},
});
```
Until the request is completed, audio data will be buffered in-memory. When the temporary API key is fetched, the buffered audio data will be sent to the server and the transcription will start.
For a full example with temporary API key generation, check the [NextJS Example](https://github.com/soniox/speech-to-text-web/tree/master/examples/nextjs).
Called when the transcription returns partial results. Result contains `text` string of recognized words and a list of individual `tokens` which form the partial result.
Called when the transcription starts. This happens after the API key is fetched and WebSocket connection is established.
Called when the transcription (successfully) finishes. Wait for this callback after calling `stop()` to be sure that all final results are received.
##### `onStateChange(state: RecorderState)`
Called when the state of the transcription changes. Useful for rerendering the UI based on the state.
##### `onError(status: ErrorStatus, message: string, errorCode?: number)`
Called when the transcription encounters an error. Possible error statuses are:
- `get_user_media_failed`: If either user denied the permission to use the microphone or the browser does not support audio recording.
- `api_key_fetch_failed`: In case you passed a function to `apiKey` option and the function throws an error.
- `queue_limit_exceeded`: While waiting for the temporary API key to be fetched, the local queue is full. You can increase the queue size by setting `bufferQueueSize` option.
- `media_recorder_error`: An error occurred while recording the audio.
- `api_error`: Error returned by the Soniox API. In this case, the `errorCode` property contains the HTTP status code equivalent to the error.
- `websocket_error`: WebSocket error.
### Custom audio streams
To transcribe audio from a custom source, you can pass a custom `MediaStream` to the `stream` option.
If you provide a custom `MediaStream` to the `stream` option, you are responsible for managing its lifecycle, including starting and stopping the stream. For instance, when using an HTML5 `<audio>` element (as shown below), you may want to pause playback when transcription is complete or an error occurs.
```ts
// Create a new audio element
const audioElement = new Audio();
audioElement.volume = 1;
audioElement.crossOrigin = 'anonymous';
audioElement.src = 'https://soniox.com/media/examples/coffee_shop.mp3';
// Create a media stream from the audio element
const audioContext = new AudioContext();
const source = audioContext.createMediaElementSource(audioElement);
const destination = audioContext.createMediaStreamDestination();
source.connect(destination); // Connect to media stream
source.connect(audioContext.destination); // Connect to playback
// Start transcription
recordTranscribe.start({
model: 'stt-rt-preview',
stream: destination.stream,
onFinished: () => {
audioElement.pause();
},
onError: (status, message) => {
audioElement.pause();
},
});
// Play the audio element to activate the stream
audioElement.play();
```
- Minimal example, a single HTML file: [examples/html](https://github.com/soniox/speech-to-text-web/tree/master/examples/html)
- Vanilla Javascript: [examples/javascript](https://github.com/soniox/speech-to-text-web/tree/master/examples/javascript)
- A bit more advanced example in Next.js with temporary API key generation: [examples/nextjs](https://github.com/soniox/speech-to-text-web/tree/master/examples/nextjs)