agentscope-ai/agentscope · error · TypeError

Unsupported audio media type: {media_type}, only WAV and MP3

Error message

Unsupported audio media type: {media_type}, only WAV and MP3 audio are supported.

What it means

OpenAI audio input only supports WAV and MP3, so _format_audio_source maps media types (audio/wav, audio/mp3, audio/mpeg) to a format string and raises TypeError for anything else (e.g. audio/ogg, audio/webm, audio/flac). This is a provider limitation, not a generic validation error.

Source

Thrown at src/agentscope/formatter/_openai_formatter.py:146

        Local ``file://`` URLs are read from disk. Remote URLs are downloaded.
        Only ``wav`` and ``mp3`` formats are supported by the OpenAI API.

        Args:
            source (`URLSource | Base64Source`):
                The audio source to convert.

        Returns:
            `dict[str, Any]`:
                A dictionary with ``"type": "input_audio"`` in OpenAI format.
        """
        media_type_to_format = {
            "audio/wav": "wav",
            "audio/mp3": "mp3",
            "audio/mpeg": "mp3",
        }
        media_type = source.media_type
        if media_type not in media_type_to_format:
            raise TypeError(
                f"Unsupported audio media type: {media_type}, "
                "only WAV and MP3 audio are supported.",
            )
        audio_format = media_type_to_format[media_type]

        if isinstance(source, Base64Source):
            return {
                "type": "input_audio",
                "input_audio": {
                    "data": source.data,
                    "format": audio_format,
                },
            }

        if isinstance(source, URLSource):
            url_str = str(source.url)
            if url_str.startswith("file://"):
                # Local file

View on GitHub (pinned to e90f1c7592)

Solutions

Transcode the audio to WAV or MP3 (e.g. with ffmpeg: ffmpeg -i in.webm out.mp3) and set media_type to 'audio/mpeg' or 'audio/wav'
Ensure media_type is set correctly on Base64Source/URLSource — 'audio/mpeg' (not 'audio/mp3') is the standard MIME for MP3
If you must keep other formats, use the OpenAI Responses/Transcription APIs or another provider that accepts them

Example fix

# before
AudioBlock(source=Base64Source(data=b64, media_type="audio/webm"), alt="voice")

# after (transcode first: ffmpeg -i in.webm out.mp3)
AudioBlock(source=Base64Source(data=b64_mp3, media_type="audio/mpeg"), alt="voice")

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED = {"audio/wav", "audio/mp3", "audio/mpeg"}
assert source.media_type in SUPPORTED, f"{source.media_type} not supported by OpenAI audio input"

Type guard

def is_openai_audio_media_type(media_type: str | None) -> bool:
    return media_type in {"audio/wav", "audio/mp3", "audio/mpeg"}

Try / catch

try:
    formatter.format(msgs)
except TypeError as e:
    if "Unsupported audio media type" in str(e):
        audio = transcode_to_mp3(audio)  # e.g. ffmpeg
        ...  # rebuild block with media_type='audio/mpeg' and retry
    else:
        raise

Prevention

Transcode browser recordings (webm/ogg) to WAV or MP3 before sending
Use 'audio/mpeg' as the MIME type for MP3 files
Always set media_type explicitly on audio sources

When it happens

Trigger: Passing an AudioBlock whose source.media_type is e.g. 'audio/ogg', 'audio/webm' (common for browser MediaRecorder output), 'audio/m4a', or a missing/None media_type to the OpenAI formatter.

Common situations: Feeding browser-recorded webm/ogg audio straight to the API; converting voice notes to flac/m4a and assuming support; omitting media_type so it defaults to something unsupported.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/434ad6e3f387ba7e. Report an issue: GitHub.