fallback-api

Fallback Audio Streaming API

A framework-agnostic TypeScript library for streaming audio responses from a fallback REST API with automatic retry and exponential backoff polling. Supports Opus audio format at 24kHz for efficient, high-quality audio streaming.

Features

• 🎵 Opus Audio Streaming: Stream Opus-encoded audio chunks in real-time (24kHz, mono)
• 🔄 Exponential Backoff Polling: Automatically retry failed requests with smart polling intervals
• ⚡ Streaming Callbacks: Receive data as it arrives with onChunkReceived callback
• 🎯 Chunk-based Processing: Handle audio and transcription data chunk by chunk
• 💪 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🏥 Health Checks: Built-in health check service before making requests
• 🎙️ Audio Playback: Optional AudioStreamQueue for seamless audio playback
• ⏸️ Cancellation: Support for AbortSignal to cancel ongoing requests
• 🎧 Automatic Opus Decoding: Opus audio is automatically decoded to PCM for Web Audio API playback

Installation

npm install fallback-api

Quick Start

Basic Usage - FallbackService

import { FallbackService } from 'fallback-api';

const service = new FallbackService({
  baseUrl: 'https://your-api.example.com',
  healthCheckTimeout: 5000,
});

const response = await service.execute({
  sessionId: 'user-session-123',
  userQuery: 0,
  audioChunkNumber: 0,
});

if (response.success) {
  console.log('Audio Data:', response.audioData);
  console.log('Transcription:', response.transcription);
}

Streaming Data with Callbacks

const response = await service.execute({
  sessionId: 'user-session-123',
  userQuery: 0,
  audioChunkNumber: 0,
  onChunkReceived: (chunk) => {
    if (chunk.transcription) {
      console.log('Transcription:', chunk.transcription);
    }
    if (chunk.audioData) {
      console.log('Audio chunk received:', chunk.chunkNumber);
    }
  },
});

With Cancellation Support

const controller = new AbortController();

const response = await service.execute({
  sessionId: 'user-session-123',
  userQuery: 0,
  audioChunkNumber: 0,
  abortSignal: controller.signal,
});

// Cancel the request if needed
// controller.abort();

Audio Playback - AudioStreamQueue

import { AudioStreamQueue } from 'fallback-api';

const audioQueue = new AudioStreamQueue(
  {
    sampleRate: 24000,
    channels: 1,
    bitDepth: 16,
  },
  {
    onChunkStart: (chunkIndex, remaining) => {
      console.log(`Playing chunk ${chunkIndex}, ${remaining} remaining`);
    },
    onChunkEnd: (chunkIndex) => {
      console.log(`Finished chunk ${chunkIndex}`);
    },
    onQueueEmpty: () => {
      console.log('Playback complete');
    },
    onError: (error) => {
      console.error('Playback error:', error);
    },
  }
);

// Enqueue audio chunks (base64-encoded PCM data)
audioQueue.enqueue(audioChunk1);
audioQueue.enqueue(audioChunk2);

// Control playback
audioQueue.setMuted(true);  // Mute audio
audioQueue.stop();          // Stop and clear queue

API Reference

FallbackService

Constructor

new FallbackService(config: FallbackConfig)

Config Options:

• baseUrl (string, required): Base URL of the fallback API
• healthCheckTimeout (number, optional): Timeout for health checks in ms (default: 5000)
• pollingIntervals (number[], optional): Polling intervals for exponential backoff (default: [0, 2000, 4000, 8000, 16000, 32000, 64000])
• maxPollingCalls (number, optional): Maximum polling attempts (default: 50)

Methods

execute(request: FallbackRequest): Promise<FallbackResponse>

Execute a request to the fallback API.

Request Options:

• sessionId (string, required): Session identifier
• userQuery (number, required): Query number (0-indexed)
• audioChunkNumber (number, required): Starting chunk number
• abortSignal (AbortSignal, optional): Signal for cancellation
• onChunkReceived (callback, optional): Callback for streaming chunks
• skipThinkingMessage (boolean, optional): Skip the thinking message phase

Response:

• success (boolean): Whether the request succeeded
• audioData (string, optional): Base64-encoded audio
• transcription (string, optional): Text transcription
• sessionId (string): Session ID from request
• isEnd (boolean): Whether response is complete
• error (string, optional): Error message if failed

AudioStreamQueue

Constructor

new AudioStreamQueue(config?: AudioStreamConfig, callbacks?: AudioQueueCallbacks)

Config:

• sampleRate (number): Audio sample rate in Hz (default: 24000)
• channels (number): Number of audio channels (default: 1)
• bitDepth (number): Audio bit depth (default: 16)

Callbacks:

• onChunkStart(chunkIndex, remainingInQueue): When chunk starts playing
• onChunkEnd(chunkIndex): When chunk finishes
• onQueueEmpty(): When all chunks are played
• onError(error): On playback errors

Methods

• enqueue(base64Audio: string): Add audio to playback queue
• setMuted(muted: boolean): Mute/unmute playback
• stop(): Stop playback and clear queue
• get queueSize(): number: Get number of pending chunks

Complete Example

import { FallbackService, AudioStreamQueue } from 'fallback-api';

// Initialize service
const service = new FallbackService({
  baseUrl: 'https://your-api.example.com',
});

// Initialize audio queue
const audioQueue = new AudioStreamQueue(
  { sampleRate: 24000, channels: 1, bitDepth: 16 },
  {
    onChunkStart: (idx) => console.log(`Playing chunk ${idx}`),
    onQueueEmpty: () => console.log('Done playing'),
    onError: (err) => console.error('Playback failed:', err),
  }
);

// Execute request with streaming
const response = await service.execute({
  sessionId: 'session-123',
  userQuery: 0,
  audioChunkNumber: 0,
  onChunkReceived: (chunk) => {
    if (chunk.audioData) {
      audioQueue.enqueue(chunk.audioData);
    }
    if (chunk.transcription) {
      console.log('Transcription:', chunk.transcription);
    }
  },
});

console.log('Final result:', response);

Error Handling

try {
  const response = await service.execute(request);
  
  if (!response.success) {
    console.error('Request failed:', response.error);
  }
} catch (error) {
  console.error('Service error:', error);
}

TypeScript Support

All types are exported for full type-safety:

import type {
  FallbackConfig,
  FallbackRequest,
  FallbackResponse,
  ChunkData,
  AudioStreamConfig,
  AudioQueueCallbacks,
} from 'fallback-api';

Browser & Node.js Support

This library works in both:

• Node.js: For server-side audio processing
• Browsers: For client-side streaming and playback
• React/Vue/Angular: Framework-agnostic, works with any framework

How It Works

• Health Check: Before making requests, the service checks the API's health
• Exponential Backoff: Implements smart polling with exponential backoff intervals
• Streaming: Chunks are sent to the onChunkReceived callback as they arrive
• Audio Playback: Optional AudioStreamQueue handles WAV conversion and playback

Logging

The library provides minimal logging to help with debugging:

• Request payloads are logged when received
• Audio chunk indices are logged during playback

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.