Node.js & Edge Runtime Support

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• package.json
• skills/speech-sdk/SKILL.md
• src/providers/google/index.ts
• src/index.ts
• skills/speech-sdk/references/result.md

The Speech SDK is a universal, lightweight TypeScript SDK designed for high-performance text-to-speech (TTS) operations across various JavaScript environments. It is architected as a "universal" library, providing consistent functionality and APIs whether running in traditional Node.js servers, modern Edge runtimes (like Vercel Edge Functions or Cloudflare Workers), or directly within the browser.

Sources: AGENTS.md:15-16, README.md:13-16, skills/speech-sdk/SKILL.md:10-11

Universal Architecture

The SDK's core architecture facilitates cross-platform support by maintaining zero runtime dependencies beyond p-retry. It utilizes standard web APIs such as fetch and ReadableStream to ensure compatibility across diverse environments.

Core Execution Flow

The SDK follows a unified execution path regardless of the host environment. The entry point generateSpeech() resolves the requested provider and model, executes the provider's specific logic, and returns a SpeechResult.

The diagram above shows the lifecycle of a speech generation request from initiation to environment-specific consumption.
Sources: AGENTS.md:15-22, README.md:143-151

Environment-Specific Implementation

The SDK provides patterns for handling audio data according to the capabilities of each supported runtime.

Node.js Support

In Node.js environments, the SDK is typically used for server-side generation where audio is written to the filesystem. The uint8Array property of the SpeechResult is used for these operations.
Sources: skills/speech-sdk/references/result.md:31-37

Edge Runtime Support

For Edge runtimes, the SDK leverages standard Web Response objects. The mediaType provided in the SpeechResult allows for setting appropriate headers in streaming or buffered responses.
Sources: skills/speech-sdk/references/result.md:39-43

Browser Support

In the browser, the SDK enables direct playback by converting the raw bytes into a Blob and a URL object.
Sources: skills/speech-sdk/references/result.md:45-48

Cross-Runtime Capability Matrix

Feature	Node.js	Edge Runtime	Browser	Implementation Source
Module System	ESM Only	ESM Only	ESM Only	package.json:6
HTTP Client	Global fetch	Native fetch	Native fetch	src/providers/google/index.ts:133
Streaming	ReadableStream	ReadableStream	ReadableStream	src/index.ts:28
Audio Format	Raw Bytes/WAV	Web Response	Blob/Audio API	skills/speech-sdk/references/result.md:31-48
Async Patterns	Async/Await	Async/Await	Async/Await	AGENTS.md:52

Technical Implementation Details

The SDK ensures compatibility through specific technical choices:

• ESM-Only Distribution: The package is configured as a native ES module ("type": "module"), which is the standard for modern Edge runtimes and Node.js.
• Lazy Computation: To optimize memory usage in resource-constrained environments like Edge workers, the base64 representation of audio is computed lazily only when accessed.
• Standard Web Streams: The streamSpeech() function returns a standard ReadableStream<Uint8Array>, which is natively supported by Edge runtimes for forwarding to HTTP responses.

Sources: package.json:6, AGENTS.md:39, skills/speech-sdk/references/result.md:29, README.md:104-106

Provider Integration Example (Google Gemini)

The GoogleSpeechProvider demonstrates environment-agnostic fetch handling by allowing a custom fetch implementation to be injected or falling back to the global globalThis.fetch.

export interface GoogleSpeechProviderConfig {
  apiKey?: string;
  baseURL?: string;
  fetch?: typeof globalThis.fetch;
}

// ... inside GoogleSpeechProvider constructor
this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);

Sources: src/providers/google/index.ts:32-36, src/providers/google/index.ts:133

Conclusion

The Speech SDK's "Universal" design philosophy eliminates the need for environment-specific polyfills or distinct libraries. By relying on modern standards like ESM and Web APIs (Fetch, Streams, Uint8Array), it provides a high-performance TTS interface that scales from localized Node.js scripts to global Edge deployments.