diff --git a/DOCS/interface-changes/keybind-cancel.txt b/DOCS/interface-changes/keybind-cancel.txt
new file mode 100644
index 0000000000000..ab137a0cb4016
--- /dev/null
+++ b/DOCS/interface-changes/keybind-cancel.txt
@@ -0,0 +1,2 @@
+change `mp.add_key_binding` so that by default, the callback is not invoked if the event is canceled; clients should now use the `complex` option to detect this situation
+add `canceled` entry to `mp.add_key_binding` callback argument
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index e8065d9a1ac77..1d8959696c7cc 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -292,6 +292,9 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
     After calling this function, key presses will cause the function ``fn`` to
     be called (unless the user remapped the key with another binding).
+    However, if the key binding is canceled (e.g. the key is logically released
+    but not physically released), the function will not be called, unless
+    ``complex`` flag is set to ``true``.
 
     The ``name`` argument should be a short symbolic string. It allows the user
     to remap the key binding via input.conf using the ``script-message``
@@ -321,7 +324,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with
                     tracked).
 
                 ``is_mouse``
-                    Boolean Whether the event was caused by a mouse button.
+                    Boolean: Whether the event was caused by a mouse button.
+
+                ``canceled``
+                    Boolean: Whether the event was canceled.
+                    Not all types of cancellations set this flag.
 
                 ``key_name``
                     The name of they key that triggered this, or ``nil`` if
diff --git a/player/lua/defaults.lua b/player/lua/defaults.lua
index 5f0ced76a5ce5..0dc6cc8624340 100644
--- a/player/lua/defaults.lua
+++ b/player/lua/defaults.lua
@@ -207,6 +207,7 @@ local function add_binding(attrs, key, name, fn, rp)
             fn({
                 event = key_states[state:sub(1, 1)] or "unknown",
                 is_mouse = state:sub(2, 2) == "m",
+                canceled = state:sub(3, 3) == "c",
                 key_name = key_name,
                 key_text = key_text,
             })
@@ -222,7 +223,8 @@ local function add_binding(attrs, key, name, fn, rp)
             -- Also, key repeat triggers the binding again.
             local event = state:sub(1, 1)
             local is_mouse = state:sub(2, 2) == "m"
-            if event == "r" and not repeatable then
+            local canceled = state:sub(3, 3) == "c"
+            if canceled or event == "r" and not repeatable then
                 return
             end
             if is_mouse and (event == "u" or event == "p") then