### Clone Repository and Install Dependencies (Bash)

Source: https://github.com/build-with-groq/groq-voice-agent-template/blob/main/README.md

Instructions for cloning the Groq Voice Agent Template repository and installing its dependencies using npm. This is a standard setup process for Node.js projects.

```bash
git clone https://github.com/benank/groq-voice-agent-template
cd groq-voice-agent-template
npm install
```

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

### Start Development Server (Bash)

Source: https://github.com/build-with-groq/groq-voice-agent-template/blob/main/README.md

Command to start the development server for the Groq Voice Agent Template. This allows for local testing and development of the application.

```bash
npm run dev
```

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

### Manage Groq API Key with TypeScript

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Illustrates the usage of apiKeyStore for managing and validating Groq API keys using Svelte stores. It includes functions to set, get, check for, and clear API keys, along with reactive subscription to state changes. The store automatically validates the API key format.

```typescript
import { apiKeyStore } from '@shared/stores/apiKeyStore';

// Set a new API key (validates automatically)
const result = apiKeyStore.setApiKey('gsk_yourApiKeyHere123456789');
if (result.success) {
  console.log('API key is valid');
} else {
  console.error('Validation error:', result.error);
}

// Check if API key exists and is valid
if (apiKeyStore.hasApiKey()) {
  const key = apiKeyStore.getApiKey();
  console.log('Using API key:', key);
}

// Subscribe to API key changes (Svelte reactive)
apiKeyStore.subscribe(state => {
  console.log('Key:', state.key);
  console.log('Valid:', state.isValid);
  console.log('Error:', state.error);
});

// Clear the API key
apiKeyStore.clearApiKey();
```

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

### Voice Activity Detection (VAD) with @ricky0123/vad-web

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Integrates browser-based voice activity detection using the @ricky0123/vad-web library. VAD automatically detects speech start and end, triggering transcription. It requires dynamic loading of ONNX Runtime and the VAD library scripts. The configuration includes thresholds for speech and silence detection, and model/worklet URLs.

```typescript
// Load VAD scripts dynamically
async function loadVADScripts(): Promise<void> {
  // Load ONNX Runtime
  const onnxScript = document.createElement('script');
  onnxScript.src = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.16.0/dist/ort.min.js';
  document.head.appendChild(onnxScript);
  await new Promise(resolve => onnxScript.onload = resolve);

  // Load VAD library
  const vadScript = document.createElement('script');
  vadScript.src = 'https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.12/dist/bundle.min.js';
  document.head.appendChild(vadScript);
  await new Promise(resolve => vadScript.onload = resolve);
}

// Create VAD instance with microphone stream
async function createVAD(audioStream: MediaStream): Promise<any> {
  return await window.vad.MicVAD.new({
    stream: audioStream,
    onSpeechStart: () => {
      console.log('User started speaking');
      // Update UI to show recording state
    },
    onSpeechEnd: async (audio: Float32Array) => {
      console.log('User stopped speaking, audio length:', audio.length);
      // Convert to WAV and send for transcription
      const wavBlob = await float32ArrayToWav(audio);
      await sendAudioForTranscription(wavBlob);
    },
    // VAD configuration options
    positiveSpeechThreshold: 0.8,  // Confidence for speech detection
    negativeSpeechThreshold: 0.5,  // Threshold for silence detection
    minSpeechFrames: 5,            // Minimum frames to consider as speech
    preSpeechPadFrames: 5,         // Frames to include before speech
    redemptionFrames: 10,          // Frames before confirming end of speech
    // CDN URLs for model files
    modelUrl: 'https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.12/dist/silero_vad.onnx',
    workletUrl: 'https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.12/dist/vad.worklet.bundle.min.js',
  });
}

// Start VAD
await vadInstance.start();

// Stop VAD
await vadInstance.stop();
```

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

### Initialize Groq Service with TypeScript

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Demonstrates how to initialize the GroqService, which manages the Groq SDK client instance. It handles API key updates and initialization state, allowing for easy integration of Groq's services into the application. The service is typically initialized on application mount.

```typescript
import { groqService } from '@shared/services/groqService';

// Initialize the service (called on app mount)
groqService.initialize();

// Check if the service is ready (API key is set)
if (groqService.isReady()) {
  // Use the Groq client
  const completion = await groqService.client.chat.completions.create({
    messages: [
      { role: "system", content: "You are a helpful AI assistant." },
      { role: "user", content: "Hello, how are you?" }
    ],
    model: "meta-llama/llama-4-maverick-17b-128e-instruct",
    temperature: 0.7,
    max_tokens: 150,
    stream: false,
  });

  console.log(completion.choices[0].message.content);
}
```

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

### Groq Service Initialization

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Demonstrates how to initialize and use the GroqService for interacting with Groq's AI models. It covers setting up the client, checking readiness, and making a chat completion request.

```APIDOC
## Groq Service Initialization

### Description
Initializes and manages the Groq SDK client instance using a singleton pattern. Automatically updates the API key from the store and tracks initialization state.

### Method
`groqService.initialize()`
`groqService.isReady()`
`groqService.client.chat.completions.create()`

### Endpoint
N/A (Client-side SDK usage)

### Parameters
#### Request Body (for `chat.completions.create`)
- **messages** (array) - Required - An array of message objects representing the conversation history.
- **model** (string) - Required - The ID of the Groq model to use (e.g., `meta-llama/llama-4-maverick-17b-128e-instruct`).
- **temperature** (number) - Optional - Controls randomness. Lower values make the output more focused and deterministic.
- **max_tokens** (number) - Optional - The maximum number of tokens to generate in the completion.
- **stream** (boolean) - Optional - Whether to stream back partial progress. Defaults to `false`.

### Request Example
```typescript
import { groqService } from '@shared/services/groqService';

groqService.initialize();

if (groqService.isReady()) {
  const completion = await groqService.client.chat.completions.create({
    messages: [
      { role: "system", content: "You are a helpful AI assistant." },
      { role: "user", content: "Hello, how are you?" }
    ],
    model: "meta-llama/llama-4-maverick-17b-128e-instruct",
    temperature: 0.7,
    max_tokens: 150,
    stream: false,
  });
  console.log(completion.choices[0].message.content);
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array containing the generated completion(s).
  - **message** (object)
    - **content** (string) - The generated text response from the AI model.
```

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

### Control Microphone Input with TypeScript

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Shows how to use the microphoneStore to manage available audio input devices and the selected microphone. It supports setting devices, selecting a specific microphone by its ID, subscribing to changes in microphone state, and resetting the store to its default.

```typescript
import { microphoneStore, type MicrophoneDevice } from '@shared/stores/microphoneStore';

// Set available devices (typically from navigator.mediaDevices.enumerateDevices)
const devices: MicrophoneDevice[] = [
  { deviceId: 'default', label: 'Default Microphone' },
  { deviceId: 'device123', label: 'USB Microphone' }
];
microphoneStore.setDevices(devices);

// Select a specific microphone
microphoneStore.setSelectedDeviceId('device123');

// Subscribe to microphone changes
microphoneStore.subscribe(state => {
  console.log('Available devices:', state.devices);
  console.log('Selected device ID:', state.selectedDeviceId);
});

// Reset microphone state
microphoneStore.reset();
```

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

### Microphone Store Management

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Explains the microphoneStore for managing audio input devices, including setting available devices, selecting a microphone, and subscribing to microphone state changes.

```APIDOC
## Microphone Store

### Description
Manages available audio input devices and the currently selected microphone. Handles device enumeration and persists selection.

### Method
`microphoneStore.setDevices(devices: MicrophoneDevice[])`
`microphoneStore.setSelectedDeviceId(deviceId: string)`
`microphoneStore.subscribe(callback)`
`microphoneStore.reset()`

### Endpoint
N/A (Client-side store management)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { microphoneStore, type MicrophoneDevice } from '@shared/stores/microphoneStore';

const devices: MicrophoneDevice[] = [
  { deviceId: 'default', label: 'Default Microphone' },
  { deviceId: 'device123', label: 'USB Microphone' }
];
microphoneStore.setDevices(devices);

microphoneStore.setSelectedDeviceId('device123');

microphoneStore.subscribe(state => {
  console.log('Available devices:', state.devices);
  console.log('Selected device ID:', state.selectedDeviceId);
});

microphoneStore.reset();
```

### Response
#### Success Response (N/A - methods return values or trigger side effects)
- **subscribe**: Callback receives state `{ devices: MicrophoneDevice[], selectedDeviceId: string | null }`.

#### Response Example
```json
{
  "devices": [
    { "deviceId": "default", "label": "Default Microphone" },
    { "deviceId": "device123", "label": "USB Microphone" }
  ],
  "selectedDeviceId": "device123"
}
```
```

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

### Manage Microphone Audio Input with Web Audio API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Handles microphone access, configuration, and stream management using the Web Audio API. It allows selecting specific input devices, applying noise suppression, and enumerating available microphones.

```typescript
// Request microphone access with configuration
async function getMicrophoneStream(deviceId?: string): Promise<MediaStream> {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      deviceId: deviceId ? { exact: deviceId } : undefined,
      echoCancellation: true,
      noiseSuppression: true,
      autoGainControl: true,
    },
  });
  return stream;
}

// Enumerate available microphones
async function getMicrophones(): Promise<MediaDeviceInfo[]> {
  const devices = await navigator.mediaDevices.enumerateDevices();
  return devices.filter(d => d.kind === 'audioinput');
}

// Listen for device changes
avigator.mediaDevices.addEventListener('devicechange', async () => {
  const microphones = await getMicrophones();
  console.log('Available microphones:', microphones);
});

// Stop microphone stream
function stopMicrophone(stream: MediaStream) {
  stream.getTracks().forEach(track => track.stop());
}
```

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

### TTS Audio Buffer Management for Playback and Visualization

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Manages streaming audio playback and visualization using the TTSAudioBuffer class. It buffers audio chunks, converts PCM16 data, and provides callbacks for frequency data visualization. Requires the '@shared/utils/tts-audio-buffer' module.

```typescript
import { TTSAudioBuffer } from '@shared/utils/tts-audio-buffer';

// Create audio buffer with callbacks
const ttsAudioBuffer = new TTSAudioBuffer({
  onAudioEnded: () => {
    console.log('Audio playback finished');
    // Transition to listening state
  },
  onAudioData: (audioData: Float32Array) => {
    // Process frequency data for visualization
    // audioData contains dB values for frequency bins
    const maxDb = Math.max(...audioData);
    console.log('Current max dB:', maxDb);
  }
});

// Connect audio context (must be called after user interaction)
await ttsAudioBuffer.connectAudioContext();

// Add audio chunks as they stream in
ttsAudioBuffer.addChunk(audioChunk); // Uint8Array

// Flush remaining buffered data when stream ends
ttsAudioBuffer.flushBufferedData();

// Check playback status
if (ttsAudioBuffer.isPlaying) {
  console.log('Audio is currently playing');
}

// Reset buffer and stop playback
await ttsAudioBuffer.reset();

// Update audio data callback dynamically
ttsAudioBuffer.updateAudioDataCallback((data) => {
  // New visualization callback
});
```

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

### TTS Audio Buffer Utility

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Documentation for the TTSAudioBuffer class, which manages the buffering, playback, and visualization of streamed TTS audio data.

```APIDOC
## TTS Audio Buffer

### Description
The `TTSAudioBuffer` class is a utility for handling streamed Text-to-Speech audio. It buffers incoming audio chunks, manages playback, and provides callbacks for audio data processing, useful for visualizations.

### Methods
- **`connectAudioContext()`**: Initializes the Web Audio API context. Must be called after user interaction.
- **`addChunk(audioChunk: Uint8Array)`**: Adds a chunk of audio data to the buffer.
- **`flushBufferedData()`**: Processes any remaining buffered audio data.
- **`reset()`**: Stops playback and clears the buffer.
- **`updateAudioDataCallback(callback: (data: Float32Array) => void)`**: Updates the callback function that receives audio data for visualization.

### Properties
- **`isPlaying`**: (boolean) - Indicates if audio is currently playing.

### Callbacks
- **`onAudioEnded`**: Called when audio playback finishes.
- **`onAudioData`**: Called with frequency data (dB values) for visualization purposes.

### Usage Example
```typescript
import { TTSAudioBuffer } from '@shared/utils/tts-audio-buffer';

const ttsAudioBuffer = new TTSAudioBuffer({
  onAudioEnded: () => console.log('Audio finished'),
  onAudioData: (data) => console.log('Frequency data:', data)
});

await ttsAudioBuffer.connectAudioContext();
ttsAudioBuffer.addChunk(audioChunk);
ttsAudioBuffer.flushBufferedData();

if (ttsAudioBuffer.isPlaying) {
  console.log('Playing...');
}

await ttsAudioBuffer.reset();
```
```

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

### API Key Store Management

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Details on how the apiKeyStore manages Groq API keys, including setting, validating, retrieving, and subscribing to changes in the API key state.

```APIDOC
## API Key Store

### Description
Manages Groq API key storage and validation using Svelte stores. Validates API keys and provides reactive state updates.

### Method
`apiKeyStore.setApiKey(key: string)`
`apiKeyStore.hasApiKey()`
`apiKeyStore.getApiKey()`
`apiKeyStore.subscribe(callback)`
`apiKeyStore.clearApiKey()`

### Endpoint
N/A (Client-side store management)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { apiKeyStore } from '@shared/stores/apiKeyStore';

// Set a new API key
const result = apiKeyStore.setApiKey('gsk_yourApiKeyHere123456789');
if (result.success) {
  console.log('API key is valid');
} else {
  console.error('Validation error:', result.error);
}

// Check if API key exists
if (apiKeyStore.hasApiKey()) {
  const key = apiKeyStore.getApiKey();
  console.log('Using API key:', key);
}

// Subscribe to changes
apiKeyStore.subscribe(state => {
  console.log('Key:', state.key);
  console.log('Valid:', state.isValid);
  console.log('Error:', state.error);
});

// Clear the API key
apiKeyStore.clearApiKey();
```

### Response
#### Success Response (N/A - methods return values or trigger side effects)
- **setApiKey**: Returns an object `{ success: boolean, error?: string }`.
- **hasApiKey**: Returns `boolean`.
- **getApiKey**: Returns `string | null`.
- **subscribe**: Callback receives state `{ key: string | null, isValid: boolean, error: string | null }`.

#### Response Example
```json
{
  "success": true
}
```
```json
{
  "key": "gsk_yourApiKeyHere123456789",
  "isValid": true,
  "error": null
}
```
```

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

### Configure Voice Agent Flow with Svelte Flow

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Defines the nodes and edges for visualizing the voice processing pipeline using Svelte Flow. It includes importing default configurations and defining custom nodes and edges with specific properties like labels, icons, and positions.

```typescript
import { getDefaultVoiceAgentFlow } from '@features/blueprints/svelteFlow/flowConfigs/voiceAgentFlow';
import { Position, type Node, type Edge } from '@xyflow/svelte';
import { Mic, Volume2, Bot, Play } from '@lucide/svelte';

// Get default voice agent flow configuration
const flowConfig = getDefaultVoiceAgentFlow();
console.log(flowConfig.nodes);  // Array of Node objects
console.log(flowConfig.edges);  // Array of Edge objects
console.log(flowConfig.theme);  // Theme configuration

// Custom node definition
const customNode: Node = {
  id: 'custom-node',
  type: 'turbo',
  data: {
    label: 'Custom Step',
    icon: Bot,
    subtitle: 'Description',
    sourcePosition: Position.Right,
    targetPosition: Position.Left,
    isActive: false,
    isProcessing: false,
    isCompleted: false,
  },
  position: { x: 300, y: 200 },
};

// Custom edge definition
const customEdge: Edge = {
  id: 'e-source-target',
  source: 'source-node-id',
  target: 'target-node-id',
  animated: true,
  type: 'smoothstep',
  label: 'Connection Label',
  style: 'stroke: #FF5C00; stroke-width: 2;',
};
```

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

### LLM Chat Completion with Groq API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Generates contextual AI responses using Groq's chat completion API. It supports multiple LLM models and maintains conversation history for context. Requires the 'groq-sdk' package.

```typescript
import Groq from 'groq-sdk';

const groq = new Groq({
  apiKey: 'gsk_yourApiKey',
  dangerouslyAllowBrowser: true
});

// Maintain conversation history for context
const conversationHistory: Array<{ role: string; content: string }> = [];

async function getAIResponse(userText: string, systemPrompt: string): Promise<string> {
  // Add user message to history
  conversationHistory.push({ role: "user", content: userText });

  // Prepare messages with system prompt and history
  const messages = [
    { role: "system", content: systemPrompt },
    ...conversationHistory,
  ];

  const completion = await groq.chat.completions.create({
    messages,
    model: "meta-llama/llama-4-maverick-17b-128e-instruct",
    // Alternative models:
    // "llama-3.1-8b-instant"
    // "llama-3.3-70b-versatile"
    // "meta-llama/llama-4-scout-17b-16e-instruct"
    temperature: 0.7,
    max_tokens: 150,
    stream: false,
  });

  const response = completion.choices[0].message.content;

  // Add assistant response to history
  conversationHistory.push({ role: "assistant", content: response });

  return response;
}

// Usage
const response = await getAIResponse(
  "What's the weather like?",
  "You are a helpful AI assistant named Groq. Answer questions clearly and concisely."
);
```

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

### WAV Stream Player for Web Audio API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

The WavStreamPlayer class manages low-level audio playback using Web Audio API AudioWorklets. It accepts 16-bit PCM audio data and streams it to the speakers, supporting interruption and track offset tracking. It requires the Web Audio API to be available in the browser.

```typescript
import { WavStreamPlayer } from '@shared/utils/wav-stream-player';

// Create player with sample rate matching your audio
const player = new WavStreamPlayer({ sampleRate: 48000 });

// Connect to audio context (required before playback)
await player.connect();

// Add 16-bit PCM audio data
const audioData = new Int16Array([/* PCM samples */]);
player.add16BitPCM(audioData, 'track-1');

// Or from ArrayBuffer
const buffer = new ArrayBuffer(1024);
player.add16BitPCM(buffer, 'track-1');

// Get current playback position
const offset = await player.getTrackSampleOffset();
console.log('Track ID:', offset.trackId);
console.log('Sample offset:', offset.offset);
console.log('Current time:', offset.currentTime, 'seconds');

// Interrupt playback and get current position
const interruptOffset = await player.interrupt();

// Set callback for when audio ends
player.setOnEndedCallback(() => {
  console.log('Playback ended');
});
```

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

### LLM Chat Completion API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

This section details how to use Groq's chat completion API to generate contextual AI responses. It supports multiple LLM models and maintains conversation history for coherent interactions.

```APIDOC
## LLM Chat Completion

### Description
This endpoint allows for chat-based interactions with AI models, leveraging conversation history to provide contextually relevant responses. It supports various Llama models.

### Method
POST (Implicitly through SDK)

### Endpoint
Groq Chat Completions API

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **messages** (Array<{ role: string; content: string }>) - Required - The conversation history, including the system prompt and user/assistant messages.
- **model** (string) - Required - The AI model to use (e.g., "meta-llama/llama-4-maverick-17b-128e-instruct").
- **temperature** (number) - Optional - Controls randomness (0.0 to 1.0).
- **max_tokens** (number) - Optional - Maximum number of tokens in the response.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
```json
{
  "messages": [
    {"role": "system", "content": "You are a helpful AI assistant named Groq."}, 
    {"role": "user", "content": "What's the weather like?"}
  ],
  "model": "meta-llama/llama-4-maverick-17b-128e-instruct",
  "temperature": 0.7,
  "max_tokens": 150,
  "stream": false
}
```

### Response
#### Success Response (200)
- **choices** (Array<{ message: { role: string; content: string } }>) - Description of the AI's response.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The weather is sunny today."
      }
    }
  ]
}
```
```

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

### Text-to-Speech Audio Generation with Groq PlayAI API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Streams Text-to-Speech (TTS) audio from Groq's PlayAI API. Supports 19 voices and streams audio in WAV format for real-time playback. Requires an API key and handles streaming audio chunks.

```typescript
// Stream TTS audio from Groq's PlayAI API
async function generateSpeech(text: string, apiKey: string, voice: string = "Arista-PlayAI"): Promise<void> {
  const response = await fetch(
    "https://api.groq.com/openai/v1/audio/speech",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "playai-tts",
        voice: voice, // Options: "Arista-PlayAI", "Atlas-PlayAI", "Basil-PlayAI", etc.
        input: text,
        response_format: "wav",
        speed: 1.0,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`TTS failed: ${response.statusText}`);
  }

  // Process streaming response
  const reader = response.body!.getReader();
  while (true) {
    const { value: chunk, done } = await reader.read();
    if (done) break;
    // Process audio chunk (add to TTSAudioBuffer for playback)
    ttsAudioBuffer.addChunk(chunk);
  }
  ttsAudioBuffer.flushBufferedData();
}

// Available TTS voices
const ttsVoices = [
  "Arista-PlayAI", "Atlas-PlayAI", "Basil-PlayAI", "Briggs-PlayAI",
  "Calum-PlayAI", "Celeste-PlayAI", "Cheyenne-PlayAI", "Chip-PlayAI",
  "Cillian-PlayAI", "Deedee-PlayAI", "Fritz-PlayAI", "Gail-PlayAI",
  "Indigo-PlayAI", "Mamaw-PlayAI", "Mason-PlayAI", "Mikail-PlayAI",
  "Mitch-PlayAI", "Quinn-PlayAI", "Thunder-PlayAI"
];
```

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

### Convert Float32Array Audio to WAV Blob

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Converts raw Float32Array audio data, typically from a VAD (Voice Activity Detection) process, into the WAV audio format. This is necessary for submitting audio data to APIs like Whisper that require specific audio encoding.

```typescript
// Convert Float32Array audio data to WAV blob
async function float32ArrayToWav(audio: Float32Array): Promise<Blob> {
  const sampleRate = 16000; // VAD outputs at 16kHz

  // Create buffer for WAV file
  const buffer = new ArrayBuffer(44 + audio.length * 2);
  const view = new DataView(buffer);

  // Helper to write string to DataView
  const writeString = (offset: number, str: string) => {
    for (let i = 0; i < str.length; i++) {
      view.setUint8(offset + i, str.charCodeAt(i));
    }
  };

  // Write WAV header
  writeString(0, 'RIFF');
  view.setUint32(4, 36 + audio.length * 2, true);
  writeString(8, 'WAVE');
  writeString(12, 'fmt ');
  view.setUint32(16, 16, true);           // Subchunk1 size
  view.setUint16(20, 1, true);            // Audio format (PCM)
  view.setUint16(22, 1, true);            // Num channels (mono)
  view.setUint32(24, sampleRate, true);   // Sample rate
  view.setUint32(28, sampleRate * 2, true); // Byte rate
  view.setUint16(32, 2, true);            // Block align
  view.setUint16(34, 16, true);           // Bits per sample
  writeString(36, 'data');
  view.setUint32(40, audio.length * 2, true);

  // Write audio samples
  for (let i = 0; i < audio.length; i++) {
    const sample = Math.max(-1, Math.min(1, audio[i]));
    const int16 = sample < 0 ? sample * 32768 : sample * 32767;
    view.setInt16(44 + i * 2, int16, true);
  }

  return new Blob([buffer], { type: 'audio/wav' });
}
```

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

### Text-to-Speech (TTS) Audio Generation API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

This section describes how to generate speech from text using Groq's PlayAI API. It supports streaming audio in WAV format and offers a variety of voices.

```APIDOC
## Text-to-Speech Audio Generation

### Description
This endpoint generates spoken audio from provided text using Groq's PlayAI TTS service. The audio is streamed in WAV format and supports multiple voices.

### Method
POST

### Endpoint
`https://api.groq.com/openai/v1/audio/speech`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The TTS model to use (e.g., "playai-tts").
- **voice** (string) - Required - The desired voice for the speech synthesis (e.g., "Arista-PlayAI").
- **input** (string) - Required - The text to convert to speech.
- **response_format** (string) - Optional - The format of the audio response (e.g., "wav"). Defaults to "wav".
- **speed** (number) - Optional - The speaking rate (e.g., 1.0 for normal speed).

### Request Example
```json
{
  "model": "playai-tts",
  "voice": "Arista-PlayAI",
  "input": "Hello, this is a test.",
  "response_format": "wav",
  "speed": 1.0
}
```

### Response
#### Success Response (200)
- **Audio Stream** (WAV format) - The generated speech audio.

#### Response Example
(Binary audio data stream)
```

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

### Voice Agent Flow Diagram Visualization with @xyflow/svelte

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

The VoiceAgentFlowDiagram component offers an interactive, node-based visualization of the voice processing pipeline using @xyflow/svelte. It displays real-time state transitions as audio data moves through the system. This component is designed to be used within a Svelte application.

```svelte
<script lang="ts">
  import VoiceAgentFlowDiagram from '@features/blueprints/svelteFlow/VoiceAgentFlowDiagram.svelte';

  let flowDiagramComponent: VoiceAgentFlowDiagram;
  let status = "Idle"; // "Idle" | "Listening" | "Recording" | "Processing" | "Responding"

  function handleDiagramStart() {
    status = "Listening";
    startRecordingWithVAD();
  }

  function handleDiagramStop(event: CustomEvent) {
    status = "Idle";
    stopConversation();
    // Force reset the diagram
    flowDiagramComponent?.forceReset();
  }

  function handleNodeClick(event: CustomEvent) {
    console.log('Node clicked:', event.detail.nodeId);
  }
</script>

<VoiceAgentFlowDiagram
  bind:this={flowDiagramComponent}
  height="400px"
  currentState={status}
  showWatermark={true}
  interactive={true}
  on:nodeClick={handleNodeClick}
  on:start={handleDiagramStart}
  on:stop={handleDiagramStop}
/>
```

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

### Transcribe Audio using Groq Whisper API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Provides a function to send an audio blob to Groq's Whisper API for speech-to-text transcription. It formats the audio as a WAV file and sends it via a POST request, including the API key for authentication. Error handling for the API response is included.

```typescript
// Send audio blob to Groq's Whisper API for transcription
async function transcribeAudio(audioBlob: Blob, apiKey: string): Promise<string> {
  const formData = new FormData();
  const audioFile = new File([audioBlob], "recording.wav", { type: "audio/wav" });
  formData.append("file", audioFile);
  formData.append("model", "whisper-large-v3-turbo");

  const response = await fetch(
    "https://api.groq.com/openai/v1/audio/transcriptions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
      body: formData,
    }
  );

  if (!response.ok) {
    const errorJson = await response.json();
    throw new Error(`Transcription failed: ${errorJson.error?.message}`);
  }

  const data = await response.json();
  return data.text; // Returns: "Hello, how are you today?"
}
```

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

### Speech-to-Text Transcription API

Source: https://context7.com/build-with-groq/groq-voice-agent-template/llms.txt

Details the process of sending audio data to Groq's Whisper API for transcription, including request formatting and error handling.

```APIDOC
## Speech-to-Text Transcription

### Description
Sends recorded audio (in WAV format) to Groq's Whisper API for transcription. Utilizes Voice Activity Detection (VAD) for audio capture.

### Method
`POST`

### Endpoint
`https://api.groq.com/openai/v1/audio/transcriptions`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (Blob) - Required - The audio file to transcribe (e.g., WAV format).
- **model** (string) - Required - The transcription model to use (e.g., `whisper-large-v3-turbo`).

### Request Example
```typescript
async function transcribeAudio(audioBlob: Blob, apiKey: string): Promise<string> {
  const formData = new FormData();
  const audioFile = new File([audioBlob], "recording.wav", { type: "audio/wav" });
  formData.append("file", audioFile);
  formData.append("model", "whisper-large-v3-turbo");

  const response = await fetch(
    "https://api.groq.com/openai/v1/audio/transcriptions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
      body: formData,
    }
  );

  if (!response.ok) {
    const errorJson = await response.json();
    throw new Error(`Transcription failed: ${errorJson.error?.message}`);
  }

  const data = await response.json();
  return data.text;
}
```

### Response
#### Success Response (200)
- **text** (string) - The transcribed text from the audio.

#### Response Example
```json
{
  "text": "Hello, how are you today?"
}
```

#### Error Response
- **error** (object)
  - **message** (string) - A message describing the error.
  - **type** (string) - The type of error.
  - **code** (string) - An error code.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.