iflytek/astron-agent · error · BusinessException

AUDIO_CHANNELS_INVALID

AUDIO_CHANNELS_INVALID

Error message

AUDIO_CHANNELS_INVALID

What it means

BusinessException(ResponseEnum.AUDIO_CHANNELS_INVALID) thrown by getAudioFormat when the AudioFormat's channel count does not equal REQUIRED_CHANNELS (mono, 1). The service requires single-channel audio, so stereo or multichannel files are rejected during format extraction.

Solutions

  1. Downmix to mono with ffmpeg: ffmpeg -i stereo.wav -ac 1 mono.wav.
  2. Set the recorder to single-channel/mono capture before recording.
  3. Re-export from the audio editor with channels = 1 (mono).
  4. Verify the source file is genuinely mono — use ffprobe to check 'Channels: 1'.

Example fix

// before: stereo file rejected
upload(voice_stereo.wav)
// after: convert to mono
// ffmpeg -i voice_stereo.wav -ac 1 voice_mono.wav
upload(voice_mono.wav)
Defensive patterns

Strategy: validation

Validate before calling

// check channels before upload via WebAudio or ffprobe
// ffprobe -v error -show_entries stream=channels -of csv=p=0 file.wav  -> expect 1

Try / catch

try { AudioValidator.validateAudioProperties(file); }
catch (BusinessException e) { if (ResponseEnum.AUDIO_CHANNELS_INVALID.equals(e.getResponseEnum())) { /* 400: request mono downmix */ } else { throw e; } }

Prevention

When it happens

Trigger: Uploading a stereo (2-channel) or 5.1 WAV/PCM file to the endpoint whose validateAudioProperties path calls getAudioFormat; happens as soon as the stream's format is read, before sample-rate and bit-depth checks.

Common situations: Recordings from DAWs or phone mics defaulting to stereo; music tracks (almost always stereo) uploaded instead of voice clips; USB audio interfaces capturing 2 channels; converted files that kept the original channel layout.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/ed18e554eac239b0. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/commons/src/main/java/com/iflytek/astron/console/commons/util/AudioValidator.java:137

            // Check duration (within 40 seconds)
            long frameLength = audioInputStream.getFrameLength();
            float frameRate = format.getFrameRate();
            if (frameRate > 0) {
                float durationSeconds = frameLength / frameRate;
                if (durationSeconds > MAX_DURATION_SECONDS) {
                    throw new BusinessException(ResponseEnum.AUDIO_DURATION_TOO_LONG);
                }
            }
        }
    }

    @NotNull
    private static AudioFormat getAudioFormat(AudioInputStream audioInputStream) {
        AudioFormat format = audioInputStream.getFormat();

        // Check number of channels (mono)
        if (format.getChannels() != REQUIRED_CHANNELS) {
            throw new BusinessException(ResponseEnum.AUDIO_CHANNELS_INVALID);
        }

        // Check sample rate (24kHz and above)
        if (format.getSampleRate() < MIN_SAMPLE_RATE) {
            throw new BusinessException(ResponseEnum.AUDIO_SAMPLE_RATE_TOO_LOW);
        }

        // Check bit depth (16bit)
        if (format.getSampleSizeInBits() != REQUIRED_SAMPLE_SIZE) {
            throw new BusinessException(ResponseEnum.AUDIO_BIT_DEPTH_INVALID);
        }
        return format;
    }

    /**
     * Validate basic properties for MP3 and M4A formats
     */
    private static void validateMp3M4aBasic(MultipartFile file) throws BusinessException {

View on GitHub (pinned to 5e758547a8)