chenhg5/cc-connect · error

ffmpeg opus conversion failed: %w (stderr: %s)

Error message

ffmpeg opus conversion failed: %w (stderr: %s)

What it means

ConvertAudioToOpus runs ffmpeg as a subprocess and, if cmd.Run() returns an error, wraps it together with the captured stderr. The wrap message distinguishes this runtime failure from the missing-binary case: ffmpeg was found and executed but the opus conversion failed. The stderr text is the key diagnostic — it holds ffmpeg's own parse/codec errors.

Source

Thrown at core/speech.go:361

// Returns the opus bytes. If ffmpeg is not installed, returns an error.
func ConvertAudioToOpus(ctx context.Context, audio []byte, srcFormat string) ([]byte, error) {
	ffmpegPath, err := exec.LookPath("ffmpeg")
	if err != nil {
		return nil, fmt.Errorf("ffmpeg not found in PATH: install ffmpeg to enable audio conversion")
	}

	args := []string{"-i", "pipe:0", "-c:a", "libopus", "-f", "opus", "-y", "pipe:1"}
	if srcFormat == "amr" || srcFormat == "silk" {
		args = append([]string{"-f", srcFormat}, args...)
	}
	cmd := exec.CommandContext(ctx, ffmpegPath, args...)
	cmd.Stdin = bytes.NewReader(audio)
	var stdout, stderr bytes.Buffer
	cmd.Stdout = &stdout
	cmd.Stderr = &stderr

	if err := cmd.Run(); err != nil {
		return nil, fmt.Errorf("ffmpeg opus conversion failed: %w (stderr: %s)", err, stderr.String())
	}
	return stdout.Bytes(), nil
}

// ConvertAudioToAMR uses ffmpeg to convert audio to AMR-NB format.
// AMR is a common voice codec for mobile messaging platforms.
// Returns the AMR bytes. If ffmpeg is not installed, returns an error.
func ConvertAudioToAMR(ctx context.Context, audio []byte, srcFormat string) ([]byte, error) {
	ffmpegPath, err := exec.LookPath("ffmpeg")
	if err != nil {
		return nil, fmt.Errorf("ffmpeg not found in PATH: install ffmpeg to enable audio conversion")
	}

	args := []string{
		"-i", "pipe:0",
		"-c:a", "amr_nb",
		"-ar", "8000",   // 8kHz sample rate (AMR-NB standard)
		"-ac", "1",      // mono

View on GitHub (pinned to 4000b2338a)

Solutions

  1. Inspect the stderr in the error message — it names the failing stage (Input/Output error, Unknown encoder 'libopus', etc.).
  2. If it says libopus is unknown, install a full ffmpeg build that includes libopus.
  3. Confirm srcFormat matches the actual input codec; fix the format detection on the caller side.
  4. If caused by ctx cancellation, raise the timeout; if input is empty or truncated, re-fetch or reject the file.

Example fix

// before
opus, err := core.ConvertAudioToOpus(ctx, voiceBytes, "amr")
// after
if !bytes.HasPrefix(voiceBytes, []byte("#!AMR")) {
    return fmt.Errorf("expected AMR payload, got different format")
}
opus, err := core.ConvertAudioToOpus(ctx, voiceBytes, "amr")
Defensive patterns

Strategy: try-catch

Validate before calling

if len(audio) == 0 {
    return fmt.Errorf("empty audio payload")
}

Try / catch

opus, err := core.ConvertAudioToOpus(ctx, audio, srcFormat)
if err != nil {
    log.Error("opus conversion failed", "stderr", extractStderr(err), "format", srcFormat)
    return fmt.Errorf("send voice note: %w", err)
}

Prevention

When it happens

Trigger: SendAudio (or a direct call) passes audio bytes ffmpeg cannot decode or cannot encode to libopus: corrupt/truncated input, srcFormat mislabeled (e.g. bytes declared "amr" that are actually wav), empty input, ffmpeg build without libopus encoder, or ctx cancellation killing the process mid-run.

Common situations: Platform delivers an unusual voice codec the local ffmpeg lacks a decoder for; a stripped ffmpeg build (e.g. libavcodec without libopus); context deadline too short for long voice notes; user uploads a corrupted file.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/8c24c48222fa4023. Report an issue: GitHub.