first commit
This commit is contained in:
88
docs/media/audio/voice/README.md
Normal file
88
docs/media/audio/voice/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# @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.
|
||||
|
||||
Reference in New Issue
Block a user