mpv libmpv 客户端 API 兼容性指南版本编号机制、兼容策略与破坏性变更全记录【免费下载链接】mpv Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv本篇基于 mpv 仓库的 DOCS/client-api-changes.rst 展开系统讲解 libmpvclient.h客户端 C API 的版本编号规则major/minor bump 策略、ABI 兼容承诺以及从 1.0API 宣布稳定到当前 2.5 的全部破坏性变更历史。读完后你将能够正确做 API 版本检测、识别哪些变更会影响自己的宿主程序并据此编写与未来 mpv 版本兼容的防御式代码。文档定位与适用范围DOCS/client-api-changes.rst 的目标是列出所有通过客户端 APIlibmpv 与client.h使用 mpv 时可能引发兼容性问题的变更。由于客户端 API 同时是输入处理命令、属性和命令行选项的接口该文档在开头明确提示options/commands/properties 层面的变更不在本文档罗列而是记录在 DOCS/interface-changes.rst在 API 版本 1.17 之前这些内容曾部分记录在本文件中。换句话说本文档只覆盖裸 C API 及其行为函数、事件、渲染 API、数据结构的变更不覆盖你能通过这些 API 访问到什么属性/选项/命令语义涉及选项、命令、属性的不兼容变更应去 DOCS/interface-changes.rst 查证更宏观的什么情况下允许破坏兼容的规则定义在 DOCS/compatibility.rst 与 include/mpv/client.h 的 Compatibility 章节中。版本编号机制如何读懂 API 版本号变更记录中的版本号与client.h中的MPV_CLIENT_API_VERSION完全一致。include/mpv/client.h#L250-L251 定义了版本编码方式#define MPV_MAKE_VERSION(major, minor) (((major) 16) | (minor) | 0UL) #define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(2, 5)即一个 32 位平坦整数高 16 位为 major低 16 位为 minor。当前仓库头文件中的 API 版本为2.5对应 mpv 0.40.0 的变更条目。按变更记录开头声明的版本策略major 位高 16 位递增C API 出现与之前版本不兼容的变更时发生minor 位低 16 位递增新增 API 符号时发生属性/命令/选项的变更也可能导致 minor 位递增尤其是当它们不兼容时。头文件注释include/mpv/client.h#L238-L248进一步说明版本在每次 API 变更时递增不兼容变更时 major 递增且这只影响 C 部分不影响属性和选项。API 使用者可用MPV_MAKE_VERSION()构造整数然后用、、、做版本比较。两个实用的配套机制运行时版本检测mpv_client_api_version()include/mpv/client.h#L266返回实际编译时所用的 API 版本。这意味着你的代码应同时用编译期宏知道自己能调用哪些函数和运行时函数知道链接/调用的库实际版本双重判断能力。排除废弃符号在包含任何 libmpv 头文件前#define MPV_ENABLE_DEPRECATED 0即可把头文件中的废弃符号排除掉此机制自 API 1.24 加入见 include/mpv/client.h#L253-L261。注意这只影响头文件可见性废弃的属性和命令在运行时仍然工作。兼容策略ABI 承诺与变相移除规则DOCS/compatibility.rst 的 libmpv C API 章节给出了与本文档配套的硬性承诺API 始终兼容不兼容变更只允许发生在 major API 版本变更时而 major 变更是极罕见事件通常意味着 API 符号永不被删除ABI 绝不被破坏major 版本变更除外常量数值不变。结构体规则是重点——若结构体由用户分配如mpv_node则不能添加字段例外union 的新增不改变任何字段或结构体本身的偏移/对齐历史上mpv_node就是这样扩展的若结构体仅由 libmpv 分配如mpv_event可以在末尾追加新字段——这正是变更记录中给mpv_event_end_file追加playlist_entry_id等字段这类条目合法的原因ABI 只向后兼容宿主程序链接旧版 libmpv、然后替换为新版库仍应正常工作无未定义行为反向的前向兼容程序与比其链接版本更旧的库配合不作要求变相移除也受约束把某个函数改成总是返回错误或什么都不做等同于移除同样要求至少 2 个版本的废弃期——变更记录中mpv_suspend()/mpv_resume()就是实例1.23 废弃0.23.01.24 条目中变为 no-op2.0 才真正从 API 中删除。include/mpv/client.h#L227-L236 还列出了下一次 major bump 时的计划事项移除所有标记 deprecated 的符号、重排 enum 数值以消除空洞、默认禁用所有事件。做长期规划时值得留意。破坏性变更全记录以下按版本区间完整继承 DOCS/client-api-changes.rst 的条目并在关键点补充当前头文件中的源码佐证。当前 2.x 系列2.0 ~ 2.52.5mpv 0.40.0废弃MPV_RENDER_PARAM_AMBIENT_LIGHT无替代物。该常量仍可见于 include/mpv/render.h#L233MPV_RENDER_PARAM_AMBIENT_LIGHT 7。2.4mpv 0.39.0mpv_render_param携带MPV_RENDER_PARAM_ICC_PROFILE参数时不再对内存分配做错误假设从此可以被正确使用。这是一次行为修复此前该用法存在隐患2.4 之前构建的客户端若依赖旧行为需注意差异。2.3mpv 0.38.0部分回滚 API 1.27 的变更不再把 libmpv 作为默认 VO将其移到自动探测顺序的末尾。这恢复了除 macOS 外所有平台的先前行为macOS 上若编译时启用了 cocoa-cb 支持仍会自动选择 libmpv/cocoa-cb。这条对调用了渲染 API 初始化但未显式设置vo选项的宿主程序影响最大。2.2mpv 0.37.0新增mpv_time_ns()。当前头文件可确认纳秒级播放时钟接口mpv_get_time_ns()include/mpv/client.h#L618的存在纳秒时钟是与播放时间轴同步的可靠基准。2.1mpv 0.36.0新增mpv_del_property()include/mpv/client.h#L1096允许删除动态创建的属性。2.0mpv 0.35.0——一次大清理移除过时 opengl_cb API 的头文件与函数移除mpv_opengl_init_params.extra_exts字段移除废弃的mpv_detach_destroy应改用mpv_destroy移除过时的mpv_suspend与mpv_resume移除废弃的事件SCRIPT_INPUT_DISPATCH、PAUSE、UNPAUSE、TRACKS_CHANGED、TRACK_SWITCHED、METADATA_UPDATE、CHAPTER_CHANGE。这些被移除的事件从 0.7.01.9 条目起就被标记废弃官方建议一律改用mpv_observe_property()。对 API 使用者的实际含义监听轨道切换、元数据更新等状态变化应走属性观察而非一次性事件。1.100 ~ 1.109mpv 0.29.0 ~ 0.33.01.109mpv 0.33.0新增MPV_RENDER_API_TYPE_SW及相关的软件渲染 API当前定义于 include/mpv/render.h#L470取值为sw。这是 render API 对无 GL 环境如服务端转码、截图的重要补充停用 opengl_cb API其初始化从此刻起总是失败。该 API 已废弃两年以上官方指引是改用 render API。1.108废弃MPV_EVENT_IDLE当前仍定义于 include/mpv/client.h#L1305新增mpv_event_start_file结构体定义见 include/mpv/client.h#L1501-L1506事件构造点在 player/loadfile.c#L1759为mpv_event_end_file新增三个字段playlist_entry_id、playlist_insert_id、playlist_insert_num_entries追加到 libmpv 分配的结构体尾部符合上述 ABI 规则新增mpv_event_to_node()include/mpv/client.h#L1655把事件统一转换为mpv_node新增mpv_client_id()include/mpv/client.h#L425多客户端weak client场景下识别事件/命令的发出方。1.107mpv 0.32.0 条目移除已废弃的qthelper.hpp。官方明确这不视为 API 变更它只是额外提供的辅助头文件依赖它的项目可自行下载该文件并调整 include 语句但官方同时建议为自身用途编写更好的封装。注意变更记录中 1.107 号在 0.33.0 与 0.31.0 两个版本段下都出现0.31.0 的 1.107 是废弃MPV_EVENT_TICK0.32.0 段下的条目移除 qthelper.hpp没有再次 bump 说明这不是 API 变更。1.106 ~ 1.102mpv 0.30.01.106mpv_stream_cb_info增加cancel_fn自定义流协议支持取消1.105修复MPV_RENDER_PARAM_ADVANCED_CONTROL与默认启用的vd-lavc-dr选项组合下的死锁问题。没有真正的 API 变更但官方要求旧 API 版本 旧 mpv 版本的组合应把vd-lavc-dr设为no规避且使用者仍须遵守 include/mpv/render.h 中记录的规则以避免其他死锁1.104废弃struct mpv_opengl_drm_params由mpv_opengl_drm_params_v2替代、废弃MPV_RENDER_PARAM_DRM_DISPLAY由MPV_RENDER_PARAM_DRM_DISPLAY_V2替代。DRM 无头渲染路径的结构体换代做 DRM 输出的项目需迁移到 v21.103重做异步命令处理——新增mpv_event_command使mpv_command_async()/mpv_command_node_async()发出的命令能够返回值新增mpv_abort_async_command()include/mpv/client.h#L1045。这是异步编程模型的重要完善以前异步命令发了就不管现在可以拿到回复并主动中止1.102struct mpv_opengl_drm_osd_size更名为mpv_opengl_drm_draw_surface_sizeMPV_RENDER_PARAM_DRM_OSD_SIZE更名为MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE。1.101mpv 0.29.0新增MPV_RENDER_PARAM_ADVANCED_CONTROL及相关 API、MPV_RENDER_PARAM_NEXT_FRAME_INFO及相关符号、MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME、MPV_RENDER_PARAM_SKIP_RENDERING以及mpv_render_context_get_info()。这一批扩展让高级宿主可以精确控制逐帧节奏如等待目标时间再出帧、跳过渲染、查询下一帧信息是构建低延迟/帧精确同步界面的基础。1.20 ~ 1.29render API 取代 opengl_cb 的核心转折1.100提升 API 编号以消除与 mpv 发布版本号的混淆自此 API 版本进入三位 minor 时代真正落地新 render API 下的GL_MP_MPGetNativeDisplay变更意味着旧 opengl-cb 路径下除 x11/wayland 外的 native display 兼容不再支持废弃mpv_get_wakeup_pipe()。官方给出的替代很简单设置一个 wakeup 回调在回调里往 pipe 写字节即可不必依赖专用 API新增一等公民的 hook API取代基于mpv_command()的旧式 hack。旧 API 从未承诺稳定新 API 承诺稳定并废弃。1.29mpv_terminate_destroy()与mpv_detach_destroy()行为微妙变化详见头文件文档mpv_detach_destroy()不再在所有情况下都让播放器继续运行更接近引用计数语义mpv_detach_destroy()更名为mpv_destroy()旧名保留为废弃别名到 2.0 移除新增mpv_create_weak_client()include/mpv/client.h#L582依托上述生命周期变化实现弱引用客户端——脚本、子模块可以借用主 handle其生命周期与主 handle 解耦MPV_EVENT_SHUTDOWN现在在mpv_handle应终止时恰好返回一次而不再向事件队列刷屏。1.28 —— render API 正式登场废弃 opengl_cb 渲染 API由 include/mpv/render.h 与 include/mpv/render_gl.h 取代。目标是支持 OpenGL 以外的后端旧 API 由新 API 模拟实现。VOopengl-cb同步更名为libmpvmpv_get_sub_api()随 opengl_cb 一同废弃。官方给出的函数对应关系旧opengl_cb新render APImpv_opengl_cb_init_glmpv_render_context_creatempv_opengl_cb_set_update_callbackmpv_render_context_set_update_callbackmpv_opengl_cb_drawmpv_render_context_rendermpv_opengl_cb_report_flipmpv_render_context_report_swapmpv_opengl_cb_uninit_glmpv_render_context_free另一个关键点GL_MP_MPGetNativeDisplay伪扩展在新 render API 中不再使用旧 opengl-cb API 只处理x11和wl两种名称其余平台支持被移除。新 API 改用正式参数例如 X11 直接传MPV_RENDER_PARAM_X11_DISPLAY废弃qthelper.hpp头文件。官方理由它只是 C/Qt 辅助工具没有留在 mpv 仓库或成为 libmpv API 一部分的理由。使用者可安全地把该头文件复制进自己项目它只使用 libmpv 公共 API或由社区在独立仓库维护。1.27opengl-cb 成为默认 VO。由此产生微妙行为变化如果 API 使用者调用了mpv_opengl_cb_init_gl()但未设置vo选项过去会像 CLI 一样使用其他 VO如vogpu此后行为等价于使用了voopengl-cb。这条后来在 2.3 被部分回滚。1.20 ~ 1.26mpv 0.22.0 ~ 0.28.01.26mpv 0.28.0移除glMPGetNativeDisplay(drm)支持新增mpv_opengl_cb_window_pos、mpv_opengl_cb_drm_params并支持通过glMPGetNativeDisplay()使用面向 DRM 无头/原子模式输出libmpv 中--stop-playback-on-init-failureno成为默认与 mpv CLI 一致。1.25mpv 0.27.0移除通过mpv_set_option*()设置no-前缀选项的能力对应 0.23.0 时的废弃声明。1.24mpv 0.25.0新增MPV_ENABLE_DEPRECATED预处理符号使用者可定义它以把头文件中的废弃符号排除注意条目编号0.25.0 段的 1.24 与 0.23.0 段的 1.24 是两个独立 bump原文如此。1.24mpv 0.23.0已废弃的mpv_suspend()与mpv_resume()变为 no-opstubbed out。1.23mpv 0.22.0废弃通过mpv_set_option*()设置no-选项例如应设videono而不是no-video不再覆盖 SIGPIPE 信号处理器那是对 FFmpeg TLS 代码缺陷的远古 workaround早已修复废弃mpv_suspend()与mpv_resume()声明 0.23.0 起变为空操作mpv_set_property()在mpv_initialize()之前开始部分可用可替代mpv_set_option()半废弃mpv_set_option()/mpv_set_option_string()应改用mpv_set_property()。少数与已废弃属性冲突的选项仍可能需要mpv_set_option()见client.h中mpv_set_option()的备注未来这些冲突项移除后mpv_set_option()将在内部翻译成mpv_set_property()qthelper.hpp废弃get_property_variant、set_property_variant、set_option_variant、command_variant替换为get_property、set_property、command。1.10 ~ 1.19mpv 0.7.0 ~ 0.19.01.22mpv 0.19.0新增 stream_cb API支持自定义流协议后续 1.30.0 的 1.106 条目为其补充cancel_fn。mpv 0.18.1无版本号 bump从mpv_request_log_messages()文档中移除status日志级别它与v100% 等价行为未变因此不构成实际 API 变更。1.21mpv 0.18.0mpv_set_property()配合MPV_FORMAT_NODE的行为变化此前若属性不是字符串且没有特殊机制传入formatMPV_FORMAT_STRING的mpv_node会被拒绝此后总是走选项字符串解析器携带基础数据类型的mpv_node的效果与直接用该类型调用完全一致等价于mpv_set_option()。该变化同时影响 Lua 的mp.set_property_native()泛化choice 类型选项/属性为yes/no时可以用MPV_FORMAT_FLAG设置把 choice 属性按MPV_FORMAT_NODE读取时值为yestrue或nofalse会返回MPV_FORMAT_FLAG。这隐式地同时影响 Lua 与 JSON IPC 接口vo-cmdline 在 vo_opengl / vo_opengl_hq 上的大改不影响 vo_opengl_cb选项不再重置而是叠加到当前选项之上未文档化的特殊值-仍然有效但语义变为重置到所有 vo-cmdline 命令调用之前的状态。1.20mpv 0.12.0废弃GL_MP_D3D_interfaces/glMPGetD3DInterface引入GL_MP_MPGetNativeDisplay/glMPGetNativeDisplay向后兼容的重命名。1.19mpv 0.10.0新增GL_MP_D3D_interfaces伪扩展使某些情况下能在 OpenGL 全屏模式使用 DXVA2mpv_request_log_messages()开始接受terminal-default参数。1.18新增MPV_END_FILE_REASON_REDIRECTMPV_EVENT_END_FILE行为相应变化一批 DOCS/interface-changes.rst 中的配套变更。1.17mpv_initialize()现在会阻塞 SIGPIPE细节见client.h。1.0 ~ 1.16mpv 0.4.0 ~ 0.9.0API 宣布稳定之后1.16mpv 0.9.0新增mpv_opengl_cb_report_flip()引入mpv_opengl_cb_draw()并废弃mpv_opengl_cb_render()新增MPV_FORMAT_BYTE_ARRAY。1.15mpv_initialize()开始加载配置文件要求设置config与config-dir选项特别是会加载mpv.conf——这对嵌入式使用 libmpv 却意外读到用户全局配置的行为差异是重要提示seek与screenshot命令的向后兼容微调新 flag 语法旧附加参数废弃。1.14mpv 0.8.0新增mpv_wait_async_requests()--msg-level选项的原生类型从平坦字符串变为 key-value 列表按字符串设置/读取仍可用。1.13新增MPV_EVENT_QUEUE_OVERFLOW事件事件队列满时通知客户端对应MPV_ERROR_EVENT_QUEUE_FULL错误码语义。1.12qthelper.hpp新增class Handle改进 opengl_cb.h 的未初始化行为并修复 qml 示例新增mpv_create_client()函数——独立创建客户端区别于 weak client的入口。1.11新增 OpenGL 渲染互操作 API使应用可以合并自身与 mpv 的 OpenGL 渲染。当时明确警告该 API 尚不稳定opengl_cb.h 中的一切可能在后续 minor bump 中以任何不兼容方式变化直到 1.28 被 render API 正式取代。1.10mpv 0.7.0废弃/禁用一切与script_dispatch直接相关的内容。1.9mpv 0.7.0为mpv_event_end_file.reason引入enum mpv_end_file_reason新增MPV_END_FILE_REASON_ERROR与mpv_event_end_file.error字段改进播放失败的错误报告新增--stop-playback-on-init-failure选项并使其成为 libmpv 的默认行为CLI 不受影响qthelper.hpp新增set_option_variant()标记以下事件为废弃MPV_EVENT_TRACKS_CHANGED、MPV_EVENT_TRACK_SWITCHED、MPV_EVENT_PAUSE、MPV_EVENT_UNPAUSE、MPV_EVENT_METADATA_UPDATE、MPV_EVENT_CHAPTER_CHANGE。官方建议按文档注释改用mpv_observe_property()当时不删除、仍然工作——直到 2.0 才真正移除。1.8新增qthelper.hppQt C 辅助头文件的起点。1.7新增mpv_command_node()、mpv_command_node_async()——以mpv_node传参、返回值的命令接口是后来 1.103 异步命令返回值的早期基础。1.6修改core-idle属性行为MPV_EVENT_LOG_MESSAGE现在总是发送完整行引入数值型日志级别mpv_log_level。1.5mpv 0.6.0X11 与--wid行为的再次调整上次改动不符合预期现可用input-x11-keyboard选项显式控制。这是 XEmbed 实现并确认工作前的临时措施。注意1.6 中该选项更名为input-vo-keyboard旧名仍可用。1.4X11 与--wid行为的微妙变化该变更被加入 0.5.2曾造成一些问题见原文引用的 issue #1090。1.3mpv 0.5.0新增MPV_MAKE_VERSION()。1.2移除stream-time-pos属性无替代。1.1dvdnav://重映射到dvd://新增--cache-file、--cache-file-size、--colormatrix-primaries及其属性图像格式属性新增primaries子字段新增playback-time属性--start选项扩展开头的由此前无意义变为有意义新增cache-free与cache-used属性macOScoreaudioAO 的 spdif 代码拆分为独立 AO。1.0mpv 0.4.0API 被宣布为稳定。这是整个版本纪元的起点从此不兼容变更遵循 major bump 规则ABI 得到前述承诺。面向 API 使用者的实战建议结合变更记录、include/mpv/client.h 的 Compatibility 章节与 DOCS/compatibility.rst可以提炼出几条可直接落地的工程实践版本比较用整数双通道检测。编译期用MPV_MAKE_VERSION(major, minor)与MPV_CLIENT_API_VERSION做整数比较决定调用哪个函数例如 1.28 前后的渲染初始化走完全不同的代码路径运行时调用mpv_client_api_version()确认实际库版本避免代码按 2.x 写、链接到 1.x 库的组合。偏好MPV_FORMAT_STRING。client.h的注释明确建议选项、命令、属性可能消失、改取值范围或改变底层数据类型优先用字符串类型解耦代码与潜在变化做防御式编程。状态监听走属性观察不走事件。1.9 起废弃的MPV_EVENT_PAUSE/UNPAUSE/TRACKS_CHANGED/METADATA_UPDATE/CHAPTER_CHANGE等已在 2.0 移除正确做法是mpv_observe_property()监听pause、track-list、media-title等属性。异步命令要处理返回值与中止。1.103 之后mpv_command_async()/mpv_command_node_async()的回复通过mpv_event_command事件返回需要取消时用mpv_abort_async_command()按reply_userdata定位。渲染路径按版本分支。1.28 之前opengl_cb 五函数式 API1.28 之后mpv_render_context_*系列1.109 之后无 GL 环境可用MPV_RENDER_API_TYPE_SW软件后端DRM 输出注意 1.102 的更名与 1.104 的 v2 结构体。生命周期用对函数。mpv_detach_destroy()自 1.29 起行为更接近引用计数1.29 起应使用mpv_destroy()弱引用客户端用mpv_create_weak_client()MPV_EVENT_SHUTDOWN自 1.29 起恰好出现一次可直接作为退出信号无需去重。严格模式检查废弃依赖。在自己的构建中#define MPV_ENABLE_DEPRECATED 0后重新编译可以提前暴露对已废弃符号的依赖——本记录中从 1.9 废弃到 2.0 移除的事件、从 1.23 废弃到 2.0 移除的mpv_suspend()都属于废弃期看似无害、major bump 时突然断裂的典型。变更记录DOCS/client-api-changes.rst与 include/mpv/client.h 头文件注释相互印证C API 本身的变更稀疏且可预期真正快速演进的始终是它所暴露的选项/命令/属性语义——那一部分请持续关注 DOCS/interface-changes.rst。【免费下载链接】mpv Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mpv libmpv 客户端 API 兼容性指南：版本编号机制、兼容策略与破坏性变更全记录
mpv libmpv 客户端 API 兼容性指南版本编号机制、兼容策略与破坏性变更全记录【免费下载链接】mpv Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv本篇基于 mpv 仓库的 DOCS/client-api-changes.rst 展开系统讲解 libmpvclient.h客户端 C API 的版本编号规则major/minor bump 策略、ABI 兼容承诺以及从 1.0API 宣布稳定到当前 2.5 的全部破坏性变更历史。读完后你将能够正确做 API 版本检测、识别哪些变更会影响自己的宿主程序并据此编写与未来 mpv 版本兼容的防御式代码。文档定位与适用范围DOCS/client-api-changes.rst 的目标是列出所有通过客户端 APIlibmpv 与client.h使用 mpv 时可能引发兼容性问题的变更。由于客户端 API 同时是输入处理命令、属性和命令行选项的接口该文档在开头明确提示options/commands/properties 层面的变更不在本文档罗列而是记录在 DOCS/interface-changes.rst在 API 版本 1.17 之前这些内容曾部分记录在本文件中。换句话说本文档只覆盖裸 C API 及其行为函数、事件、渲染 API、数据结构的变更不覆盖你能通过这些 API 访问到什么属性/选项/命令语义涉及选项、命令、属性的不兼容变更应去 DOCS/interface-changes.rst 查证更宏观的什么情况下允许破坏兼容的规则定义在 DOCS/compatibility.rst 与 include/mpv/client.h 的 Compatibility 章节中。版本编号机制如何读懂 API 版本号变更记录中的版本号与client.h中的MPV_CLIENT_API_VERSION完全一致。include/mpv/client.h#L250-L251 定义了版本编码方式#define MPV_MAKE_VERSION(major, minor) (((major) 16) | (minor) | 0UL) #define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(2, 5)即一个 32 位平坦整数高 16 位为 major低 16 位为 minor。当前仓库头文件中的 API 版本为2.5对应 mpv 0.40.0 的变更条目。按变更记录开头声明的版本策略major 位高 16 位递增C API 出现与之前版本不兼容的变更时发生minor 位低 16 位递增新增 API 符号时发生属性/命令/选项的变更也可能导致 minor 位递增尤其是当它们不兼容时。头文件注释include/mpv/client.h#L238-L248进一步说明版本在每次 API 变更时递增不兼容变更时 major 递增且这只影响 C 部分不影响属性和选项。API 使用者可用MPV_MAKE_VERSION()构造整数然后用、、、做版本比较。两个实用的配套机制运行时版本检测mpv_client_api_version()include/mpv/client.h#L266返回实际编译时所用的 API 版本。这意味着你的代码应同时用编译期宏知道自己能调用哪些函数和运行时函数知道链接/调用的库实际版本双重判断能力。排除废弃符号在包含任何 libmpv 头文件前#define MPV_ENABLE_DEPRECATED 0即可把头文件中的废弃符号排除掉此机制自 API 1.24 加入见 include/mpv/client.h#L253-L261。注意这只影响头文件可见性废弃的属性和命令在运行时仍然工作。兼容策略ABI 承诺与变相移除规则DOCS/compatibility.rst 的 libmpv C API 章节给出了与本文档配套的硬性承诺API 始终兼容不兼容变更只允许发生在 major API 版本变更时而 major 变更是极罕见事件通常意味着 API 符号永不被删除ABI 绝不被破坏major 版本变更除外常量数值不变。结构体规则是重点——若结构体由用户分配如mpv_node则不能添加字段例外union 的新增不改变任何字段或结构体本身的偏移/对齐历史上mpv_node就是这样扩展的若结构体仅由 libmpv 分配如mpv_event可以在末尾追加新字段——这正是变更记录中给mpv_event_end_file追加playlist_entry_id等字段这类条目合法的原因ABI 只向后兼容宿主程序链接旧版 libmpv、然后替换为新版库仍应正常工作无未定义行为反向的前向兼容程序与比其链接版本更旧的库配合不作要求变相移除也受约束把某个函数改成总是返回错误或什么都不做等同于移除同样要求至少 2 个版本的废弃期——变更记录中mpv_suspend()/mpv_resume()就是实例1.23 废弃0.23.01.24 条目中变为 no-op2.0 才真正从 API 中删除。include/mpv/client.h#L227-L236 还列出了下一次 major bump 时的计划事项移除所有标记 deprecated 的符号、重排 enum 数值以消除空洞、默认禁用所有事件。做长期规划时值得留意。破坏性变更全记录以下按版本区间完整继承 DOCS/client-api-changes.rst 的条目并在关键点补充当前头文件中的源码佐证。当前 2.x 系列2.0 ~ 2.52.5mpv 0.40.0废弃MPV_RENDER_PARAM_AMBIENT_LIGHT无替代物。该常量仍可见于 include/mpv/render.h#L233MPV_RENDER_PARAM_AMBIENT_LIGHT 7。2.4mpv 0.39.0mpv_render_param携带MPV_RENDER_PARAM_ICC_PROFILE参数时不再对内存分配做错误假设从此可以被正确使用。这是一次行为修复此前该用法存在隐患2.4 之前构建的客户端若依赖旧行为需注意差异。2.3mpv 0.38.0部分回滚 API 1.27 的变更不再把 libmpv 作为默认 VO将其移到自动探测顺序的末尾。这恢复了除 macOS 外所有平台的先前行为macOS 上若编译时启用了 cocoa-cb 支持仍会自动选择 libmpv/cocoa-cb。这条对调用了渲染 API 初始化但未显式设置vo选项的宿主程序影响最大。2.2mpv 0.37.0新增mpv_time_ns()。当前头文件可确认纳秒级播放时钟接口mpv_get_time_ns()include/mpv/client.h#L618的存在纳秒时钟是与播放时间轴同步的可靠基准。2.1mpv 0.36.0新增mpv_del_property()include/mpv/client.h#L1096允许删除动态创建的属性。2.0mpv 0.35.0——一次大清理移除过时 opengl_cb API 的头文件与函数移除mpv_opengl_init_params.extra_exts字段移除废弃的mpv_detach_destroy应改用mpv_destroy移除过时的mpv_suspend与mpv_resume移除废弃的事件SCRIPT_INPUT_DISPATCH、PAUSE、UNPAUSE、TRACKS_CHANGED、TRACK_SWITCHED、METADATA_UPDATE、CHAPTER_CHANGE。这些被移除的事件从 0.7.01.9 条目起就被标记废弃官方建议一律改用mpv_observe_property()。对 API 使用者的实际含义监听轨道切换、元数据更新等状态变化应走属性观察而非一次性事件。1.100 ~ 1.109mpv 0.29.0 ~ 0.33.01.109mpv 0.33.0新增MPV_RENDER_API_TYPE_SW及相关的软件渲染 API当前定义于 include/mpv/render.h#L470取值为sw。这是 render API 对无 GL 环境如服务端转码、截图的重要补充停用 opengl_cb API其初始化从此刻起总是失败。该 API 已废弃两年以上官方指引是改用 render API。1.108废弃MPV_EVENT_IDLE当前仍定义于 include/mpv/client.h#L1305新增mpv_event_start_file结构体定义见 include/mpv/client.h#L1501-L1506事件构造点在 player/loadfile.c#L1759为mpv_event_end_file新增三个字段playlist_entry_id、playlist_insert_id、playlist_insert_num_entries追加到 libmpv 分配的结构体尾部符合上述 ABI 规则新增mpv_event_to_node()include/mpv/client.h#L1655把事件统一转换为mpv_node新增mpv_client_id()include/mpv/client.h#L425多客户端weak client场景下识别事件/命令的发出方。1.107mpv 0.32.0 条目移除已废弃的qthelper.hpp。官方明确这不视为 API 变更它只是额外提供的辅助头文件依赖它的项目可自行下载该文件并调整 include 语句但官方同时建议为自身用途编写更好的封装。注意变更记录中 1.107 号在 0.33.0 与 0.31.0 两个版本段下都出现0.31.0 的 1.107 是废弃MPV_EVENT_TICK0.32.0 段下的条目移除 qthelper.hpp没有再次 bump 说明这不是 API 变更。1.106 ~ 1.102mpv 0.30.01.106mpv_stream_cb_info增加cancel_fn自定义流协议支持取消1.105修复MPV_RENDER_PARAM_ADVANCED_CONTROL与默认启用的vd-lavc-dr选项组合下的死锁问题。没有真正的 API 变更但官方要求旧 API 版本 旧 mpv 版本的组合应把vd-lavc-dr设为no规避且使用者仍须遵守 include/mpv/render.h 中记录的规则以避免其他死锁1.104废弃struct mpv_opengl_drm_params由mpv_opengl_drm_params_v2替代、废弃MPV_RENDER_PARAM_DRM_DISPLAY由MPV_RENDER_PARAM_DRM_DISPLAY_V2替代。DRM 无头渲染路径的结构体换代做 DRM 输出的项目需迁移到 v21.103重做异步命令处理——新增mpv_event_command使mpv_command_async()/mpv_command_node_async()发出的命令能够返回值新增mpv_abort_async_command()include/mpv/client.h#L1045。这是异步编程模型的重要完善以前异步命令发了就不管现在可以拿到回复并主动中止1.102struct mpv_opengl_drm_osd_size更名为mpv_opengl_drm_draw_surface_sizeMPV_RENDER_PARAM_DRM_OSD_SIZE更名为MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE。1.101mpv 0.29.0新增MPV_RENDER_PARAM_ADVANCED_CONTROL及相关 API、MPV_RENDER_PARAM_NEXT_FRAME_INFO及相关符号、MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME、MPV_RENDER_PARAM_SKIP_RENDERING以及mpv_render_context_get_info()。这一批扩展让高级宿主可以精确控制逐帧节奏如等待目标时间再出帧、跳过渲染、查询下一帧信息是构建低延迟/帧精确同步界面的基础。1.20 ~ 1.29render API 取代 opengl_cb 的核心转折1.100提升 API 编号以消除与 mpv 发布版本号的混淆自此 API 版本进入三位 minor 时代真正落地新 render API 下的GL_MP_MPGetNativeDisplay变更意味着旧 opengl-cb 路径下除 x11/wayland 外的 native display 兼容不再支持废弃mpv_get_wakeup_pipe()。官方给出的替代很简单设置一个 wakeup 回调在回调里往 pipe 写字节即可不必依赖专用 API新增一等公民的 hook API取代基于mpv_command()的旧式 hack。旧 API 从未承诺稳定新 API 承诺稳定并废弃。1.29mpv_terminate_destroy()与mpv_detach_destroy()行为微妙变化详见头文件文档mpv_detach_destroy()不再在所有情况下都让播放器继续运行更接近引用计数语义mpv_detach_destroy()更名为mpv_destroy()旧名保留为废弃别名到 2.0 移除新增mpv_create_weak_client()include/mpv/client.h#L582依托上述生命周期变化实现弱引用客户端——脚本、子模块可以借用主 handle其生命周期与主 handle 解耦MPV_EVENT_SHUTDOWN现在在mpv_handle应终止时恰好返回一次而不再向事件队列刷屏。1.28 —— render API 正式登场废弃 opengl_cb 渲染 API由 include/mpv/render.h 与 include/mpv/render_gl.h 取代。目标是支持 OpenGL 以外的后端旧 API 由新 API 模拟实现。VOopengl-cb同步更名为libmpvmpv_get_sub_api()随 opengl_cb 一同废弃。官方给出的函数对应关系旧opengl_cb新render APImpv_opengl_cb_init_glmpv_render_context_creatempv_opengl_cb_set_update_callbackmpv_render_context_set_update_callbackmpv_opengl_cb_drawmpv_render_context_rendermpv_opengl_cb_report_flipmpv_render_context_report_swapmpv_opengl_cb_uninit_glmpv_render_context_free另一个关键点GL_MP_MPGetNativeDisplay伪扩展在新 render API 中不再使用旧 opengl-cb API 只处理x11和wl两种名称其余平台支持被移除。新 API 改用正式参数例如 X11 直接传MPV_RENDER_PARAM_X11_DISPLAY废弃qthelper.hpp头文件。官方理由它只是 C/Qt 辅助工具没有留在 mpv 仓库或成为 libmpv API 一部分的理由。使用者可安全地把该头文件复制进自己项目它只使用 libmpv 公共 API或由社区在独立仓库维护。1.27opengl-cb 成为默认 VO。由此产生微妙行为变化如果 API 使用者调用了mpv_opengl_cb_init_gl()但未设置vo选项过去会像 CLI 一样使用其他 VO如vogpu此后行为等价于使用了voopengl-cb。这条后来在 2.3 被部分回滚。1.20 ~ 1.26mpv 0.22.0 ~ 0.28.01.26mpv 0.28.0移除glMPGetNativeDisplay(drm)支持新增mpv_opengl_cb_window_pos、mpv_opengl_cb_drm_params并支持通过glMPGetNativeDisplay()使用面向 DRM 无头/原子模式输出libmpv 中--stop-playback-on-init-failureno成为默认与 mpv CLI 一致。1.25mpv 0.27.0移除通过mpv_set_option*()设置no-前缀选项的能力对应 0.23.0 时的废弃声明。1.24mpv 0.25.0新增MPV_ENABLE_DEPRECATED预处理符号使用者可定义它以把头文件中的废弃符号排除注意条目编号0.25.0 段的 1.24 与 0.23.0 段的 1.24 是两个独立 bump原文如此。1.24mpv 0.23.0已废弃的mpv_suspend()与mpv_resume()变为 no-opstubbed out。1.23mpv 0.22.0废弃通过mpv_set_option*()设置no-选项例如应设videono而不是no-video不再覆盖 SIGPIPE 信号处理器那是对 FFmpeg TLS 代码缺陷的远古 workaround早已修复废弃mpv_suspend()与mpv_resume()声明 0.23.0 起变为空操作mpv_set_property()在mpv_initialize()之前开始部分可用可替代mpv_set_option()半废弃mpv_set_option()/mpv_set_option_string()应改用mpv_set_property()。少数与已废弃属性冲突的选项仍可能需要mpv_set_option()见client.h中mpv_set_option()的备注未来这些冲突项移除后mpv_set_option()将在内部翻译成mpv_set_property()qthelper.hpp废弃get_property_variant、set_property_variant、set_option_variant、command_variant替换为get_property、set_property、command。1.10 ~ 1.19mpv 0.7.0 ~ 0.19.01.22mpv 0.19.0新增 stream_cb API支持自定义流协议后续 1.30.0 的 1.106 条目为其补充cancel_fn。mpv 0.18.1无版本号 bump从mpv_request_log_messages()文档中移除status日志级别它与v100% 等价行为未变因此不构成实际 API 变更。1.21mpv 0.18.0mpv_set_property()配合MPV_FORMAT_NODE的行为变化此前若属性不是字符串且没有特殊机制传入formatMPV_FORMAT_STRING的mpv_node会被拒绝此后总是走选项字符串解析器携带基础数据类型的mpv_node的效果与直接用该类型调用完全一致等价于mpv_set_option()。该变化同时影响 Lua 的mp.set_property_native()泛化choice 类型选项/属性为yes/no时可以用MPV_FORMAT_FLAG设置把 choice 属性按MPV_FORMAT_NODE读取时值为yestrue或nofalse会返回MPV_FORMAT_FLAG。这隐式地同时影响 Lua 与 JSON IPC 接口vo-cmdline 在 vo_opengl / vo_opengl_hq 上的大改不影响 vo_opengl_cb选项不再重置而是叠加到当前选项之上未文档化的特殊值-仍然有效但语义变为重置到所有 vo-cmdline 命令调用之前的状态。1.20mpv 0.12.0废弃GL_MP_D3D_interfaces/glMPGetD3DInterface引入GL_MP_MPGetNativeDisplay/glMPGetNativeDisplay向后兼容的重命名。1.19mpv 0.10.0新增GL_MP_D3D_interfaces伪扩展使某些情况下能在 OpenGL 全屏模式使用 DXVA2mpv_request_log_messages()开始接受terminal-default参数。1.18新增MPV_END_FILE_REASON_REDIRECTMPV_EVENT_END_FILE行为相应变化一批 DOCS/interface-changes.rst 中的配套变更。1.17mpv_initialize()现在会阻塞 SIGPIPE细节见client.h。1.0 ~ 1.16mpv 0.4.0 ~ 0.9.0API 宣布稳定之后1.16mpv 0.9.0新增mpv_opengl_cb_report_flip()引入mpv_opengl_cb_draw()并废弃mpv_opengl_cb_render()新增MPV_FORMAT_BYTE_ARRAY。1.15mpv_initialize()开始加载配置文件要求设置config与config-dir选项特别是会加载mpv.conf——这对嵌入式使用 libmpv 却意外读到用户全局配置的行为差异是重要提示seek与screenshot命令的向后兼容微调新 flag 语法旧附加参数废弃。1.14mpv 0.8.0新增mpv_wait_async_requests()--msg-level选项的原生类型从平坦字符串变为 key-value 列表按字符串设置/读取仍可用。1.13新增MPV_EVENT_QUEUE_OVERFLOW事件事件队列满时通知客户端对应MPV_ERROR_EVENT_QUEUE_FULL错误码语义。1.12qthelper.hpp新增class Handle改进 opengl_cb.h 的未初始化行为并修复 qml 示例新增mpv_create_client()函数——独立创建客户端区别于 weak client的入口。1.11新增 OpenGL 渲染互操作 API使应用可以合并自身与 mpv 的 OpenGL 渲染。当时明确警告该 API 尚不稳定opengl_cb.h 中的一切可能在后续 minor bump 中以任何不兼容方式变化直到 1.28 被 render API 正式取代。1.10mpv 0.7.0废弃/禁用一切与script_dispatch直接相关的内容。1.9mpv 0.7.0为mpv_event_end_file.reason引入enum mpv_end_file_reason新增MPV_END_FILE_REASON_ERROR与mpv_event_end_file.error字段改进播放失败的错误报告新增--stop-playback-on-init-failure选项并使其成为 libmpv 的默认行为CLI 不受影响qthelper.hpp新增set_option_variant()标记以下事件为废弃MPV_EVENT_TRACKS_CHANGED、MPV_EVENT_TRACK_SWITCHED、MPV_EVENT_PAUSE、MPV_EVENT_UNPAUSE、MPV_EVENT_METADATA_UPDATE、MPV_EVENT_CHAPTER_CHANGE。官方建议按文档注释改用mpv_observe_property()当时不删除、仍然工作——直到 2.0 才真正移除。1.8新增qthelper.hppQt C 辅助头文件的起点。1.7新增mpv_command_node()、mpv_command_node_async()——以mpv_node传参、返回值的命令接口是后来 1.103 异步命令返回值的早期基础。1.6修改core-idle属性行为MPV_EVENT_LOG_MESSAGE现在总是发送完整行引入数值型日志级别mpv_log_level。1.5mpv 0.6.0X11 与--wid行为的再次调整上次改动不符合预期现可用input-x11-keyboard选项显式控制。这是 XEmbed 实现并确认工作前的临时措施。注意1.6 中该选项更名为input-vo-keyboard旧名仍可用。1.4X11 与--wid行为的微妙变化该变更被加入 0.5.2曾造成一些问题见原文引用的 issue #1090。1.3mpv 0.5.0新增MPV_MAKE_VERSION()。1.2移除stream-time-pos属性无替代。1.1dvdnav://重映射到dvd://新增--cache-file、--cache-file-size、--colormatrix-primaries及其属性图像格式属性新增primaries子字段新增playback-time属性--start选项扩展开头的由此前无意义变为有意义新增cache-free与cache-used属性macOScoreaudioAO 的 spdif 代码拆分为独立 AO。1.0mpv 0.4.0API 被宣布为稳定。这是整个版本纪元的起点从此不兼容变更遵循 major bump 规则ABI 得到前述承诺。面向 API 使用者的实战建议结合变更记录、include/mpv/client.h 的 Compatibility 章节与 DOCS/compatibility.rst可以提炼出几条可直接落地的工程实践版本比较用整数双通道检测。编译期用MPV_MAKE_VERSION(major, minor)与MPV_CLIENT_API_VERSION做整数比较决定调用哪个函数例如 1.28 前后的渲染初始化走完全不同的代码路径运行时调用mpv_client_api_version()确认实际库版本避免代码按 2.x 写、链接到 1.x 库的组合。偏好MPV_FORMAT_STRING。client.h的注释明确建议选项、命令、属性可能消失、改取值范围或改变底层数据类型优先用字符串类型解耦代码与潜在变化做防御式编程。状态监听走属性观察不走事件。1.9 起废弃的MPV_EVENT_PAUSE/UNPAUSE/TRACKS_CHANGED/METADATA_UPDATE/CHAPTER_CHANGE等已在 2.0 移除正确做法是mpv_observe_property()监听pause、track-list、media-title等属性。异步命令要处理返回值与中止。1.103 之后mpv_command_async()/mpv_command_node_async()的回复通过mpv_event_command事件返回需要取消时用mpv_abort_async_command()按reply_userdata定位。渲染路径按版本分支。1.28 之前opengl_cb 五函数式 API1.28 之后mpv_render_context_*系列1.109 之后无 GL 环境可用MPV_RENDER_API_TYPE_SW软件后端DRM 输出注意 1.102 的更名与 1.104 的 v2 结构体。生命周期用对函数。mpv_detach_destroy()自 1.29 起行为更接近引用计数1.29 起应使用mpv_destroy()弱引用客户端用mpv_create_weak_client()MPV_EVENT_SHUTDOWN自 1.29 起恰好出现一次可直接作为退出信号无需去重。严格模式检查废弃依赖。在自己的构建中#define MPV_ENABLE_DEPRECATED 0后重新编译可以提前暴露对已废弃符号的依赖——本记录中从 1.9 废弃到 2.0 移除的事件、从 1.23 废弃到 2.0 移除的mpv_suspend()都属于废弃期看似无害、major bump 时突然断裂的典型。变更记录DOCS/client-api-changes.rst与 include/mpv/client.h 头文件注释相互印证C API 本身的变更稀疏且可预期真正快速演进的始终是它所暴露的选项/命令/属性语义——那一部分请持续关注 DOCS/interface-changes.rst。【免费下载链接】mpv Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考