skills/docs/media/audio/voice/README.md

@suaveplan/voice - Provider-agnostic voice core: abstract interfaces, shared types, Zod schemas, and structured errors for TTS, STT, voice management, sound effects, and voice isolation.

Summary

Provider-agnostic voice core for Suaveplan. Defines the abstract interfaces, shared types, Zod schemas, and structured error hierarchy that every voice provider adapter (@suaveplan/voice-elevenlabs, future -openai, -google, -azure, -polly) implements. This package contains zero provider-specific code, no HTTP, no API keys — it is the contract.

Documentation tree

• effects — The text-to-sound-effect engine interface for @suaveplan/voice. Defines the SoundEffectEngine contract every sound-…
  • effects — The text-to-sound-effect engine interface for @suaveplan/voice. Defines the SoundEffectEngine contract every sound-…
• errors — Stable error class hierarchy and code registry for @suaveplan/voice. Every typed error in this module extends `VoiceE…
  • errors — Stable error class hierarchy and code registry for @suaveplan/voice. Every typed error in this module extends `VoiceE…
• isolation — The voice-isolation engine interface for @suaveplan/voice. Defines the VoiceIsolationEngine contract every voice-is…
  • isolation — The voice-isolation engine interface for @suaveplan/voice. Defines the VoiceIsolationEngine contract every voice-is…
• stt — The speech-to-text (STT) engine interface for @suaveplan/voice. Defines the TranscriptionEngine contract every STT…
  • stt — The speech-to-text (STT) engine interface for @suaveplan/voice. Defines the TranscriptionEngine contract every STT…
• tts — The text-to-speech (TTS) engine interface for @suaveplan/voice. Defines the VoiceSynthesizer contract every TTS pro…
  • tts — The text-to-speech (TTS) engine interface for @suaveplan/voice. Defines the VoiceSynthesizer contract every TTS pro…
• types — Shared types and Zod schemas used by every voice engine interface in @suaveplan/voice. The module is the single sourc…
  • types — Shared types and Zod schemas used by every voice engine interface in @suaveplan/voice. The module is the single sourc…
• voices — The voice repository interface for @suaveplan/voice — read-only listing and lookup of voices available to the active…
  • voices — The voice repository interface for @suaveplan/voice — read-only listing and lookup of voices available to the active…

Install

bun add @suaveplan/voice

Quick start

Consume the contract via a provider adapter (here, ElevenLabs). The adapter is responsible for transport; this package owns the shape:

import type { VoiceSynthesizer } from "@suaveplan/voice";
import { createElevenLabsVoice } from "@suaveplan/voice-elevenlabs";

const { tts } = createElevenLabsVoice({ apiKey: process.env.ELEVENLABS_API_KEY! });

const synth: VoiceSynthesizer = tts;
const result = await synth.synthesize({
  text: "Hello, world.",
  voiceId: "21m00Tcm4TlvDq8ikWAM",
});
// result.audio is a Uint8Array, result.format is an AudioFormat

Modules

• errors/errors — VoiceError base class and 12 typed subclasses with stable VOICE.* codes.
• types/types — AudioFormat, Voice, VoiceSettings, WordTimestamp, SpeakerSegment, DetectedEntity and their Zod schemas.
• tts/tts — VoiceSynthesizer interface, SynthesisRequest, SynthesisResult.
• stt/stt — TranscriptionEngine interface, TranscriptionRequest, TranscriptionResult.
• voices/voices — VoiceRepository interface for listing and looking up voices.
• effects/effects — SoundEffectEngine interface for text-to-sound-effect generation.
• isolation/isolation — VoiceIsolationEngine interface for extracting a voice from mixed audio.

Design

@suaveplan/voice is a pure abstraction layer:

1. No transport. This package contains no fetch, no WebSocket, no retry logic, no rate-limit handling. Provider adapters own all of that.
2. No factories tied to providers. The package never knows which adapter is plugged in. Composition happens at the adapter site (createElevenLabsVoice, createOpenAIVoice, etc.).
3. One canonical type per concept. Voice, AudioFormat, WordTimestamp, SynthesisRequest, etc. — adapters map their native shapes onto these at the package boundary.
4. Stable error codes. Every adapter remaps its transport errors onto the 12 codes in VOICE_CODES. Callers branch on error.code or instanceof TtsSynthesisFailedError and never touch upstream details.
5. Zod schemas mirror every public type. Inputs validate at API boundaries; outputs validate when crossing process or service borders. AbortSignal and binary audio fields are excluded from schemas (they have no canonical encoding) and validate structurally at runtime.

Provider-specific extensions (voice cloning, conversational AI, music, dubbing, voice changing) ship in their own packages under separate abstractions when those domains stabilise across two or more vendors.