Something went wrong. Try again.
🎥 Command line media player
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196CLI and API compatibility policy================================
Human users and API users rely on the mpv/libmpv/scripting/IPC interface notbreaking their use case. On the other hand, active development occasionallyrequires breaking things, such as removing old options or changing options ina way that may break.
This document lists rules when, what, and how incompatible changes can be made.It's interesting both for mpv developers, who want to change user-visible parts,and mpv users, who want to know what is guaranteed to remain stable.
Any of the rules below may be overridden by statements in more specificdocumentation (for example, if the manpage says that a particular option may beremoved any time, it means that, and the option probably won't even go throughdeprecation).
Additions---------
Additions are basically always allowed. API users etc. are supposed to deal withthe possibility that for example new API functions are added. Some parts of theAPI may document how they are extended.
Options, commands, properties, events, hooks (command interface)----------------------------------------------------------------
All of these are important for interfacing both with end users and API users(which include Lua scripts, libmpv, and the JSON IPC). As such, they constitutea large part of the user interface and APIs.
Certain options and commands may have documented default values. These defaultvalues are considered a part of the API since scripts may already rely on thesedocumented behaviors. Changing these defaults are considered incompatiblechanges and must be documented. Undocumented default values do not subject tothis requirement, and it is recommended to discourage such usage in the relateddocumentations if there is a need to frequently change such defaults.
All incompatible changes to this must be declared in interface-changes.rst,which include the types of changes, the impact of these changes, and suggestedactions to address such impact so that the incompatibility is alleviated.(This may also list compatible additions, but it's not a requirement.)
Degrees of importance and compatibility preservation^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Critical and central parts of the command interface have the strictestrequirements. It may not be reasonable to break them, and other means to achievesome change have to be found. For example, the "seek" command is a bit of amess, but since changing it would likely affect almost every user, it may beimpossible to break at least the commonly used syntax. If changed anyway, thereshould be a deprecation period of at least 1 year, during which the commandstill works, and possibly a warning should remain even after this.
Important/often used parts must be deprecated for at least 2 releases beforethey can be broken. There must be at least 1 release where the deprecatedfunctionality still works, and a replacement is available (if technicallyreasonable). For example, a feature deprecated in mpv 0.30.0 may be removed inmpv 0.32.0. Minor releases do not count towards this.
Under extraordinary circumstances, such as missed incompatible changes that arealready included in a release, critical security fixes, or a severe shortage ofdeveloper time to address the known incompatible changes, important/often usedparts may be broken immediately, but the change must be extensively documented:all of the related documentations (including manpage, interface-changes.rst,etc., retrospectively modified if applicable) must clearly state the following:the fact that the change is a breaking change; the version when the breakingchange happened; and the reason, impact, and suggested remedy actions.
Less useful parts can be broken immediately, but must come with some sort ofremoval warning.
Parts for debugging and testing may be removed any time, potentially evenwithout any sort of documentation.
Currently, the importance of a part is not documented and not even well-defined,which is probably a mistake.
Renaming or removing options^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Typically, renaming an option can be done in a compatible way with OPT_REPLACED.You may need to check whether the corresponding properties still work (includingmessy details like observing properties for changes).
OPT_REMOVED can be used to inform the user of alternatives or reasons for theremoval, which is better than an option not found error. Likewise,m_option.deprecation_message should be set to something helpful.
Both OPT_REPLACED and OPT_REMOVED can remain in the code for a long time, sincethey're unintrusive and hopefully make incompatible changes less painful forusers.
Scripting APIs--------------
This affects internal scripting APIs (currently Lua and JavaScript).
Vaguely the same rules as with the command interface apply. Since there is alarge number of scripts, an effort should be made to provide compatibilityfor old scripts, but it does not need to be stronger than that of the commandinterface.
Undocumented parts of the scripting APIs are _not_ guaranteed for compatibility.This applies especially for internals. Languages like Lua do not have strictaccess control (nor does the mpv code try to emulate any), so if a scriptaccesses private parts, and breaks on the next mpv release, it's not mpv'sproblem.
JSON IPC--------
The JSON IPC is a thin protocol wrapping the libmpv API and the commandinterface. Compatibility-wise, it's about the same as the scripting APIs.The JSON protocol commands should remain as compatible as possible, and itshould probably accept the current way commands are delimited (line breaks)forever.
The protocol may accept non-standard JSON extensions, but only standard JSON(possibly with restrictions) is guaranteed for compatibility. Clients which wantto remain compatible should not use any extensions.
CLI---
Things such as default key bindings do not necessarily require compatibility.However, the release notes should be extremely clear on changes to "important"key bindings. Bindings which restore the old behavior should be added torestore-old-bindings.conf and restore-osc-bindings.conf.
Some option parsing is CLI-only and not available from libmpv or scripting. Nocompatibility guarantees come with them. However, the rules which mpv uses todistinguish between options and filenames must remain consistent (if thenon-deprecated options syntax is used).
Terminal and log output-----------------------
There are no compatibility guarantees for the terminal output, or the textlogged via ``MPV_EVENT_LOG_MESSAGE`` and similar APIs. In particular, scriptsinvoking mpv CLI are extremely discouraged from trying to parse text output,and should use other mechanisms such as the JSON IPC.
Protocols, filters, demuxers, etc.----------------------------------
Which of these are present is generally not guaranteed, and can even dependon compile time settings.
The filter list and their sub-options are considered part of thecommand-interface.
libmpv C API------------
The libmpv client API (such as ``<libmpv/client.h>``) mostly gives access tothe command interface. The API itself (if looked at as a component separatefrom the command interface) is intended to be extremely stable.
All API changes are documented in client-api-changes.rst.
API compatibility^^^^^^^^^^^^^^^^^
The API is *always* compatible. Incompatible changes are only allowed on majorAPI version changes (see ``MPV_CLIENT_API_VERSION``). A major version change isan extremely rare event, which means usually no API symbols are ever removed.
Essentially removing API functions by making them always return an error, ormaking it do nothing is allowed in cases where it is unlikely to break mostclients, but requires a deprecation period of 2 releases. (This has happened to``mpv_suspend()`` for example.)
API symbols can be deprecated. This should be clearly marked in the doxygenwith ``@deprecated``, and if possible, the affected API symbols should not bevisible if the API user defines ``MPV_ENABLE_DEPRECATED`` to 0.
ABI compatibility^^^^^^^^^^^^^^^^^
The ABI must never be broken, except on major API version changes. For example,constants don't change their values.
Structs are tricky. If a struct can be allocated by a user (such as ``mpv_node``),no fields can be added. (Unless it's an union, and the addition does not changethe offset or alignment of any of the fields or the struct itself. This hashappened to ``mpv_node`` in the past.) If a struct is allocated by libmpv only,new fields can be appended to the end (for example ``mpv_event``).
The ABI is only backward compatible. This means if a host application is linkedto an older libmpv, and libmpv is updated to a newer version, it will stillwork (as in not causing any undefined behavior).
Forward compatibility (an application would work with an older libmpv than itwas linked to) is not required.