本文介绍通过 python-mpv 的日志回调机制捕获流媒体 url 解析/连接错误，并将其转换为可捕获的异常，从而实现对无效电台链接、网络中断等场景的可靠错误处理。
本文介绍通过 python-mpv 的日志回调机制捕获流媒体 url 解析/连接错误，并将其转换为可捕获的异常，从而实现对无效电台链接、网络中断等场景的可靠错误处理。
python-mpv 是一个轻量但功能强大的 Python 绑定库，用于控制底层 mpv 播放器。然而，其 player.play() 方法是异步非阻塞的：调用后立即返回，不等待资源加载完成；因此，直接在 play() 外层套用 try...except 无法捕获 URL 解析失败、DNS 错误、连接超时或 HTTP 404 等流层面的错误——这些错误实际由 mpv 内部线程在后续加载过程中触发，并通过日志系统（log）输出。
真正的解决方案是利用 MPV 构造时的 log_handler 参数，注册自定义日志处理器，监听 component='stream' 且 loglevel='error' 的关键错误消息。mpv 在无法打开流时（如无效域名、端口拒绝、路径不存在、协议不支持等），会统一通过 stream 组件输出结构化错误日志，例如：
Failed to recognize file format. Could not connect to server. Unable to open URI: http://...
以下是一个生产就绪的错误处理示例：
import mpv
class StreamURLError(Exception):
"""专用于捕获 mpv 流媒体 URL 加载失败的异常"""
pass
def log_handler(loglevel, component, message):
# 仅当 stream 组件报告 error 级别日志时触发异常
if loglevel == 'error' and component == 'stream':
raise StreamURLError(f"Stream error: {message.strip()}")
# 初始化播放器，启用日志回调
player = mpv.MPV(
log_handler=log_handler,
# 可选：禁用视频以节省资源（纯音频流场景）
video=False,
# 可选：设置较短的超时，加速失败响应（单位：秒）
stream_lavf_probe_options="timeout=5000000"
)
try:
player.play('http://51.89.148.171xxx:8022/stream') # 故意构造的非法 URL
player.wait_for_playback() # 阻塞直到播放结束或出错终止
except StreamURLError as e:
print(f"❌ 流媒体加载失败：{e}")
except KeyboardInterrupt:
print("\n⏹ 用户中断播放")
finally:
player.terminate() # 推荐显式释放资源（比 del 更可靠）⚠️ 重要注意事项：
立即学习“Python免费学习笔记（深入）”；
- log_handler 中抛出的异常不会被 play() 或 wait_for_playback() 直接捕获，而是由 mpv 内部线程触发，并最终导致 wait_for_playback() 抛出该异常（前提是播放未成功进入缓冲/解码状态）；
- 若 URL 实际可连接但后续流数据中断（如电台断播），mpv 可能持续重试而不报错；此时建议结合 idle 状态监听或 time-pos 超时检测做二次判断；
- del player 并不能保证及时清理底层资源，应优先调用 player.terminate()；
- 对于高可用电台客户端，建议在捕获 StreamURLError 后执行退避重试（如指数退避）或自动切换备用源。
通过该模式，你可将不可控的底层流错误转化为清晰、可测试、可监控的 Python 异常，大幅提升音频流应用的健壮性与用户体验。
