### Install dependencies for Speechmatics Node.js examples

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nodejs/README.md

This command installs all necessary project dependencies using pnpm. Ensure Node.js version 22 or higher is installed before running. This step is crucial for setting up the development environment.

```Shell
pnpm i
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-real-time-transcription/README.md

Run this command in the project directory to install all required dependencies, including the Speechmatics SDK packages defined in the repository's `package.json`.

```Shell
pnpm i
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-flow/README.md

Use the pnpm package manager to install all required project dependencies. This command will set up the development environment by installing all packages, including the Speechmatics SDK packages defined in the repository.

```Shell
pnpm i
```

--------------------------------

### Install @speechmatics/browser-audio-input package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Instructions for installing the `@speechmatics/browser-audio-input` package using npm.

```npm
npm i @speechmatics/browser-audio-input
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-real-time-transcription/README.md

Execute this command to start the Next.js development server. The application will typically be accessible on port 3000 in your web browser.

```Shell
pnpm dev
```

--------------------------------

### Run Speechmatics batch file transcription example (Node.js)

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nodejs/README.md

Executes the Speechmatics batch API example, which processes a file for transcription. This command assumes an API key is configured in a .env file. It demonstrates how to use the batch processing capabilities.

```Shell
pnpm run:batch
```

--------------------------------

### Run Next.js Development Server with pnpm

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-flow/README.md

Execute this command to start the Next.js development server. The application will typically be accessible on port 3000, allowing for local development, testing, and real-time code changes.

```Shell
pnpm dev
```

--------------------------------

### Run Speechmatics real-time file transcription example (Node.js)

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nodejs/README.md

Executes the Speechmatics real-time API example for file transcription. This command processes audio data in real-time, requiring a configured API key. It showcases the real-time capabilities of the Speechmatics SDK.

```Shell
pnpm run:real-time-file
```

--------------------------------

### Install Dependencies for React Native Expo Project

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/react-native-flow/README.md

This command installs all necessary Node.js dependencies for the React Native Expo example application, ensuring all required packages are available for development and execution.

```sh
npm install
```

--------------------------------

### Initialize and start PCM audio recording

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Shows how to initialize `PCMRecorder` and start recording audio using an `AudioContext`. It also demonstrates subscribing to the 'recordingStarted' event.

```typescript
import {
  type InputAudioEvent,
  PCMRecorder
} from '@speechmatics/browser-audio-input';

const pcmRecorder = new PCMRecorder("/path/to/pcm-audio-worklet.min.js");

pcmRecorder.addEventListener('recordingStarted', () => {
  console.log("Recording started!");
});

// Later in your app...
const audioContext = new AudioContext();
pcmRecorder.startRecording({ audioContext });
```

--------------------------------

### Install Speechmatics Flow Client React Package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/flow-client-react/README.md

Instructions for installing the `@speechmatics/flow-client-react` package using npm.

```Shell
npm i @speechmatics/flow-client-react
```

--------------------------------

### Install @speechmatics/web-pcm-player-react

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player-react/README.md

Install the React bindings for the web PCM player using npm, enabling integration into React applications.

```Shell
npm i @speechmatics/web-pcm-player-react
```

--------------------------------

### Install web-pcm-player via NPM

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player/README.md

Command to install the @speechmatics/web-pcm-player package using the Node Package Manager.

```bash
npm i @speechmatics/web-pcm-player
```

--------------------------------

### Install Speechmatics Authentication Library

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/auth/README.md

This snippet demonstrates how to install the Speechmatics authentication library using npm, a package manager for JavaScript.

```sh
npm i @speechmatics/auth
```

--------------------------------

### Install Speechmatics Flow Transcript React package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/use-flow-transcript/README.md

Command to install the `@speechmatics/use-flow-transcript` package using npm.

```Shell
npm i @speechmatics/use-flow-transcript
```

--------------------------------

### Install and Configure PNPM for Development

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/CONTRIBUTING.md

A sequence of shell commands to install, configure, and verify PNPM, the package manager used by the Speechmatics Javascript SDK monorepo. This ensures the correct Node.js version and PNPM setup for development.

```Shell
rm -rf $PNPM_HOME
nvm use
corepack use pnpm@latest
corepack enable pnpm
pnpm --version
```

--------------------------------

### Start PCM recording with a specific audio input device

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Illustrates how to select a specific audio input device by its ID when starting PCM recording, leveraging the `getAudioDevicesStore`.

```typescript
import { getAudioDevicesStore } from "@speechmatics/browser-audio-input";

const audioContext = new AudioContext();

// This picks the first device ID (assuming permission has been granted)
const audioDevices = getAudioDevicesStore();
const deviceId = audioDevices.permissionState === "granted" ? audioDevices.devices[0] : undefined;
pcmRecorder.startRecording({ audioContext, deviceId });
```

--------------------------------

### Configure Speechmatics API Key

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-real-time-transcription/README.md

Create a `.env` file in the project root and add your Speechmatics API key. This key is essential for authenticating API requests and generating JWTs.

```Shell
API_KEY=<your api key>
```

--------------------------------

### Configure web-pcm-player using an HTML import map

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player/README.md

Example HTML script tag demonstrating how to use an import map to load the @speechmatics/web-pcm-player library from UNPKG.

```html
<script type="importmap">
  {
    "imports": {
      "@speechmatics/web-pcm-player": "https://unpkg.com/@speechmatics/web-pcm-player@1.0.0-rc/dist/index.min.js"
    }
  }
</script>
```

--------------------------------

### Install Speechmatics Browser Audio Input Package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

Installs the base `@speechmatics/browser-audio-input` package using npm, which provides the PCM audio processor.

```bash
npm i @speechmatics/browser-audio-input
```

--------------------------------

### Install Speechmatics Batch Client with npm

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/batch-client/README.md

This command installs the official JavaScript client for the Speechmatics batch jobs API using npm, the Node.js package manager.

```Shell
npm i @speechmatics/batch-client
```

--------------------------------

### Install Speechmatics Real-Time Client SDK

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/real-time-client/README.md

This command installs the official Speechmatics real-time client JavaScript SDK using npm, the package manager for Node.js. This is the primary method for integrating the SDK into a JavaScript or TypeScript project.

```bash
npm i @speechmatics/real-time-client
```

--------------------------------

### Configure Speechmatics API Key in .env

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs-flow/README.md

Create a .env file in the project root to store your Speechmatics API key. This key is essential for authentication and generating JSON Web Tokens (JWTs) required to access Speechmatics APIs.

```Text
API_KEY=<your api key>
```

--------------------------------

### Install Speechmatics Flow Client npm Package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/flow-client/README.md

Instructions for installing the @speechmatics/flow-client package using npm. Includes a warning about event-target-polyfill for React Native environments.

```bash
npm i @speechmatics/flow-client
```

--------------------------------

### Install Project Dependencies with PNPM

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/CONTRIBUTING.md

Command to install all necessary dependencies for the Speechmatics Javascript SDK monorepo. This should be run from the root directory of the project after cloning.

```Shell
pnpm i
```

--------------------------------

### Play Base64 Audio Chunks with Speechmatics Web PCM Player

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player/example/example.html

This JavaScript code demonstrates how to initialize an `AudioContext` and `PCMPlayer` from `@speechmatics/web-pcm-player` to play base64-encoded audio data chunks. It includes an asynchronous function to decode and play audio, and sets up event listeners for a play button and volume slider. The `base64Data` array contains example audio chunks necessary for the demonstration.

```JavaScript
{ "imports": { "@speechmatics/web-pcm-player": "https://unpkg.com/@speechmatics/web-pcm-player@1.0.0-rc3/dist/index.min.js" } }
import { PCMPlayer } from "@speechmatics/web-pcm-player";

const audioContext = new AudioContext({ sampleRate: 16_000 });
const player = new PCMPlayer(audioContext);

async function playTestAudio() {
  await audioContext.resume();
  for (const audioChunk of base64Data) {
    const { buffer } = Uint8Array.from(atob(audioChunk), (c) => c.charCodeAt(0)
    );
    const data = new Int16Array(buffer);
    player.playAudio(data);
  }
}

window.onload = () => {
  document.getElementById("play-button").addEventListener("click", () => {
    playTestAudio();
  });
  document
    .getElementById("volume-slider")
    .addEventListener("change", (e) => {
      player.volumePercentage = Number.parseInt(e.target.value);
    });
};

const base64Data = [
  "MAA2ACwAJQAgABwAKwAwADIAPwBRAFEAPgBEAEIAOgA9ADoARwBTAF8AZgBnAGoAbABvAGsAcwCCAIUAkACQAI0AkgCPAIcAeAByAIIAiwCGAHYAbwB4AHIAcwCJAIQAeQCJAIcAfACAAH0AgQCDAH4AjACNAIkAlgCEAHcAgwCAAHwAfACEAIkAdwB3AHoAagBjAGwAaQBcAF8AZgBlAFgAVgBVAD0AQABGADoAOgA6ADEAMgAxACkAJgAbABQAEwAKAA0ADQAQABcABAD6//n/8//1/+7/6//p/+r/9v/v/+P/5v/g/9//2v/V/+H/3P/e/+f/2v/a/9r/z//H/w==",
  "v//C/7b/p/+u/63/qP+n/6H/lv+U/5n/kv+Q/5D/hv97/3b/ff9+/3T/cP9x/2b/Yf9q/2n/bP9z/3P/cP9n/2X/af9j/2D/Zv9r/2//bv97/4n/gf97/3X/cv94/3D/bf94/4P/hf95/3X/gP+C/3X/df98/3r/hP+J/43/l/+O/5T/n/+d/6P/pv+w/8P/0P/a/9z/0v/W/+D/4f/t/+v/7f/4//L/8//u/+D/3f/l/+7/8P/6//n/8f/9//j/9v/+//n/AwAHAAcACgAQABkAHAAlACwANQAyADcAUgBMAE8AZwBiAFoAYQBsAHIAeQB+AHsAfwB+AHoAggCAAA==",
  "ggCKAIYAiwCVAJkAlwCWAJoAmwCbAKQAswCzALEAvQDBALwAvQDEAMEAvwC9ALMAtwC3ALIAuAC2ALAArACtAK8ApwCnAKYAogCeAJgAmgCUAIsAjwCOAI0AiQCBAIEAdwB4AHwAbABlAGQAYwBhAF0AWgBaAFsAWgBaAE8ASwBNAEYARABFADkAMwAyAB8AHQAjABkAEAAJAAIABQAGAPz/AAADAPj/7f/p/+X/2v/V/9L/0f/K/8T/xP+4/6//rf+l/53/jv+G/5L/k/+O/4//j/+O/4n/ff95/4L/e/9p/2//dP9z/3n/ef9z/3H/a/9q/2//aP9o/3X/dv9u/w==",
  "cv95/3T/cP9v/27/cP9y/3L/d/95/3n/ff93/3//iv+I/4j/iv+I/4r/k/+R/47/kf+Q/5v/n/+V/5T/lv+c/5b/l/+m/6P/rP+y/6z/tv+5/7X/vf/B/8X/0f/T/9j/1//V/9z/3//l/+P/5P/q/+b/7f/4//r/9/////r/8/8FAP//9/8HAAAA+P/7////AQAFAAoABQAEAAcABgANAAoACQATABUAGgAfACwAKgAhACsAKQArADEAMAA2ADQAMQA0ADEANABDAEcARgBJAEsASABEAEUARwBBAD4ASQBLAEEAPABEAEMAQABJAEYARQBJAEkATABNAE4ASQBHAA==",
  "SABEAEkASgBJAEwASABEAEkATQBJAE0AVABNAFAAUwBIAE0ASwBEAEkARABGAEoAPgA9AEMAQgA8ADIANgA8ADgAOgA7ADwAPQA3ADYAOAAzADEALgArACoAKgAnACQAIwAdABUAFQAYABYAGAAbABMADgAKAAMABAD///v//v////v/+v8AAPv/9v/z/+f/7P/u/+r/6P/l/+b/5f/j/+L/5P/e/9b/2//W/9T/2P/R/9P/0P/M/8//x//H/8j/vP+6/7j/uf++/7r/u/+5/7X/sv+x/7L/r/+3/7T/p/+p/6r/r/+v/7D/r/+w/7n/uP+4/7n/tf+2/7T/uv+6/w==",
  "s/+9/73/tf+6/77/vP+7/7v/tP+w/7P/sv+x/7f/v/+8/7b/vP++/7T/t//E/8j/xP/C/8P/wf/B/8b/yv/Q/9X/0f/S/9f/1P/W/9j/zv/S/+D/3//k/+f/5P/v//P/9P/8//r/+v8CAAYABwALAAwADQAPAAsAFQAeAB0AIQAaABsAKAAkACcALAApACsALQAsACsAMAAwADEANgA2ADoAPAA4ADsAOgA2ADkAPQBBAEUASwBOAEwAVQBZAFUAVgBaAGEAXABaAGAAXABkAGUAXwBhAF4AXwBjAGQAYgBfAGAAYQBZAFoAXABcAFwAWABaAFkAVABUAFIAUABRAA==",
  "UQBPAFIAUQBOAFAATQBIAEoARwBDAEAAQABHAEEAPAA6ADYANwA0ADMALwAtACsAIwAjACMAIQAbABcAHAATAA0AFgATAA8AEAAHAAMABgAHAP//AAABAPf//v/8//H/8v/v/+3/6f/c/+L/5v/W/9z/4P/Z/9f/zP/O/8//yv/K/8H/wP/A/7v/xP/D/7n/uf+y/6//uP+x/6z/tv+y/6b/qv+s/6n/qv+u/7X/s/+v/7D/rP+y/7f/tP+3/7r/u//C/8P/wP/C/8T/yP/H/8X/x//E/8b/zf/L/8r/0f/R/9D/0f/U/9z/4P/Z/9j/2//Y/+D/4P/a/9//3f/c/w==",
  "4//h/+P/6f/u/+//7P/s/+3/8P/x//H/+v/2//T/AQAAAAIABgAFAAcABgAFAAkADwARAA8ADgARABkAFwAaACAAFwAbACAAHAAgAB8AJQAmACQAJwAlACgAKwAsACoAKQAyACwAKgAzADEANAAyAC4AMAAsACwAKwApACUAJQApACYAIgAkACYAJQAjACQAIAAfACEAIAAeABoAGAAaABsAGQAZABgAEAAQABcAFwATABcAFgAMAA0AEAALAA0ADQAKAA0ACwAFAAIA/v8CAAMA//8CAAMABAADAPz/+P/9//3/+P/2//T/9//5//n/9v/z//P/8f/x//D/7//y/w==",
  "8f/v//L/9P/r/+z/7f/n/+n/5//q/+v/5f/m/+f/6v/p/+L/5v/m/+P/6//n/+b/6v/o/+z/7v/r/+3/8P/x/+//7f/t//H/7v/q//H/9P/s/+7/8P/u//L/9f/1//H/8f/x//P/+P/y//H/9//2//X/9P/z//f/9//5//r/+f/4//j//f/8//f/+P////3///8GAP//BwAJAP3/AwADAAEAAAD9/wEAAQD+/wEAAwAAAAEAAwAEAAQAAQADAAIA/v8CAAcACgAGAAMABwAHAAQABwAHAAkADgALAAsADQALAA0AEgASABAADQAOABIADgAPABMAEQATABIADwATAA==",
  "EgAPAA8AEgATABEAEwATAA4ADwATABYAEwAOAA0ADgATABEADwAUAA8ACwAMAAwADQAOAAsADwAPAAgACQAJAAMABQAJAAcABgAIAAkACQAEAAYACAACAAEAAgD9//7/AgD///z/+v/5//z/+P/0//j/9f/2//f/8//1//L/7//v//L/8P/o/+z/7//r/+n/6//t/+n/6P/q/+j/6P/p/+b/5//q/+f/4v/n/+z/5//n/+n/5//k/+L/6f/p/+L/6P/m/+T/6f/m/+j/6f/h/+T/6P/o/+3/7f/q/+z/7v/s//D/9f/v/+//8//x//L/8P/z//T/8//4//n/9//4/w==",
  "9v/1//b/7v/w//f/8//0//L/8//3//H/8v/1//H/8//z//H/9P/0//P/9P/x//D/8//y//L/9f/w//L/9//1//P/9v/4//r//P/7//v//f///wIAAwACAAUABgADAAcABwAGAAwACwALAAoACgAOAA0ADwAPAA0ADwAOAA8AEQASABMAEgAVABMAEAAUABgAGQAWABYAGQAZABsAHAAcAB0AHAAiACAAHAAgACAAHgAhACMAJQAlACQAJwAkACEAIQAgACYAJQAjACYAJgAnACgAJQAkACcAKAAmACQAIwAkACYAJQAmACUAIAAgAB8AIwAiAB0AIAAfABsAGwAYAA==",
  "GAAbABkAGAAbABUAFAATABIAEAAQABMADAANABEACwANAAwABgAIAAYABAAEAPz/AAAGAPn/+/8BAPn/+v/7//f/+P/3//b/8//y//P/8v/z/+7/7v/s/+b/6P/l/+L/5f/j/+P/4P/d/9z/2P/W/9b/1v/W/9L/0v/T/9L/0f/O/8//zv/J/8v/yf/J/8//x//F/83/xP/F/8z/wv/F/8b/wv/I/8X/xP/I/8T/xv/C/8L/xP/B/8T/xf/H/8P/wP/I/8b/xv/G/8f/zP/E/8T/yP/G/8X/w//J/87/yf/K/87/0P/Q/9L/1P/S/9T/2P/Y/9r/2//c/+H/4//j/w=="
];
```

--------------------------------

### Install Speechmatics React Real-time Client

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/real-time-client-react/README.md

Command to install the @speechmatics/real-time-client-react package using npm. This package provides React hooks for real-time audio transcription.

```bash
npm i @speechmatics/real-time-client-react
```

--------------------------------

### Install Speechmatics Browser Audio Input React Package

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

This snippet provides the command to install the @speechmatics/browser-audio-input-react package using npm, which is required to use the React bindings for browser audio input.

```Shell
npm i @speechmatics/browser-audio-input-react
```

--------------------------------

### Configure Webpack to copy AudioWorklet script

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Provides a Webpack configuration example using `copy-webpack-plugin` to ensure the `pcm-audio-worklet.min.js` script is copied to the public directory, which is necessary for `AudioWorklet` to function correctly.

```javascript
const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  // ... rest of your Webpack config
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: path.resolve(
            __dirname,
            'node_modules/@speechmatics/browser-audio-input/dist/pcm-audio-worklet.min.js'
          ),
          to: path.resolve(__dirname, 'public/js/[name][ext]')
        }
      ]
    })
  ]
};
```

--------------------------------

### Initiate a Conversation with Speechmatics Flow API

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/flow-client-react/README.md

Example of using `startConversation` with a JWT and configuration options, including `template_id` and `audioFormat`. The `audioFormat` specifies the type, encoding, and sample rate of the audio.

```TypeScript
  await startConversation(jwt, {
    config: {
      template_id: personaId,
      template_variables: {},
    },
    audioFormat: {
      type: 'raw',
      encoding: 'pcm_s16le',
      sample_rate: 16000,
    },
  });
```

--------------------------------

### Perform Real-time Audio Transcription with Speechmatics SDK

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/auth/README.md

This TypeScript example illustrates how to set up a real-time client for Speechmatics, generate a JSON Web Token (JWT) for authentication, stream an audio file, and handle incoming transcription messages. It showcases the integration of the authentication and real-time client libraries.

```typescript
import { RealtimeClient } from '@speechmatics/real-time-client';
import { createSpeechmaticsJWT } from '@speechmatics/auth';

const client = new RealtimeClient();

client.addEventListener('receiveMessage', ({ data }) => {
  // Handle transcription messages
});

async function transcribeFileRealtime () {
  const jwt = await createSpeechmaticsJWT({
    type: 'rt',
    apiKey,
    ttl: 60, // 1 minute
  });

  const fileStream = fs.createReadStream(
    path.join(__dirname, './example.wav'),
    {
      highWaterMark: 4096, //avoid sending faster than realtime
    },
  );

  await client.start(jwt, {
    transcription_config: {
      language: 'en',
      enable_partials: true,
    },
  });

  //send it
  fileStream.on('data', (sample) => {
    client.sendAudio(sample);
  });

  //end the session
  fileStream.on('end', () => {
    client.stopRecognition();
  });
}

transcribeFileRealtime();
```

--------------------------------

### Play Base64 encoded PCM audio with JavaScript

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player/README.md

A JavaScript example demonstrating how to initialize PCMPlayer with an AudioContext and play pcm_s16le audio data. It shows the process of decoding Base64 chunks into Int16Array for playback.

```javascript
import { PCMPlayer } from "@speechmatics/web-pcm-player";

async function playTestAudio() {
  const audioContext = new AudioContext({ sampleRate: 16_000 });
  await audioContext.resume();
  const player = new PCMPlayer(audioContext);

  for (const audioChunk of base64Data) {
    const buffer = Uint8Array.from(atob(audioChunk), (c) =>
      c.charCodeAt(0)
    );
    const data = new Int16Array(buffer.buffer);
    player.playAudio(data);
  }
}

window.onload = () => {
  document.getElementById("play-button").addEventListener("click", () => {
    playTestAudio();
  });
};

const base64Data = [
  // See data in the examples/ folder
];
```

--------------------------------

### Initialize and Manage Conversation with Speechmatics FlowClient

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/flow-client/README.md

Demonstrates how to import and instantiate FlowClient, attach event listeners for agentAudio, start a conversation with a JWT and configuration (including audio format), send PCM audio data, and gracefully end the conversation by removing listeners and closing the websocket.

```typescript
import { FlowClient, AgentAudioEvent } from "@speechmatics/flow-client";
const flowClient = new FlowClient('wss://flow.api.speechmatics.com', { appId: "example" });

function onAgentAudio(audio: AgentAudioEvent) {
  // audio.data is PCM16_SLE data. How you play this depends on your environment
  myAudioPlayFunction(audio.data)
}

flowClient.addEventListener("agentAudio", onAgentAudio);

flowClient.startConversation(YOUR_JWT, {
  config: {
    template_id: "flow-service-assistant-amelia",
    template_variables: {},
  },
  // Optional, this is the default
  audio_format: {
    type: 'raw',
    encoding: 'pcm_s16le',
    sample_rate: 16000,
  },
});

// PCM audio can be sent to the client (either f32 or int16 depending on the audio_format defined above)
function onPCMAudio(audio: Int16Array) {
  flowClient.sendAudio(audio);
}


function onSessionEnd() {
  // Ends conversation and closes websocket
  flowClient.endConversation();

  // Event listeners can also be removed like so
  flowClient.removeEventListener("agentAudio", onAgentAudio);
}
```

--------------------------------

### Toggle Audio Recording with React Hook

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

This React component uses the usePCMAudioRecorderContext hook to access recording functions. It provides a button to start or stop audio recording, managing the isRecording state and initializing an AudioContext when starting recording. stopRecording halts the stream but keeps the AudioContext open for reuse.

```TSX
import { usePCMAudioRecorderContext } from "@speechmatics/browser-audio-input-react";

function RecordingButton() {
  const { startRecording, stopRecording, isRecording } = usePCMAudioRecorderContext();

  const onClick = () => {
    if (isRecording) {
      stopRecording();
    } else {
      const audioContext = new AudioContext();
      startRecording({ audioContext });
    }
  }

  return <button onClick={onClick}>
    {isRecording ? "Stop recording" : "Start recording" }
  </button>
}
```

--------------------------------

### Configure RealtimeTranscriptionProvider in React Root Layout

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/real-time-client-react/README.md

Demonstrates how to wrap a React application with RealtimeTranscriptionProvider and PCMAudioRecorderProvider. This setup is essential for enabling Speechmatics real-time transcription and capturing PCM microphone audio within your React project.

```jsx
import { RealtimeTranscriptionProvider } from "@speechmatics/real-time-client-react";
import { PCMAudioRecorderProvider } from '@speechmatics/browser-audio-input-react';

function RootLayout({children}) {
  /*
    Two context providers wrapping the app:
      - One for the Speechmatics Real time transcription client
      - One for capturing PCM microphone audio in the browser
        see https://www.npmjs.com/package/@speechmatics/browser-audio-input-react
  */
  return <RealtimeTranscriptionProvider>
    <PCMAudioRecorderProvider workletScriptURL="/js/pcm-audio-worklet.min.js">
      {children}
    </PCMAudioRecorderProvider>
  </RealtimeTranscriptionProvider>
}
```

--------------------------------

### Configure Speechmatics API Key for Expo React Native

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/react-native-flow/README.md

This snippet demonstrates how to set up the Speechmatics API key as an environment variable in an Expo React Native project. The key should be placed in a `.env` file at the project root and is used by the application to request a temporary token for the Flow API.

```sh
EXPO_PUBLIC_SPEECHMATICS_API_KEY='YOUR-API-KEY-HERE'
```

--------------------------------

### Use Speechmatics Real-time Transcription Hooks in React Component

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/real-time-client-react/README.md

Illustrates how to use useRealtimeTranscription and usePCMAudioRecorder hooks within a React component. This example shows how to start/stop transcription, send audio, and manage recording sessions, including fetching a JWT for authentication.

```jsx
import {
  type RealtimeTranscriptionConfig,
  useRealtimeTranscription,
} from '@speechmatics/real-time-client-react';

import {
  usePCMAudioListener,
  usePCMAudioRecorder,
} from '@speechmatics/browser-audio-input-react';

// We recommend 16_000Hz sample rate for speech audio.
// Anything higher will be downsampled server-side
const RECORDING_SAMPLE_RATE = 16_000;

function MyComponent() {
  const { startTranscription, stopTranscription, sendAudio, socketState } =
    useRealtimeTranscription();

  const { isRecording, startRecording, stopRecording } = usePCMAudioRecorder();

  // Send audio to Speechmatics when captured
  usePCMAudioListener(sendAudio);

  const startSession = useCallback(
    async (config: RealtimeTranscriptionConfig) => {
      // getJWT can fetch an ephemeral key based on your setup
      // See our NextJS example: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/nextjs/src/app/actions.ts
      const jwt = await getJWT('rt');

      // Start a Speechmatics session, then start recording to stream the audio
      await startTranscription(jwt, config);
      await startRecording({ sampleRate: RECORDING_SAMPLE_RATE });
    },
    [startTranscription, startRecording],
  );
}
```

--------------------------------

### Run React Native Expo App on Device in Release Mode

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/react-native-flow/README.md

These commands build and run the React Native Expo application directly on a physical iOS or Android device in release configuration. This is necessary to test advanced audio features like Acoustic Echo Cancelling, noise reduction, or microphone modes, which may not work on simulators.

```bash
npx expo run:ios --device --configuration Release
npx expo run:android --device --variant release
```

--------------------------------

### Run React Native Expo App in Development Mode

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/examples/react-native-flow/README.md

These commands launch the React Native Expo application for iOS or Android in development mode. It's important to note that some audio features may not function correctly in Expo Go, requiring a development build for full functionality.

```sh
npm run ios
npm run android
```

--------------------------------

### Initialize PCMRecorder with Vite Worker URL

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

This TypeScript snippet demonstrates how to initialize the `PCMRecorder` from the `@speechmatics/browser-audio-input` library in a Vite project. It leverages Vite's `?url` import suffix to reference the `pcm-audio-worklet.min.js` script as a URL, which is then passed to the `PCMRecorder` constructor for use in a Web Worker.

```typescript
import {
  type InputAudioEvent,
  PCMRecorder
} from '@speechmatics/browser-audio-input';
import PCMAudioWorkletUrl from "@speechmatics/browser-audio-input/pcm-audio-worklet.min.js?url";

const PCMRecorder = new PCMRecorder(PCMAudioWorkletUrl);
```

--------------------------------

### Configure PCMPlayerProvider for Global Audio Context

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player-react/README.md

Illustrates how to set up `PCMPlayerProvider` to wrap a React application or a section, making the audio player state accessible via React Context. It includes a pattern for safely initializing `AudioContext` to support server-side rendering environments.

```TSX
import { PCMPlayerProvider } from '@speechmatics/web-pcm-player-react';

export function ({ children }) {
  const audioContext = useMemo(
    () =>
      // Note audioContext may be undefined if we are rendering on the server. The provider supports this
      typeof window !== "undefined" ? new AudioContext() : undefined,
    [],
  );

  <PCMPlayerProvider audioContext={audioContext}>
    {children}
  </PCMPlayerProvider>
}
```

--------------------------------

### Configure recording options for PCM audio capture

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Explains how to pass `MediaTrackSettings` as `recordingOptions` to `startRecording` for fine-grained control over audio processing like noise suppression.

```typescript
pcmRecorder.startRecording({
  audioContext,
  deviceId,
  recordingOptions: {
    noiseSuppression: false
  }
});
```

--------------------------------

### Query available audio input devices in browser

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input/README.md

Demonstrates how to use `getAudioDevicesStore` to access and listen for changes in available audio input devices and their permission state.

```typescript
import { getAudioDevicesStore } from "@speechmatics/browser-audio-input";
const audioDevices = getAudioDevicesStore();

audioDevices.addEventListener("changeDevices", (e) => {
  if (audioDevices.permissionState === "granted") {
    // This will print all available devices
    console.log(audioDevices.devices)
  }
});
```

--------------------------------

### Use PCMAudioRecorderProvider with Vite URL Import

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

Illustrates how Vite's URL import feature can be used to reference the `pcm-audio-worklet.min.js` script directly within `PCMAudioRecorderProvider`.

```tsx
// VITE EXAMPLE
import { PCMAudioRecorderProvider } from '@speechmatics/browser-audio-input-react';
import workletScriptURL from '@speechmatics/browser-audio-input/pcm-audio-worklet.min.js?url';

function App() {
  return (
    <PCMAudioRecorderProvider workletScriptURL={workletScriptURL}>
      <Component>
    </PCMAudioRecorderProvider>
  );
}
```

--------------------------------

### Access AnalyserNode for Audio Visualization

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

Demonstrates how to obtain the `analyser` object, an instance of `AnalyserNode`, from the `usePCMAudioRecorderContext` hook for creating audio visualizers.

```typescript
const { analyser } = usePCMAudioRecorderContext();
```

--------------------------------

### Speechmatics FlowClient API Reference

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/flow-client/README.md

Detailed API reference for the FlowClient class, outlining its constructor parameters, key methods (addEventListener, startConversation, sendAudio, endConversation, removeEventListener), and the structure of the AgentAudioEvent.

```APIDOC
FlowClient:
  Description: Official Javascript client for the Speechmatics Flow API. An EventTarget that allows listening for incoming events.
  Constructor:
    new FlowClient(websocketUrl: string, options?: object)
      websocketUrl: The WebSocket URL for the Flow API.
      options: Optional configuration object.
        appId: string (e.g., "example")
  Methods:
    addEventListener(eventName: string, listener: Function):
      Description: Attaches an event listener.
      Parameters:
        eventName: "agentAudio" | "sessionEnd" | ...
        listener: The callback function for the event.
    startConversation(jwt: string, config: object):
      Description: Initiates a conversation.
      Parameters:
        jwt: Your JWT token for authentication.
        config: Conversation configuration.
          config:
            template_id: string (e.g., "flow-service-assistant-amelia")
            template_variables: object
          audio_format:
            type: 'raw'
            encoding: 'pcm_s16le'
            sample_rate: 16000
    sendAudio(audioData: Int16Array | Float32Array):
      Description: Sends audio data to the client.
      Parameters:
        audioData: PCM audio data (Int16Array or Float32Array).
    endConversation():
      Description: Ends the current conversation and closes the websocket.
    removeEventListener(eventName: string, listener: Function):
      Description: Removes an event listener.
      Parameters:
        eventName: string
        listener: Function

AgentAudioEvent:
  Description: Event object for incoming agent audio.
  Properties:
    data: PCM16_SLE audio data (e.g., Uint8Array or similar).

fetchPersonas:
  Description: Function to fetch personas (details not provided in snippet).
```

--------------------------------

### Run Code Linting and Formatting Checks

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/CONTRIBUTING.md

Commands to execute linting and formatting checks using Biome, ensuring code quality and adherence to the project's style guidelines within the Speechmatics Javascript SDK.

```Shell
pnpm lint
pnpm format
```

--------------------------------

### Use PCMAudioRecorderProvider with Webpack Path

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

Shows how to configure `PCMAudioRecorderProvider` in a React component, referencing the `pcm-audio-worklet.min.js` script copied by Webpack.

```tsx
// WEBPACK EXAMPLE
import { PCMAudioRecorderProvider } from '@speechmatics/browser-audio-input-react';

function App() {
  return (
    <PCMAudioRecorderProvider workletScriptURL="/js/pcm-audio-worklet.min.js">
      <Component>
    </PCMAudioRecorderProvider>
  );
}
```

--------------------------------

### Play 16-bit PCM Audio from Base64 with usePCMAudioPlayer

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player-react/README.md

Demonstrates how to use the `usePCMAudioPlayer` hook in a React component to play 16-bit integer PCM audio. It shows initializing an `AudioContext`, converting base64 audio chunks to `Int16Array` buffers, and providing UI controls for playback and volume adjustment.

```TSX
import { usePCMAudioPlayer } from '@speechmatics/web-pcm-player-react';
import { useMemo } from 'react';

const base64Data = [
  // See this file for full test data:
  // packages/web-pcm-player/example/example.html
]

export default function Component() {
  const audioContext = useMemo(
    () => new AudioContext({ sampleRate: 16_000 }),
    [],
  );

  const { playAudio, volumePercentage, setVolumePercentage } =
    usePCMAudioPlayer(audioContext);

  async function playTestAudio() {
    await audioContext.resume();

    for (const audioChunk of base64Data) {
      const buffer = Uint8Array.from(atob(audioChunk), (c) => c.charCodeAt(0));
      const data = new Int16Array(buffer.buffer);
      playAudio(data);
    }
  }

  function handleVolumeChange(e) {
    setVolumePercentage(Number(e.target.value));
  }

  return (
    <div>
      <button type="button" onClick={playTestAudio}>
        Play
      </button>
      <br />
      <label>
        Volume
        <input
          type="range"
          value={volumePercentage}
          onChange={handleVolumeChange}
        />
      </label>
    </div>
  );
}
```

--------------------------------

### Speechmatics BatchClient Class API Key Information

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/batch-client/README.md

Details regarding the `apiKey` property of the `BatchClient` class, specifying its type and handling for long-lived keys versus short-lived JWTs.

```APIDOC
BatchClient:
  Properties:
    apiKey:
      Type: string
      Description: API key for authentication. Can be a long-lived API key or a short-lived JWT.
      Notes: If a JWT, the developer is responsible for making sure the key is valid.
```

--------------------------------

### Specify Recording Options for PCM Audio

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

This snippet demonstrates how to pass MediaTrackSettings as recordingOptions to the startRecording method. It shows how to disable noiseSuppression and highlights the default optimized settings for speech, including echoCancellation and autoGainControl, with a note on browser compatibility.

```typescript
pcmRecorder.startRecording({
      audioContext,
      deviceId,
      recordingOptions: {
        noiseSuppression: false,
      },
    });
```

```javascript
{
  noiseSuppression: true,
  echoCancellation: true,
  autoGainControl: true,
}
```

--------------------------------

### Configure Webpack to Copy AudioWorklet Script

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

Demonstrates how to use `copy-webpack-plugin` to copy the `pcm-audio-worklet.min.js` file to the public directory, addressing Webpack's limitations with AudioWorklet scripts.

```javascript
const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  // ... rest of your Webpack config
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        {
          from: path.resolve(
            __dirname,
            'node_modules/@speechmatics/browser-audio-input/dist/pcm-audio-worklet.min.js',
          ),
          to: path.resolve(__dirname, 'public/js/[name][ext]'),
        },
      ],
    }),
  ]
};
```

--------------------------------

### Configure PCM Audio Recorder Provider in React App

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/browser-audio-input-react/README.md

This snippet demonstrates how to wrap a React application with the PCMAudioRecorderProvider. This provider makes a single PCM recorder instance available to all child components, centralizing control over audio recording within the application. It requires a workletScriptURL for the AudioWorklet script.

```TSX
import { PCMAudioRecorderProvider } from '@speechmatics/browser-audio-input-react';

function App() {
  return (
    // See note in the next section about the AudioWorklet script
    <PCMAudioRecorderProvider workletScriptURL="/path/to/pcm-audio-worklet.min.js">
      <Component>
    </PCMAudioRecorderProvider>
  );
}
```

--------------------------------

### Access Audio Player State with usePCMAudioPlayerContext

Source: https://github.com/speechmatics/speechmatics-js-sdk/blob/main/packages/web-pcm-player-react/README.md

Shows how to consume the audio player state and functions from the `PCMPlayerContext` within any child component using the `usePCMAudioPlayerContext` hook. This allows components deep in the tree to control audio playback and volume without prop drilling.

```TSX
import { usePCMAudioPlayerContext } from '@speechmatics/web-pcm-player-react';

const base64Data = [
  // See this file for full test data:
  // packages/web-pcm-player/example/example.html
]

export default function Component() {
  const { playAudio, volumePercentage, setVolumePercentage } =
    usePCMAudioPlayerContext();

  async function playTestAudio() {
    await audioContext.resume();

    for (const audioChunk of base64Data) {
      const buffer = Uint8Array.from(atob(audioChunk), (c) => c.charCodeAt(0));
      const data = new Int16Array(buffer.buffer);
      playAudio(data);
    }
  }

  function handleVolumeChange(e) {
    setVolumePercentage(Number(e.target.value));
  }

  // ...
 
}
```