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

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. 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. 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 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, 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, handling its unique word-level confidence and timestamp formats.

Concrete Provider Implementations

OpenAI Whisper

The OpenAI provider, located in 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 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. 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:

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:

{
  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 to enforce a consistent contract across all speech-to-text providers.
• Canonical types in 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 and 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}