# How Audio.Transcription Enables Speech-to-Text Across Providers in AISuite

> Discover how Audio.Transcription in AISuite unifies speech-to-text across providers with a single interface. Normalize requests and responses for seamless ASR integration.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-07-30

---

**AISuite unifies speech-to-text (ASR) behind a single Audio.Transcription interface by normalizing requests and responses through provider-specific adapters while enforcing a common ASRProvider contract.**

The `andrewyng/aisuite` library abstracts the complexity of integrating multiple automatic speech recognition (ASR) services through its **Audio.Transcription** API. By implementing a provider-agnostic architecture, AISuite allows developers to switch between Whisper, Deepgram, and other engines without refactoring application code. This article examines the source code to reveal how the library normalizes disparate provider SDKs behind a unified transcription interface.

## The Unified Type System

All ASR interactions in AISuite revolve around two canonical types defined in **[`src/types/transcription.ts`](https://github.com/andrewyng/aisuite/blob/main/src/types/transcription.ts)**. The `TranscriptionRequest` interface captures common parameters such as `model`, `file`, `language`, and `timestamps`, while the `TranscriptionResult` interface standardizes the output shape with `text`, `language`, `confidence`, `words`, and `segments` properties.

This type system ensures that every provider, regardless of underlying SDK differences, consumes and produces the same data structures. By mandating these types at the boundary, AISuite eliminates vendor-specific payload variations from reaching consumer code.

## The ASRProvider Contract

Every speech-to-text implementation must satisfy the `ASRProvider` interface declared in **[`src/core/base-asr-provider.ts`](https://github.com/andrewyng/aisuite/blob/main/src/core/base-asr-provider.ts)**. This contract requires three specific methods:

- **`transcribe(request, options?)`**: The core execution method that performs the ASR operation.
- **`validateParams(request)`**: Validates incoming parameters against provider-specific constraints.
- **`translateParams(request)`**: Transforms the generic `TranscriptionRequest` into a format the provider’s SDK expects.

By enforcing this interface, AISuite guarantees that any class registered as an ASR provider can be invoked interchangeably through the same surface area.

## Provider Registration and Discovery

The library maintains a provider registry in **[`src/asr-providers/index.ts`](https://github.com/andrewyng/aisuite/blob/main/src/asr-providers/index.ts)** that maps provider name strings to concrete class implementations. AISuite identifies the correct provider at runtime by parsing the `model` field of the request, which follows the convention `"<provider>:<modelName>"` (for example, `"openai:whisper-1"` or `"deepgram:general"`).

When `client.transcribe()` is called, the system extracts the provider prefix, retrieves the corresponding class from the registry, and instantiates it with the appropriate API credentials supplied during client initialization.

## Adapter Pattern for Cross-Provider Compatibility

Provider-specific SDKs use incompatible payload structures, so AISuite employs adapter functions to bridge the gap. Each provider implements two adapters:

- **Request adapter**: Converts the generic `TranscriptionRequest` into the provider’s native SDK parameters.
- **Response adapter**: Maps the provider’s raw JSON response into the standardized `TranscriptionResult`.

For example, in **[`src/providers/openai/adapters.ts`](https://github.com/andrewyng/aisuite/blob/main/src/providers/openai/adapters.ts)**, the `adaptASRRequest` function translates AISuite’s request format into the OpenAI SDK’s `audio.transcriptions.create` parameters, while `adaptASRResponse` normalizes the `OpenAI.Audio.Transcription` response into the common result shape. Deepgram implements analogous logic in **[`src/asr-providers/deepgram/adapters.ts`](https://github.com/andrewyng/aisuite/blob/main/src/asr-providers/deepgram/adapters.ts)**, handling its unique word-level confidence and timestamp formats.

## Concrete Provider Implementations

### OpenAI Whisper

The OpenAI provider, located in **[`src/providers/openai/provider.ts`](https://github.com/andrewyng/aisuite/blob/main/src/providers/openai/provider.ts)**, implements the `ASRProvider` interface by wrapping the official OpenAI SDK. Its `transcribe` method first calls `translateParams` to adapt the request, then invokes `client.audio.transcriptions.create` with the transformed payload. After receiving the `OpenAIASRResponse`, it passes the result through `adaptASRResponse` to return a normalized `TranscriptionResult`.

### Deepgram

The Deepgram implementation in **[`src/asr-providers/deepgram/provider.ts`](https://github.com/andrewyng/aisuite/blob/main/src/asr-providers/deepgram/provider.ts)** follows the same contract but uses Deepgram’s HTTP client rather than a high-level SDK wrapper. It adapts the request payload to match Deepgram’s query parameters and JSON body expectations, executes the HTTP call, then transforms the Deepgram-specific JSON response—complete with its nested `results.channel.alternatives` structure—into the standard `TranscriptionResult` format.

## The Client Facade

The high-level API exposed to developers lives in **[`src/client.ts`](https://github.com/andrewyng/aisuite/blob/main/src/client.ts)**. The `AISuiteClient` class exposes a `transcribe(request)` method that orchestrates the entire workflow:

1. Parses the `model` string to determine the provider name.
2. Retrieves the provider instance from the internal registry.
3. Invokes `validateParams` to ensure the request meets the provider’s requirements.
4. Delegates execution to the provider’s `transcribe` method.
5. Returns the normalized `TranscriptionResult` directly to the caller.

This facade hides the complexity of provider instantiation, adapter selection, and error handling behind a single method call.

## Complete Usage Example

The following example demonstrates switching between OpenAI and Deepgram without changing application logic:

```typescript
import { AISuiteClient } from "aisuite-js";
import fs from "fs";

const client = new AISuiteClient({
  openai: { apiKey: process.env.OPENAI_KEY },
  deepgram: { apiKey: process.env.DEEPGRAM_KEY },
});

// OpenAI Whisper
const openaiResult = await client.transcribe({
  model: "openai:whisper-1",
  file: fs.readFileSync("audio.mp3"),
  language: "en",
  timestamps: true,
});

// Deepgram
const deepgramResult = await client.transcribe({
  model: "deepgram:general",
  file: fs.readFileSync("audio.wav"),
  language: "en",
  word_confidence: true,
});

```

Both calls return identical `TranscriptionResult` objects:

```typescript
{
  text: "Hello world, this is a test transcription.",
  language: "en",
  confidence: 0.95,
  words: [
    { text: "Hello", start: 0.0, end: 0.5, confidence: 0.98 },
    { text: "world", start: 0.5, end: 0.9, confidence: 0.96 }
  ],
  segments: [
    { text: "Hello world, this is a test transcription.", start: 0.0, end: 3.2 }
  ]
}

```

## Summary

- **Audio.Transcription** in AISuite relies on the `ASRProvider` interface in [`src/core/base-asr-provider.ts`](https://github.com/andrewyng/aisuite/blob/main/src/core/base-asr-provider.ts) to enforce a consistent contract across all speech-to-text providers.
- **Canonical types** in [`src/types/transcription.ts`](https://github.com/andrewyng/aisuite/blob/main/src/types/transcription.ts) normalize request parameters and response shapes, insulating application code from vendor-specific formats.
- **Provider adapters** in directories like [`src/providers/openai/adapters.ts`](https://github.com/andrewyng/aisuite/blob/main/src/providers/openai/adapters.ts) and [`src/asr-providers/deepgram/adapters.ts`](https://github.com/andrewyng/aisuite/blob/main/src/asr-providers/deepgram/adapters.ts) handle the bidirectional translation between AISuite’s generic types and provider-native SDK calls.
- **The client facade** in [`src/client.ts`](https://github.com/andrewyng/aisuite/blob/main/src/client.ts) orchestrates provider lookup, validation, and execution based on the `"provider:model"` string convention.
- **Zero-code migration** between providers like OpenAI and Deepgram is possible because all implementations return the standardized `TranscriptionResult` structure.

## Frequently Asked Questions

### What is the Audio.Transcription interface in AISuite?

The **Audio.Transcription** interface refers to the collective API surface—including `TranscriptionRequest`, `TranscriptionResult`, and the `ASRProvider` contract—that enables speech-to-text operations. It defines how audio files are submitted and how transcription results are returned, regardless of which underlying ASR service (Whisper, Deepgram, etc.) processes the audio.

### How does AISuite handle different ASR provider formats?

AISuite uses an **adapter pattern** where each provider implements specific request and response adapter functions. These adapters translate the generic `TranscriptionRequest` into provider-specific SDK parameters and convert the provider’s raw response into the standardized `TranscriptionResult` format, ensuring consistent output across services.

### What model string format does AISuite use for transcription?

AISuite uses the format `"<provider>:<modelName>"` to identify both the ASR provider and the specific model to invoke. For example, `"openai:whisper-1"` routes the request to the OpenAI provider using the Whisper model, while `"deepgram:general"` routes to Deepgram’s general transcription model. The `Client` class parses this string to select the appropriate provider implementation.

### Where does AISuite validate transcription parameters?

Parameter validation occurs within each concrete provider’s `validateParams` method, which is defined as part of the `ASRProvider` interface in [`src/core/base-asr-provider.ts`](https://github.com/andrewyng/aisuite/blob/main/src/core/base-asr-provider.ts). The `Client` class invokes this method immediately before executing the transcription, ensuring that provider-specific constraints (such as supported audio formats or language codes) are checked before the network request is made.