--- AnyEvent-MPV/README	2023/03/19 23:26:01	1.2
+++ AnyEvent-MPV/README	2023/03/20 12:31:31	1.3
@@ -291,9 +291,9 @@
 
         The first/implicit argument is the $mpv object, the second is the
         event name (same as "$data->{event}", purely for convenience), and
-        the third argument is the full event object as sent by mpv. See List
-        of events <https://mpv.io/manual/stable/#list-of-events> in its
-        documentation.
+        the third argument is the event object as sent by mpv (sans "event"
+        key). See List of events
+        <https://mpv.io/manual/stable/#list-of-events> in its documentation.
 
         For subclassing, see *SUBCLASSING*, below.
 
@@ -353,7 +353,7 @@
         This is an extension implement by this module to make it easy to get
         key events. The way this is implemented is to bind a
         "client-message" witha first argument of "AnyEvent::MPV" and the
-        $string you passed. This $string is then passed ot the "on_key"
+        $string you passed. This $string is then passed to the "on_key"
         handle when the key is proessed, e.g.:
 
            my $mpv = AnyEvent::MPV->new (
@@ -371,6 +371,55 @@
         The key configuration is lost when mpv is stopped and must be
         (re-)done after every "start".
 
+    [$guard] = $mpv->observe_property ($name => $coderef->($mpv, $name,
+    $value))
+    [$guard] = $mpv->observe_property_string ($name => $coderef->($mpv,
+    $name, $value))
+        These methods wrap a registry system around mpv's "observe_property"
+        and "observe_property_string" commands - every time the named
+        property changes, the coderef is invoked with the $mpv object, the
+        name of the property and the new value.
+
+        For a list of properties that you can observe, see the mpv
+        documentation <https://mpv.io/manual/stable/#property-list>.
+
+        Due to the (sane :) way mpv handles these requests, you will always
+        get a property cxhange event right after registering an observer
+        (meaning you don't have to query the current value), and it is also
+        possible to register multiple observers for the same property - they
+        will all be handled properly.
+
+        When called in void context, the observer stays in place until mpv
+        is stopped. In any otrher context, these methods return a guard
+        object that, when it goes out of scope, unregisters the observe
+        using "unobserve_property".
+
+        Internally, this method uses observer ids of 2**52
+        (0x10000000000000) or higher - it will not interfere with lower
+        ovserver ids, so it is possible to completely ignore this system and
+        execute "observe_property" commands yourself, whilst listening to
+        "property-change" events - as long as your ids stay below 2**52.
+
+        Example: register observers for changtes in "aid" and "sid". Note
+        that a dummy statement is added to make sure the method is called in
+        void context.
+
+           sub register_observers {
+              my ($mpv) = @_;
+
+              $mpv->observe_property (aid => sub {
+                 my ($mpv, $name, $value) = @_;
+                 print "property aid (=$name) has changed to $value\n";
+              });
+
+              $mpv->observe_property (sid => sub {
+                 my ($mpv, $name, $value) = @_;
+                 print "property sid (=$name) has changed to $value\n";
+              });
+
+              () # ensure the above method is called in void context
+           }
+
   SUBCLASSING
     Like most perl objects, "AnyEvent::MPV" objects are implemented as
     hashes, with the constructor simply storing all passed key-value pairs