89 lines
5.6 KiB
Markdown
89 lines
5.6 KiB
Markdown
# @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.
|
|
|