Summary

Detect and surface ffmpeg failures via exit code checking.

• Affects:FFmpegPCMAudio,FFmpegOpusAudio (via FFmpegAudio base),AudioPlayer
• Changes:
  • Added_raise_if_process_failed() method to check ffmpeg exit codes
  • Call error check inFFmpeg*Audio.read() when stream ends unexpectedly
  • AddedAudioPlayer.error andAudioPlayer.has_failed properties for error inspection
  • UpdatedFFmpegPCMAudio docstring to document runtime error behavior

Behavioral impact:

• Previously, ffmpeg failures (including missing files) would silently result in no audio playback
• Now, ffmpeg failures raiseClientException with exit code information during playback
• Users can checkAudioPlayer.has_failed andAudioPlayer.error to inspect playback failures

If applicable, link issue(s):

• Fixes:nextcord.FFmpegPCMAudio does not throw FileNotFoundError #1229

Initial Approach (Revised - see below)

Reproduction and verification

Minimal example:

importnextcorddefafter_playback(error):iferror:print(f"Playback failed:{error}")# Missing file will cause ffmpeg to exit with errorsource=nextcord.FFmpegPCMAudio("non-existent-file.m4a")voice_client.play(source,after=after_playback)# Or check during/after playback:ifvoice_client._player.has_failed:print(f"Error:{voice_client._player.error}")

Expected:ClientException raised during.read() when ffmpeg exits with non-zero status, error accessible via AudioPlayer properties.

Additional notes:

• This approach is more robust than path validation - it catches all ffmpeg failures, not just missing files
• Error detection happens at the point of failure (during read) rather than construction
• BothFFmpegPCMAudio andFFmpegOpusAudio benefit from this error handling

This is a Code Change

• I have tested my changes.
• I have updated the documentation to reflect the changes.
• I have runtask pyright and fixed the relevant issues.

Tooling status

• Lint/format: PASS (task lint)
• Typecheck: PASS (poetry run python -m pyright → 0 errors)
• Slotscheck: PASS (task slotscheck)
• Syntax/build: PASS (Poetry install / compile succeeded)

Risk assessment

Low. Changes improve error visibility by detecting actual ffmpeg failures rather than attempting flaky proactive validation. Error information is now accessible to users via clean API.