Adapt Voice¶

Adapt Voice — mvp.adapt_voice

Cluster: Creative & Media | Type: component | MCP Tools: 32

Overview¶

Text-to-speech and speech-to-text block that synthesises spoken audio from text via multiple TTS engines (edge-tts, pyttsx3, Coqui, espeak, ElevenLabs, OpenAI - with paid APIs gated behind an explicit opt-in flag) and transcribes audio back to text using faster-whisper or OpenAI STT. Also supports pitch shifting, speed adjustment, volume normalisation, trimming, concatenation, format conversion, and language detection. Audio is exchanged as base64-encoded bytes or file paths, making it composable with any other audio or media block.

When to use:

Synthesising voice narration from agent-generated text for podcast or video pipelines
Transcribing recorded audio or voice commands to text for downstream NLP processing
Applying pitch and speed modifications to generated speech to match a target voice profile
Converting spoken audio to a different format before archiving or streaming

Example:

from mvp.adapt_voice import AdaptVoiceBlock, VoiceInput

block = AdaptVoiceBlock(name="voice")
result = block.infer(VoiceInput(
    op="tts_speak",
    text="Hello from the G6 Hyperdistillation pipeline.",
    language="en",
    speed=1.0,
    output_format="wav",
))
# result.value.audio_base64 → synthesised speech as base64 WAV

Works well with: adapt_audio, adapt_ffmpeg, ctx_langextract

Launch Caveat¶

For first-user and pilot workflows, prefer one known-good path instead of presenting every backend as equally available. Use edge-tts for quick TTS demos and WAV inputs for built-in audio operations. Local STT requires faster-whisper; richer format conversion and media handling are best routed through adapt_audio or adapt_ffmpeg when their optional dependencies are installed.

OpenAI and ElevenLabs integrations are available only when their API keys are configured and allow_paid_api=True is set. Keep that opt-in explicit in tutorials, examples, and onboarding so a new user does not trigger paid API calls by accident.

Public API¶

`VoiceInput(BaseModel)`¶

Input for AdaptVoiceBlock.

Field	Type	Default
`op`	`Literal['tts_speak', 'tts_list_voices', 'tts_set_engine', 'stt_transcribe', 'stt_detect_language', 'pitch_shift', 'speed_change', 'volume_adjust', 'trim', 'concat', 'convert_format', 'get_duration', 'normalize', 'backend_capabilities', 'backend_probe', 'backend_op_schema', 'backend_validate', 'backend_execute']`	'tts_speak'
`text`	`str`	''
`audio_base64`	`str`	''
`audio_path`	`str`	''
`voice`	`str`	''
`engine`	`str`	''
`language`	`str`	'en'
`speed`	`float`	1.0
`pitch`	`float`	1.0
`volume`	`float`	1.0
`output_format`	`str`	'wav'
`profile_name`	`str`	''
`start_seconds`	`float`	0.0
`end_seconds`	`float`	0.0
`allow_paid_api`	`bool`	False
`backend_id`	`str`	''
`target_op`	`str`	''
`params`	`dict[str, Any]`	Field(default_factory=dict)
`dry_run`	`bool`	False
`allow_network`	`bool`	False
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`VoiceOutput(BaseModel)`¶

Output from AdaptVoiceBlock.

Field	Type	Default
`op`	`str`	required
`audio_base64`	`str`	''
`output_path`	`str`	''
`text`	`str`	''
`language`	`str`	''
`duration_seconds`	`float`	0.0
`engine`	`str`	''
`voice`	`str`	''
`confidence`	`float`	0.0
`backend`	`str`	''
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict[str, Any]`	Field(default_factory=dict)
`evidence`	`dict[str, Any]`	Field(default_factory=dict)
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`AdaptVoiceBlock(AIBlock[VoiceInput, VoiceOutput, None])`¶

Voice TTS/STT block with multi-engine fallback.

Field	Type	Default
`name`	`str`	'adapt_voice'
`resource_bounds`	`ResourceBounds \\| None`	None
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: VoiceInput) -> Result[VoiceOutput]`¶

`egress_plan(op: str, params: dict) -> 'list[EgressTarget] | None'`¶

`MCPVoiceInput(BaseModel)`¶

Input to AdaptVoiceMCPBlock — 27 ops (25 deterministic + 2 advisory).

Field	Type	Default
`op`	Literal['tts_speak', 'tts_list_voices', 'tts_set_engine', 'stt_transcribe', 'stt_detect_language', 'stt_set_engine', 'pitch_shift', 'speed_change', 'volume_adjust', 'trim', 'concat', 'convert_format', 'get_duration', 'normalize', 'voice_profile_save', 'voice_profile_list', 'voice_profile_delete', 'recording_save', 'recording_get', 'recording_list', 'recording_delete', 'batch_tts', 'batch_stt', 'stats', 'get_info', 'recommend_engine', 'list_patterns', 'backend_capabilities', 'backend_probe', 'backend_op_schema', 'backend_validate', 'backend_execute']	required
`text`	`str`	''
`audio_base64`	`str`	''
`audio_path`	`str`	''
`voice`	`str`	''
`engine`	`str`	''
`language`	`str`	'en'
`speed`	`float`	1.0
`pitch`	`float`	1.0
`volume`	`float`	1.0
`output_format`	`str`	'wav'
`start_seconds`	`float`	0.0
`end_seconds`	`float`	0.0
`profile_name`	`str`	''
`profile_settings`	`dict`	Field(default_factory=dict)
`recording_id`	`str`	''
`recording_name`	`str`	''
`tags_csv`	`str`	''
`notes`	`str`	''
`duration_seconds`	`float`	0.0
`texts`	`list[str]`	Field(default_factory=list)
`audio_items`	`list[str]`	Field(default_factory=list)
`limit`	`int`	50
`query`	`str`	''
`allow_paid_api`	`bool`	False
`allow_network`	`bool`	False
`backend_id`	`str`	''
`target_op`	`str`	''
`params`	`dict[str, Any]`	Field(default_factory=dict)
`dry_run`	`bool`	False
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''
`task`	`str`	''
`offline_required`	`bool`	False

`MCPVoiceOutput(BaseModel)`¶

Output from AdaptVoiceMCPBlock.

Field	Type	Default
`op`	`str`	required
`audio_base64`	`str`	''
`output_path`	`str`	''
`text`	`str`	''
`language`	`str`	''
`duration_seconds`	`float`	0.0
`engine`	`str`	''
`voice`	`str`	''
`confidence`	`float`	0.0
`backend`	`str`	''
`found`	`bool`	False
`count`	`int`	0
`records`	`list[dict]`	Field(default_factory=list)
`results`	`list[dict]`	Field(default_factory=list)
`message`	`str`	''
`metadata`	`dict`	Field(default_factory=dict)
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict[str, Any]`	Field(default_factory=dict)
`evidence`	`dict[str, Any]`	Field(default_factory=dict)
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`VoiceStore`¶

SQLite-backed store for the adapt_voice MCP sub-package.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`save_recording(name: str, audio_base64: str = '', text: str = '', engine: str = '', voice: str = '', language: str = '', duration_seconds: float = 0.0, tags: str = '', notes: str = '', metadata: dict | None = None) -> str`¶

Save a recording. Returns the assigned id.

`get_recording(recording_id: str) -> dict | None`¶

Get a recording by ID.

`list_recordings(tags_csv: str = '', limit: int = 50) -> list[dict]`¶

List recordings, optionally filtered by tags.

`delete_recording(recording_id: str) -> bool`¶

Delete a recording by ID. Returns True if it existed.

`save_profile(name: str, engine: str = '', voice: str = '', language: str = 'en', speed: float = 1.0, pitch: float = 1.0, volume: float = 1.0, output_format: str = 'wav', settings: dict | None = None) -> str`¶

Save or update a voice profile. Returns the assigned id.

`get_profile(name: str) -> dict | None`¶

Get a voice profile by name.

`list_profiles(limit: int = 50) -> list[dict]`¶

List all voice profiles.

`delete_profile(name: str) -> bool`¶

Delete a voice profile by name. Returns True if it existed.

`count_all() -> dict[str, int]`¶

Return row counts for all tables.

`close() -> None`¶

Close the SQLite connection so temp DB files can be removed on Windows.

MCP Tools¶

Operation	Source
`tts_speak`	voice_mcp
`tts_list_voices`	voice_mcp
`tts_set_engine`	voice_mcp
`stt_transcribe`	voice_mcp
`stt_detect_language`	voice_mcp
`stt_set_engine`	voice_mcp
`pitch_shift`	voice_mcp
`speed_change`	voice_mcp
`volume_adjust`	voice_mcp
`trim`	voice_mcp
`concat`	voice_mcp
`convert_format`	voice_mcp
`get_duration`	voice_mcp
`normalize`	voice_mcp
`voice_profile_save`	voice_mcp
`voice_profile_list`	voice_mcp
`voice_profile_delete`	voice_mcp
`recording_save`	voice_mcp
`recording_get`	voice_mcp
`recording_list`	voice_mcp
`recording_delete`	voice_mcp
`batch_tts`	voice_mcp
`batch_stt`	voice_mcp
`stats`	voice_mcp
`get_info`	voice_mcp
`recommend_engine`	voice_mcp
`list_patterns`	voice_mcp
`backend_capabilities`	voice_mcp
`backend_probe`	voice_mcp
`backend_op_schema`	voice_mcp
`backend_validate`	voice_mcp
`backend_execute`	voice_mcp

Adapt Voice¶

Overview¶

Launch Caveat¶

Public API¶

VoiceInput(BaseModel)¶

VoiceOutput(BaseModel)¶

AdaptVoiceBlock(AIBlock[VoiceInput, VoiceOutput, None])¶

infer(data: VoiceInput) -> Result[VoiceOutput]¶

egress_plan(op: str, params: dict) -> 'list[EgressTarget] | None'¶

MCPVoiceInput(BaseModel)¶

MCPVoiceOutput(BaseModel)¶

VoiceStore¶

save_recording(name: str, audio_base64: str = '', text: str = '', engine: str = '', voice: str = '', language: str = '', duration_seconds: float = 0.0, tags: str = '', notes: str = '', metadata: dict | None = None) -> str¶

get_recording(recording_id: str) -> dict | None¶

list_recordings(tags_csv: str = '', limit: int = 50) -> list[dict]¶

delete_recording(recording_id: str) -> bool¶

save_profile(name: str, engine: str = '', voice: str = '', language: str = 'en', speed: float = 1.0, pitch: float = 1.0, volume: float = 1.0, output_format: str = 'wav', settings: dict | None = None) -> str¶

get_profile(name: str) -> dict | None¶

list_profiles(limit: int = 50) -> list[dict]¶

delete_profile(name: str) -> bool¶

count_all() -> dict[str, int]¶

close() -> None¶