# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
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:

```ts
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`](src/errors/errors.md) — `VoiceError` base class and 12 typed subclasses with stable `VOICE.*` codes.
- [`types/types`](src/types/types.md) — `AudioFormat`, `Voice`, `VoiceSettings`, `WordTimestamp`, `SpeakerSegment`, `DetectedEntity` and their Zod schemas.
- [`tts/tts`](src/tts/tts.md) — `VoiceSynthesizer` interface, `SynthesisRequest`, `SynthesisResult`.
- [`stt/stt`](src/stt/stt.md) — `TranscriptionEngine` interface, `TranscriptionRequest`, `TranscriptionResult`.
- [`voices/voices`](src/voices/voices.md) — `VoiceRepository` interface for listing and looking up voices.
- [`effects/effects`](src/effects/effects.md) — `SoundEffectEngine` interface for text-to-sound-effect generation.
- [`isolation/isolation`](src/isolation/isolation.md) — `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.