babysor/MockingBird · error · ValueError

Either --voice-id or --reference-audio is required.

Error message

Either --voice-id or --reference-audio is required.

What it means

ValueError raised by synthesize() when neither voice_id nor reference_audio is supplied. The Noiz TTS backend needs either a preset voice identifier or an uploaded reference audio clip to know which voice to synthesize with.

Source

Thrown at skills/speak/scripts/noiz_tts.py:102

        data["similarity_enh"] = "true"
    if save_voice:
        data["save_voice"] = "true"
    if duration is not None:
        data["duration"] = str(duration)

    files = None
    if reference_audio:
        if not reference_audio.exists():
            raise FileNotFoundError(f"Reference audio not found: {reference_audio}")
        files = {
            "file": (
                reference_audio.name,
                reference_audio.open("rb"),
                "application/octet-stream",
            )
        }
    elif not voice_id:
        raise ValueError("Either --voice-id or --reference-audio is required.")

    try:
        resp = requests.post(
            url,
            headers={"Authorization": api_key},
            data=data,
            files=files,
            timeout=timeout,
        )
    finally:
        if files and files["file"][1]:
            files["file"][1].close()

    if resp.status_code != 200:
        raise RuntimeError(
            f"/text-to-speech failed: status={resp.status_code}, body={resp.text}"
        )

View on GitHub (pinned to 28dc5e14f1)

Solutions

  1. Pass a valid --voice-id from the service's voice list
  2. Or pass --reference-audio pointing to an existing audio file
  3. Check that environment-variable indirection for voice id is actually set (not empty string)

Example fix

# before
synthesize(..., voice_id=None, reference_audio=None)
# after
synthesize(..., voice_id=os.environ["NOIZ_VOICE_ID"], reference_audio=None)
Defensive patterns

Strategy: validation

Validate before calling

if not (voice_id or reference_audio):
    sys.exit('Either --voice-id or --reference-audio is required.')

Type guard

def has_voice_source(voice_id, reference_audio) -> bool:
    return bool(voice_id) or bool(reference_audio)

Try / catch

try:
    synthesize(...)
except ValueError as e:
    if 'required' in str(e):
        synthesize(..., voice_id=os.environ['NOIZ_VOICE_ID'])
    else:
        raise

Prevention

When it happens

Trigger: Calling synthesize(voice_id=None, reference_audio=None) — e.g. invoking the CLI with neither --voice-id nor --reference-audio.

Common situations: User assumes there is a default voice, or an env var/flag that was expected to supply the voice id is unset or empty string.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of babysor/MockingBird@28dc5e14f1 (2026-08-27). Data as JSON: /api/errors/ae7d44ebbdbc8bb6. Report an issue: GitHub.