# Reported issues for Supertone TTS

Pod holds 16 of 19 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Supertone TTS](/mcp/supertone-tts).

## Most discussed

### merge_audio_files: crossfade_ms intermittently truncates short clips (acrossfade bug)

## Symptom
`crossfade_ms` is accurate on normal-length clips but intermittently truncates output on short / similar-length clips. E.g. `1.36s + 1.36s, cf=500` expected ~2.22s but produces ~0.86s (≈ one clip − crossfade) on a fraction of runs. Non-deterministic.

## Root cause (confirmed)
Intrinsic ffmpeg `acrossfade` bug on short inputs — reproduces even on raw inputs with no normalization/`aresample`. acrossfade's EOF/buffering occasionally drops one stream entirely. Results vary run-to-run (0.

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/53) · 2026-06-17 · closed · 0 comments

### merge_audio_files: WAV duration mis-reported (pipe:1 corrupts RIFF size header)

## Symptom
`merge_audio_files` with WAV output reports a wildly wrong `Duration` (e.g. `24347.9 seconds` for a real ~4.96s file). MP3 output is correct.

## Root cause (confirmed)
`audio_ops.merge_audio` renders to `pipe:1` (non-seekable). ffmpeg cannot rewind to patch the RIFF / `data` chunk size fields when writing WAV to a pipe, so it writes the placeholder `0xFFFFFFFF` (4294967295).

`tools.calculate_duration` (mutagen) then computes `4294967295 / (44100*2*2) ≈ 24347.887s` — exactly the repo

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/52) · 2026-06-17 · closed · 0 comments

### [ISSUE-031] Harden _pipe_format to reject unknown output formats (L1)

## Goal
Make `audio_ops._pipe_format` fail loudly on an unknown output format instead of silently mapping anything non-`wav` to `mp3`.

## Background (review finding L1, from PR #49)
`_pipe_format` returns `"wav" if output_format == "wav" else "mp3"`. Today `output_format` is enum-validated upstream (`SUPPORTED_FORMATS`), so there's no current bug. But `MERGE_SUPPORTED_EXTENSIONS` exists specifically "so the merge surface can diverge later" — if a third format is added there, `_pipe_format` woul

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/51) · 2026-06-16 · open · 0 comments

### [ISSUE-030] Real-ffmpeg integration test tier for merge_audio_files (RL-007)

## Goal
Add an opt-in (CI-skipped) real-ffmpeg integration test tier for `merge_audio_files`, so the filter-graph / parameter-compatibility contract is pinned by a test that actually runs the bundled ffmpeg — not just the mocked unit tests.

## Background (review lesson RL-007, from PR #49)
`tests/test_audio_ops.py` mocks `asyncio.create_subprocess_exec`, so it validates the **command string** but never ffmpeg's actual behavior. The C1/C2 filter-graph bug in PR #49 (concat/aevalsrc parameter mis

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/50) · 2026-06-16 · open · 0 comments

### [ISSUE-029] Add merge_audio_files tool (ffmpeg-backed audio concatenation)

## Goal
Add a `merge_audio_files` MCP tool backed by a bundled ffmpeg binary that concatenates two or more audio files produced by `text_to_speech` into a single deliverable, supporting head-to-tail concat, silence-gap insertion, and crossfade blending.

Spec: docs/specs/SPEC-029.md (Option A — bundle ffmpeg via imageio-ffmpeg).

## Scope
**In:** new `src/supertone_mcp/audio_ops.py` (async ffmpeg subprocess); `merge_audio_files` handler in `tools.py`; registration in `server.py`; `imageio-ffmpeg

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/48) · 2026-06-16 · closed · 0 comments

### [ISSUE-027] New usage tools get_usage_history + get_voice_usage

## Goal
Two new MCP tools expose usage data:
- `get_usage_history()` wraps `usage.get_usage_async` (advanced analytics; time-bucketed).
- `get_voice_usage(voice_id)` reports usage for a single voice.

Each returns a formatted plain-text usage summary.

## Scope (In)
- New `SupertoneClient.get_usage_history(...)` and `SupertoneClient.get_voice_usage(...)` methods.
- Two tool handlers + formatters in tools.py.
- server.py registration for both.
- Empty-voice_id validation for get_voice_usage.
- Te

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/43) · 2026-06-05 · closed · 0 comments

### [ISSUE-026] New tool get_custom_voice

Closes via PR for ISSUE-026.

## Goal
A new `get_custom_voice(voice_id)` tool returns the detail of a single custom (cloned) voice by wrapping `custom_voices.get_custom_voice_async`, with empty-voice_id validation.

## Scope
In: New `async get_custom_voice(voice_id)` method on SupertoneClient wrapping `custom_voices.get_custom_voice_async`; new `async get_custom_voice(voice_id) -> str` tool handler + `format_custom_voice_detail(...)` formatter in tools.py; server.py registration; empty voice_id 

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/41) · 2026-06-05 · closed · 0 comments

### [ISSUE-025] Expose include_phonemes + normalized_text TTS params

## Goal
`text_to_speech` exposes the SDK 0.2.3 `include_phonemes` (bool, default false) and `normalized_text` (str, optional) parameters, passing them through to the client/SDK, with `normalized_text` documented as effective only for `sona_speech_2`/`sona_speech_2_flash`.

## Scope
- In: Add `include_phonemes: bool = False` and `normalized_text: str | None = None` to `tools.text_to_speech`, `client.synthesize` and `synthesize_stream`, and `server.py` registration/docstrings; pass both through to

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/39) · 2026-06-05 · closed · 0 comments

## Most recent

### [ISSUE-024] Relax 300-char hard limit → delegate to SDK auto-chunk

## Goal
`text_to_speech` and `predict_duration` no longer hard-reject text over 300 characters; long text is delegated to the SDK's internal auto-chunking, while empty-text validation is retained.

## Scope
**In:** Remove the `validate_text_max_length` hard rejection from `predict_duration` (confirm `text_to_speech` does not call it); keep `validate_text` (non-empty); update `text_to_speech` and `predict_duration` tool descriptions/docstrings to note long text is auto-chunked and credit/latency 

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/37) · 2026-06-05 · closed · 0 comments

### [ISSUE-023] Add streaming param + route synthesize vs stream + sona_speech_1-only validation

Closes-tracking for ISSUE-023.

## Goal
`text_to_speech` accepts a per-call `streaming` parameter (default false) that routes to one-shot `client.synthesize` by default and to `client.synthesize_stream` when true, with fail-fast validation rejecting `streaming=true` for any model other than `sona_speech_1` before any SDK call.

## Scope
In: add `streaming: bool = False` to tools.text_to_speech + server.py registration/docstring; wire the one-shot `client.synthesize()` path through existing outpu

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/35) · 2026-06-05 · closed · 0 comments

### [ISSUE-022] Remove behavior env vars → per-call output_mode/autoplay (BREAKING)

## Goal
`text_to_speech` decides output mode and autoplay per call via new `output_mode` and `autoplay` parameters; the env vars `SUPERTONE_MCP_OUTPUT_MODE` and `SUPERTONE_MCP_AUTOPLAY` are no longer read; `autoplay` defaults to `false`. BREAKING.

## Scope
In: Add `output_mode` (str, default `files`) and `autoplay` (bool, default `false`) params to `tools.text_to_speech` and `server.py` registration + docstrings; replace `resolve_output_mode()` env read with `validate_output_mode(mode)` against

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/33) · 2026-06-05 · closed · 0 comments

### [ISSUE-021] SDK 0.2.3 sync: model enum + default + version pin

## Goal
constants.SUPPORTED_MODELS matches the SDK 0.2.3 model enum (all 7 models), the default model is sona_speech_2_flash, and the supertone dependency is pinned to >=0.2.3,<0.3.

## Scope
In: Add sona_speech_3t and supertonic_api_3 to SUPPORTED_MODELS and the Model Literal in constants.py; change DEFAULT_MODEL from sona_speech_1 to sona_speech_2_flash; pin supertone>=0.2.3,<0.3 in pyproject.toml; update validate_model tests; correct the stale text_to_speech docstring in server.py.
Out: strea

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/31) · 2026-06-05 · closed · 0 comments

### ISSUE-020: Custom voice CRUD tools (search/edit/delete)

Tracking issue for ISSUE-020 (FR-018, FR-019, US-011). See issues.md ISSUE-020 for full spec. Implemented in PR #23.

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/24) · 2026-05-27 · closed · 0 comments

### [ISSUE-019] Add clone_voice tool (single file ≤3MB)

## Goal
`clone_voice(name, audio_path, description?)` creates a custom (cloned) voice from a local audio file (WAV or MP3, ≤3MB) and returns the new custom voice ID.

## Scope
- In: New `async create_cloned_voice(name, audio_bytes, file_name, content_type, description?) -> dict` method on `SupertoneClient` wrapping `custom_voices.create_cloned_voice_async`; new `async clone_voice(name, audio_path, description?) -> str` tool handler that reads the file, validates extension/size, builds the SDK `F

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/21) · 2026-05-27 · closed · 0 comments

### [ISSUE-018] Add predict_duration tool (client + handler)

Closes: tracked in `issues.md` ISSUE-018

## Goal
`predict_duration(text, voice_id?, language?, model?, output_format?, speed?, pitch_shift?, style?)` calls the Supertone duration prediction API and returns the predicted audio length in seconds, which is proportional to credit consumption.

## Scope (In/Out)
**In:**
- New `async predict_duration(...)` method on `SupertoneClient` wrapping `text_to_speech.predict_duration_async`
- New `async predict_duration(...)` tool handler in `tools.py`
- Vali

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/19) · 2026-05-27 · closed · 0 comments

### [ISSUE-017] Add preview_voice tool (returns sample URLs)

## Goal
\`preview_voice(voice_id, language?, style?, model?)\` returns matching sample audio URLs from the voice's \`samples\` array so users (or the client) can listen to a preview before choosing a voice.

## Scope
**In:**
- \`async preview_voice(voice_id, language?, style?, model?) -> str\` handler in \`tools.py\`
- New \`format_voice_samples(samples, filters) -> str\` formatter
- Server registration in \`server.py\`
- Tests in \`tests/test_tools.py\` and \`tests/test_server.py\`

**Out:**
- 

[Read the thread](https://github.com/supertone-inc/supertone-mcp/issues/17) · 2026-05-27 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/supertone-inc/supertone-mcp/issues).