Adapt Audio¶

Adapt Audio — mvp.adapt_audio

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

Overview¶

Production audio processing component with 62 core ops across 9 domains and a 6-tier dependency system with graceful degradation to stdlib WAV when heavy deps are unavailable. Covers format conversion, editing, effects, analysis, mixing, mastering, critical listening, post-production, live sound, Sonic Pi live coding, local Splice sample helpers, and prompt-to-music forwards. Uses 7 backend modules (librosa, pydub, professional, mixing, dynamics, analysis, postprod) with a stdlib fallback for basic ops.

When to use:

Full audio editing pipeline: trim, normalize, effects, EQ, compression, limiting
Multi-track mixing with per-track volume/pan and stereo width control
Mastering chains: spectral matching, multiband compression, limiting, dither
Critical listening: A/B reference comparisons, spectral analysis, phase correlation
Post-production: dialogue normalization, source separation, de-reverb, room tone extraction
Live sound: feedback detection, time alignment, proximity compensation

Example:

import base64
from mvp.adapt_audio import AdaptAudioBlock, AudioInput

# Load your audio as base64 (e.g. b64_data = base64.b64encode(open("clip.wav", "rb").read()).decode())
b64_data = base64.b64encode(b"\x00" * 4410).decode()  # placeholder: 0.1s of silence

block = AdaptAudioBlock()
result = block.infer(AudioInput(op="noise_reduce", audio_base64=b64_data))
# result.value → AudioOutput with processed audio (or degraded=True if noisereduce not installed)

Works well with: adapt_voice, adapt_ffmpeg, adapt_synth

Architecture¶

adapt_audio/
├── schema.py                # Tier 1: AudioInput / AudioOutput (62 ops)
├── audio_block.py           # Tier 1: AdaptAudioBlock — tiered dispatcher
├── deps.py                  # Dependency tier system (0-5) + runtime checks
├── backends/
│   ├── librosa_be.py        # analysis/metadata/resample/pitch
│   ├── pydub_be.py          # editing/effects/generation
│   ├── professional_be.py   # noise_reduce/loudness (noisereduce/pyloudnorm)
│   ├── mixing_be.py         # multi-track mix/pan/width/mid-side/gain staging
│   ├── dynamics_be.py       # parametric EQ/compression/limiting/dither
│   ├── analysis_be.py       # spectral compare/A-B reference/masking/phase
│   └── postprod_be.py       # dialogue norm/room tone/source sep/de-reverb/live sound
└── audio_mcp/               # Tier 2: MCP sub-package (84 public MCP tools)
    ├── schema.py            # MCPAudioInput / MCPAudioOutput
    ├── store.py             # AudioStore — SQLite + file persistence
    ├── audio_block.py       # AdaptAudioMCPBlock — 81-op internal dispatcher
    └── server.py            # FastMCP tools + singleton wiring

Dependency Tiers¶

Tier	Name	Packages	Ops
0	stdlib	wave, struct, io	get_metadata, get_duration, generate_tone, trim, split_channels
1	numpy+soundfile	numpy, soundfile	waveform_data, dynamic_compress, mixing ops, noise_gate, brickwall_limit, dither, phase_correlation, crest_factor, feedback_detect, time_align, phase_align
2	pydub+scipy	pydub, scipy	editing (trim, concat, mix, effects, fade, reverse, convert), crossfade, EQ/dynamics (parametric_eq, shelving, graphic_eq, multiband/sidechain compress, de_esser), dialogue_normalize
3	librosa	librosa	resample, spectral_analysis, pitch_detect, bpm_detect, audio_classify, silence_detect, spectrogram_data, pitch_shift, auto_segment, spectral_match, mastering_chain, critical listening, room_tone_extract, de_reverb
4	professional	noisereduce, pyloudnorm	noise_reduce, loudness_normalize, loudness_measure
5	ml	demucs	source_separate

When a tier is unavailable, the block returns a degraded response with degraded=True and a pip install hint.

Public API¶

`AdaptAudioBlock(AIBlock[AudioInput, AudioOutput, None])`¶

Multi-backend audio processing block.

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

Methods:

`infer(data: AudioInput) -> Result[AudioOutput]`¶

`deps_check() -> dict`¶

Return dependency tier status for all tiers.

`AudioInput(BaseModel)`¶

Input for AdaptAudioBlock.

Field	Type	Default
`op`	Literal['convert_format', 'trim', 'concat', 'mix', 'adjust_volume', 'apply_effect', 'split_channels', 'get_metadata', 'get_duration', 'normalize', 'fade_in', 'fade_out', 'reverse', 'resample', 'generate_tone', 'generate_silence', 'spectral_analysis', 'pitch_detect', 'bpm_detect', 'audio_classify', 'silence_detect', 'waveform_data', 'spectrogram_data', 'noise_reduce', 'loudness_normalize', 'loudness_measure', 'dynamic_compress', 'crossfade', 'eq', 'pitch_shift', 'auto_segment', 'multi_track_mix', 'stereo_pan', 'stereo_width', 'auto_gain_stage', 'mid_side', 'parametric_eq', 'shelving_filter', 'graphic_eq', 'multiband_compress', 'sidechain_compress', 'de_esser', 'noise_gate', 'brickwall_limit', 'dither', 'spectral_match', 'mastering_chain', 'spectral_compare', 'ab_reference', 'frequency_masking', 'phase_correlation', 'crest_factor', 'dialogue_normalize', 'room_tone_extract', 'source_separate', 'noise_profile', 'de_reverb', 'feedback_detect', 'notch_filter', 'time_align', 'proximity_compensate', 'phase_align', 'ops', 'help', 'discover_capabilities', 'dependency_health', 'backend_native_op', 'create_preview', 'compare_preview', 'record_human_review', 'apply_recipe', 'sonic_pi_check', 'sonic_pi_eval', 'sonic_pi_stop', 'sonic_pi_run_file', 'sonic_pi_record', 'sonic_pi_compose']	'get_metadata'
`audio_base64`	`str`	''
`audio_path`	`str`	''
`format`	`str`	'wav'
`second_audio_base64`	`str`	''
`reference_audio_base64`	`str`	''
`start_seconds`	`float`	0.0
`end_seconds`	`float`	0.0
`duration_seconds`	`float`	1.0
`volume`	`float`	1.0
`sample_rate`	`int`	0
`channels`	`int`	0
`effect`	`str`	''
`frequency`	`float`	440.0
`n_fft`	`int`	2048
`threshold_db`	`float`	-40.0
`min_silence_ms`	`int`	500
`num_points`	`int`	1000
`target_lufs`	`float`	-14.0
`prop_decrease`	`float`	1.0
`semitones`	`float`	0.0
`ratio`	`float`	4.0
`attack_ms`	`float`	5.0
`release_ms`	`float`	50.0
`hold_ms`	`float`	10.0
`range_db`	`float`	-80.0
`gain_db`	`float`	0.0
`q`	`float`	1.0
`reduction_db`	`float`	-6.0
`crossfade_ms`	`int`	100
`pan`	`float`	0.0
`width`	`float`	1.0
`target_peak_db`	`float`	-6.0
`mid_side_mode`	`str`	''
`volumes_json`	`str`	''
`pans_json`	`str`	''
`ceiling_db`	`float`	-0.3
`bit_depth`	`int`	16
`noise_shaping`	`bool`	True
`strength`	`float`	0.8
`dither_bits`	`int`	16
`bands_json`	`str`	''
`band_gains_json`	`str`	''
`filter_type`	`str`	''
`stems`	`str`	''
`noise_profile_json`	`str`	''
`mode`	`str`	''
`true_peak_dbtp`	`float`	-1.0
`distance_cm`	`float`	15.0
`compensation_db`	`float`	-6.0
`max_shift_ms`	`float`	50.0
`audio_list`	`list[str]`	[]
`sonic_pi_code`	`str`	''
`sonic_pi_host`	`str`	'127.0.0.1'
`sonic_pi_cmd_port`	`int`	4557
`sonic_pi_file`	`str`	''
`sonic_pi_description`	`str`	''
`sonic_pi_output_path`	`str`	''
`backend_operation`	`str`	''
`backend_parameters_json`	`str`	''
`dry_run`	`bool`	True
`preview_id`	`str`	''
`recipe_json`	`str`	''
`reviewer`	`str`	''
`review_notes`	`str`	''
`approved`	`bool`	False
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`AudioOutput(BaseModel)`¶

Output from AdaptAudioBlock.

Field	Type	Default
`op`	`str`	required
`audio_base64`	`str`	''
`output_path`	`str`	''
`format`	`str`	''
`duration_seconds`	`float`	0.0
`sample_rate`	`int`	0
`channels`	`int`	0
`size_bytes`	`int`	0
`backend`	`str`	''
`metadata`	`dict[str, Any]`	{}
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`available_with`	`str`	''
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict[str, Any]`	{}
`evidence`	`dict[str, Any]`	{}
`degradation`	`dict[str, Any]`	{}
`dependency_health`	`dict[str, Any]`	{}
`objective_metrics`	`dict[str, Any]`	{}
`human_listening_required`	`bool`	False
`listening_checklist`	`list[str]`	[]
`subjective_judgement_limits`	`str`	''
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`AdaptAudioMCPBlock(AIBlock[MCPAudioInput, MCPAudioOutput, dict])`¶

79-op internal audio MCP block with SQLite persistence (_all_ops()).

Field	Type	Default
`name`	`str`	'adapt_audio_mcp'
`state`	`dict`	field(default_factory=dict)
`db_path`	`str`	field(default_factory=lambda: os.environ.get('AUDIO_DB_PATH', _DEFAULT_DB))
`resource_bounds`	`ResourceBounds`	field(default_factory=ResourceBounds)
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)

Methods:

`infer(data: MCPAudioInput) -> Result[MCPAudioOutput]`¶

`MCPAudioInput(BaseModel)`¶

Input to AdaptAudioMCPBlock -- 81 ops (op Literal).

Field	Type	Default
`op`	Literal['convert_format', 'trim', 'concat', 'mix', 'adjust_volume', 'apply_effect', 'split_channels', 'get_metadata', 'get_duration', 'normalize', 'fade_in', 'fade_out', 'reverse', 'resample', 'generate_tone', 'generate_silence', 'save', 'load', 'list', 'delete', 'batch_convert', 'merge', 'list_formats', 'stats', 'get_info', 'spectral_analysis', 'pitch_detect', 'bpm_detect', 'audio_classify', 'silence_detect', 'waveform_data', 'spectrogram_data', 'noise_reduce', 'loudness_normalize', 'loudness_measure', 'dynamic_compress', 'crossfade', 'eq', 'pitch_shift', 'auto_segment', 'multi_track_mix', 'stereo_pan', 'stereo_width', 'auto_gain_stage', 'mid_side', 'parametric_eq', 'shelving_filter', 'graphic_eq', 'multiband_compress', 'sidechain_compress', 'de_esser', 'noise_gate', 'brickwall_limit', 'dither', 'spectral_match', 'mastering_chain', 'spectral_compare', 'ab_reference', 'frequency_masking', 'phase_correlation', 'crest_factor', 'dialogue_normalize', 'room_tone_extract', 'source_separate', 'noise_profile', 'de_reverb', 'feedback_detect', 'notch_filter', 'time_align', 'proximity_compensate', 'phase_align', 'ops', 'help', 'discover_capabilities', 'dependency_health', 'backend_native_op', 'create_preview', 'compare_preview', 'record_human_review', 'apply_recipe', 'sonic_pi_check', 'sonic_pi_eval', 'sonic_pi_stop', 'sonic_pi_run_file', 'sonic_pi_record', 'sonic_pi_compose', 'recommend_chain', 'list_patterns']	required
`audio_base64`	`str`	''
`audio_path`	`str`	''
`format`	`str`	'wav'
`second_audio_base64`	`str`	''
`start_seconds`	`float`	0.0
`end_seconds`	`float`	0.0
`volume`	`float`	1.0
`sample_rate`	`int`	0
`channels`	`int`	0
`effect`	`str`	''
`frequency`	`float`	440.0
`duration_seconds`	`float`	1.0
`name`	`str`	''
`tags_csv`	`str`	''
`notes`	`str`	''
`limit`	`int`	50
`target_format`	`str`	'wav'
`audio_list`	`list[str]`	[]
`query`	`str`	''
`reference_audio_base64`	`str`	''
`n_fft`	`int`	2048
`threshold_db`	`float`	-40.0
`min_silence_ms`	`int`	500
`num_points`	`int`	1000
`target_lufs`	`float`	-14.0
`prop_decrease`	`float`	1.0
`semitones`	`float`	0.0
`ratio`	`float`	4.0
`attack_ms`	`float`	5.0
`release_ms`	`float`	50.0
`hold_ms`	`float`	10.0
`range_db`	`float`	-80.0
`gain_db`	`float`	0.0
`q`	`float`	1.0
`reduction_db`	`float`	-6.0
`crossfade_ms`	`int`	100
`pan`	`float`	0.0
`width`	`float`	1.0
`target_peak_db`	`float`	-6.0
`mid_side_mode`	`str`	''
`volumes_json`	`str`	''
`pans_json`	`str`	''
`ceiling_db`	`float`	-0.3
`bit_depth`	`int`	16
`noise_shaping`	`bool`	True
`strength`	`float`	0.8
`dither_bits`	`int`	16
`bands_json`	`str`	''
`band_gains_json`	`str`	''
`filter_type`	`str`	''
`stems`	`str`	''
`noise_profile_json`	`str`	''
`mode`	`str`	''
`true_peak_dbtp`	`float`	-1.0
`distance_cm`	`float`	15.0
`compensation_db`	`float`	-6.0
`max_shift_ms`	`float`	50.0
`sonic_pi_code`	`str`	''
`sonic_pi_host`	`str`	'127.0.0.1'
`sonic_pi_cmd_port`	`int`	4557
`sonic_pi_file`	`str`	''
`sonic_pi_description`	`str`	''
`sonic_pi_output_path`	`str`	''
`brief`	`str`	''
`context_text`	`str`	''
`backend_operation`	`str`	''
`backend_parameters_json`	`str`	''
`dry_run`	`bool`	True
`preview_id`	`str`	''
`recipe_json`	`str`	''
`reviewer`	`str`	''
`review_notes`	`str`	''
`approved`	`bool`	False
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''

`MCPAudioOutput(BaseModel)`¶

Output from AdaptAudioMCPBlock.

Field	Type	Default
`op`	`str`	required
`audio_base64`	`str`	''
`output_path`	`str`	''
`format`	`str`	''
`duration_seconds`	`float`	0.0
`sample_rate`	`int`	0
`channels`	`int`	0
`size_bytes`	`int`	0
`backend`	`str`	''
`metadata`	`dict[str, Any]`	{}
`name`	`str`	''
`found`	`bool`	False
`count`	`int`	0
`records`	`list[dict[str, Any]]`	[]
`message`	`str`	''
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`available_with`	`str`	''
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict[str, Any]`	{}
`evidence`	`dict[str, Any]`	{}
`degradation`	`dict[str, Any]`	{}
`dependency_health`	`dict[str, Any]`	{}
`objective_metrics`	`dict[str, Any]`	{}
`human_listening_required`	`bool`	False
`listening_checklist`	`list[str]`	[]
`subjective_judgement_limits`	`str`	''
`request_id`	`str`	''
`task_id`	`str`	''
`run_id`	`str`	''
`recommendation`	`dict[str, Any]`	{}
`llm_used`	`bool`	False

`AudioStore`¶

File-backed store for the adapt_audio MCP sub-package.

Constructor:

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

Methods:

`close() -> None`¶

`save_audio(name: str, audio_bytes: bytes, fmt: str = 'wav', duration_seconds: float = 0.0, sample_rate: int = 0, channels: int = 0, size_bytes: int = 0, tags: str = '', notes: str = '', metadata: dict | None = None) -> str`¶

Persist a named audio file. Writes file to disk, metadata to SQLite.

`load_audio(name: str) -> dict[str, Any] | None`¶

Retrieve a stored audio file by name. Returns None if not found.

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

List stored audio files (metadata only, no file data).

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

Delete a stored audio file. Removes both DB row and file on disk.

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

`total_size() -> int`¶

`total_duration() -> float`¶

Functions¶

`tier_available(tier: int) -> bool`¶

Check if all packages for the given tier are importable.

`deps_check() -> dict`¶

Return full tier status for all tiers and CLI tools.

MCP Tools¶

Operation	Source
`convert_format`	audio_mcp
`trim`	audio_mcp
`concat`	audio_mcp
`mix`	audio_mcp
`adjust_volume`	audio_mcp
`apply_effect`	audio_mcp
`split_channels`	audio_mcp
`get_metadata`	audio_mcp
`get_duration`	audio_mcp
`normalize`	audio_mcp
`fade_in`	audio_mcp
`fade_out`	audio_mcp
`reverse`	audio_mcp
`resample`	audio_mcp
`generate_tone`	audio_mcp
`generate_silence`	audio_mcp
`save`	audio_mcp
`load`	audio_mcp
`list`	audio_mcp
`delete`	audio_mcp
`batch_convert`	audio_mcp
`merge`	audio_mcp
`list_formats`	audio_mcp
`stats`	audio_mcp
`get_info`	audio_mcp
`spectral_analysis`	audio_mcp
`pitch_detect`	audio_mcp
`bpm_detect`	audio_mcp
`audio_classify`	audio_mcp
`silence_detect`	audio_mcp
`waveform_data`	audio_mcp
`spectrogram_data`	audio_mcp
`noise_reduce`	audio_mcp
`loudness_normalize`	audio_mcp
`loudness_measure`	audio_mcp
`dynamic_compress`	audio_mcp
`crossfade`	audio_mcp
`eq`	audio_mcp
`pitch_shift`	audio_mcp
`auto_segment`	audio_mcp
`multi_track_mix`	audio_mcp
`stereo_pan`	audio_mcp
`stereo_width`	audio_mcp
`auto_gain_stage`	audio_mcp
`mid_side`	audio_mcp
`parametric_eq`	audio_mcp
`shelving_filter`	audio_mcp
`graphic_eq`	audio_mcp
`multiband_compress`	audio_mcp
`sidechain_compress`	audio_mcp
`de_esser`	audio_mcp
`noise_gate`	audio_mcp
`brickwall_limit`	audio_mcp
`dither`	audio_mcp
`spectral_match`	audio_mcp
`mastering_chain`	audio_mcp
`spectral_compare`	audio_mcp
`ab_reference`	audio_mcp
`frequency_masking`	audio_mcp
`phase_correlation`	audio_mcp
`crest_factor`	audio_mcp
`dialogue_normalize`	audio_mcp
`room_tone_extract`	audio_mcp
`source_separate`	audio_mcp
`noise_profile`	audio_mcp
`de_reverb`	audio_mcp
`feedback_detect`	audio_mcp
`notch_filter`	audio_mcp
`time_align`	audio_mcp
`proximity_compensate`	audio_mcp
`phase_align`	audio_mcp
`ops`	audio_mcp
`help`	audio_mcp
`discover_capabilities`	audio_mcp
`dependency_health`	audio_mcp
`backend_native_op`	audio_mcp
`create_preview`	audio_mcp
`compare_preview`	audio_mcp
`record_human_review`	audio_mcp
`apply_recipe`	audio_mcp
`sonic_pi_check`	audio_mcp
`sonic_pi_eval`	audio_mcp
`sonic_pi_stop`	audio_mcp
`sonic_pi_run_file`	audio_mcp
`sonic_pi_record`	audio_mcp
`sonic_pi_compose`	audio_mcp
`recommend_chain`	audio_mcp
`list_patterns`	audio_mcp

Adapt Audio¶

Overview¶

Architecture¶

Dependency Tiers¶

Public API¶

AdaptAudioBlock(AIBlock[AudioInput, AudioOutput, None])¶

infer(data: AudioInput) -> Result[AudioOutput]¶

deps_check() -> dict¶

AudioInput(BaseModel)¶

AudioOutput(BaseModel)¶

AdaptAudioMCPBlock(AIBlock[MCPAudioInput, MCPAudioOutput, dict])¶

infer(data: MCPAudioInput) -> Result[MCPAudioOutput]¶

MCPAudioInput(BaseModel)¶

MCPAudioOutput(BaseModel)¶

AudioStore¶

close() -> None¶

save_audio(name: str, audio_bytes: bytes, fmt: str = 'wav', duration_seconds: float = 0.0, sample_rate: int = 0, channels: int = 0, size_bytes: int = 0, tags: str = '', notes: str = '', metadata: dict | None = None) -> str¶

load_audio(name: str) -> dict[str, Any] | None¶

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

delete_audio(name: str) -> bool¶

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

total_size() -> int¶

total_duration() -> float¶

Functions¶

tier_available(tier: int) -> bool¶

deps_check() -> dict¶

MCP Tools¶

`AdaptAudioBlock(AIBlock[AudioInput, AudioOutput, None])`¶

`infer(data: AudioInput) -> Result[AudioOutput]`¶

`deps_check() -> dict`¶

`AudioInput(BaseModel)`¶

`AudioOutput(BaseModel)`¶

`AdaptAudioMCPBlock(AIBlock[MCPAudioInput, MCPAudioOutput, dict])`¶

`infer(data: MCPAudioInput) -> Result[MCPAudioOutput]`¶

`MCPAudioInput(BaseModel)`¶

`MCPAudioOutput(BaseModel)`¶

`AudioStore`¶

`close() -> None`¶

`save_audio(name: str, audio_bytes: bytes, fmt: str = 'wav', duration_seconds: float = 0.0, sample_rate: int = 0, channels: int = 0, size_bytes: int = 0, tags: str = '', notes: str = '', metadata: dict | None = None) -> str`¶

`load_audio(name: str) -> dict[str, Any] | None`¶

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

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

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

`total_size() -> int`¶

`total_duration() -> float`¶

`tier_available(tier: int) -> bool`¶

`deps_check() -> dict`¶