[ViewVC] Annotation of: cvs/AnyEvent-MPV/README

NAME
    AnyEvent::MPV - remote control mpv (https://mpv.io)

SYNOPSIS
       use AnyEvent::MPV;

DESCRIPTION
    This module allows you to remote control mpv (a video player). It also
    is an AnyEvent user, you need to make sure that you use and run a
    supported event loop.

    There are other modules doing this, and I haven't looked much at them
    other than to decide that they don't handle encodings correctly, and
    since none of them use AnyEvent, I wrote my own. When in doubt, have a
    look at them, too.

    Knowledge of the mpv command interface
    <https://mpv.io/manual/stable/#command-interface> is required to use
    this module.

    Features of this module are:

    uses AnyEvent, so integrates well into most event-based programs
    supports asynchronous and synchronous operation
    allows you to properly pass binary filenames
    accepts data encoded in any way (does not crash when mpv replies with
    non UTF-8 data)
    features a simple keybind/event system

  OVERVIEW OF OPERATION
    This module forks an mpv process and uses --input-ipc-client (or
    equivalent) to create a bidirectional communication channel between it
    and the mpv process.

    It then speaks the somewhat JSON-looking (but not really being JSON)
    protocol that mpv implements to both send it commands, decode and handle
    replies, and handle asynchronous events.

    Here is a very simple client:

       use AnyEvent;
       use AnyEvent::MPV;
   
       my $videofile = "./xyzzy.mp4";

       my $mpv = AnyEvent::MPV->new (trace => 1);

       $mpv->start ("--", $videofile);

       my $timer = AE::timer 2, 0, my $quit = AE::cv;
       $quit->recv;

    This starts mpv with the two arguments "--" and $videofile, which it
    should load and play. It then waits two seconds by starting a timer and
    quits. The "trace" argument to the constructor makes mpv more verbose
    and also prints the commands and responses, so you can have an idea what
    is going on.

    In my case, the above example would output something like this:

       [uosc] Disabled because original osc is enabled!
       mpv> {"event":"start-file","playlist_entry_id":1}
       mpv> {"event":"tracks-changed"}
        (+) Video --vid=1 (*) (h264 480x480 30.000fps)
       mpv> {"event":"metadata-update"}
       mpv> {"event":"file-loaded"}
       Using hardware decoding (nvdec).
       mpv> {"event":"video-reconfig"}
       VO: [gpu] 480x480 cuda[nv12]
       mpv> {"event":"video-reconfig"}
       mpv> {"event":"playback-restart"}

    This is not usually very useful (you could just run mpv as a simple
    shell command), so let us load the file at runtime:

       use AnyEvent;
       use AnyEvent::MPV;
   
       my $videofile = "./xyzzy.mp4";

       my $mpv = AnyEvent::MPV->new (
          trace => 1,
          args  => ["--pause", "--idle=yes"],
       );

       $mpv->start;
       $mpv->cmd_recv (loadfile => $mpv->escape_binary ($videofile));
       $mpv->cmd ("set", "pause", "no");

       my $timer = AE::timer 2, 0, my $quit = AE::cv;
       $quit->recv;

    This specifies extra arguments in the constructor - these arguments are
    used every time you "->start" mpv, while the arguments to "->start" are
    only used for this specific clal to0 "start". The argument --pause keeps
    mpv in pause mode (i.e. it does not play the file after loading it), and
    "--idle=yes" tells mpv to not quit when it does not have a playlist - as
    no files are specified on the command line.

    To load a file, we then send it a "loadfile" command, which accepts, as
    first argument, the URL or path to a video file. To make sure mpv does
    not misinterpret the path as a URL, it was prefixed with ./ (similarly
    to "protecting" paths in perls "open").

    Since commands send *to* mpv are send in UTF-8, we need to escape the
    filename (which might be in any encoding) using the "esscape_binary"
    method - this is not needed if your filenames are just ascii, or
    magically get interpreted correctly, but if you accept arbitrary
    filenamews (e.g. from the user), you need to do this.

    The "cmd_recv" method then queues the command, waits for a reply and
    returns the reply data (or croaks on error). mpv would, at this point,
    load the file and, if everything was successful, show the first frame
    and pause. Note that, since mpv is implement rather synchronously
    itself, do not expect commands to fail in many circumstances - for
    example, fit he file does not exit, you will likely get an event, but
    the "loadfile" command itself will run successfully.

    To unpause, we send another command, "set", to set the "pause" property
    to "no", this time using the "cmd" method, which queues the command, but
    instead of waiting for a reply, it immediately returns a condvar that
    cna be used to receive results.

    This should then cause mpv to start playing the video.

    It then again waits two seconds and quits.

    Now, just waiting two seconds is rather, eh, unuseful, so let's look at
    receiving events (using a somewhat embellished example):

       use AnyEvent;
       use AnyEvent::MPV;
   
       my $videofile = "xyzzy.mp4";

       my $quit = AE::cv;

       my $mpv = AnyEvent::MPV->new (
          trace => 1,
          args  => ["--pause", "--idle=yes"],
          on_event => sub {
             my ($mpv, $event, $data) = @_;

             if ($event eq "start-file") {
                $mpv->cmd ("set", "pause", "no");
             } elsif ($event eq "end-file") {
                print "end-file<$data->{reason}>\n";
                $quit->send;
             }
          },
       );

       $mpv->start;
       $mpv->cmd (loadfile => $mpv->escape_binary ($videofile));

       $quit->recv;

    This example uses a global condvar $quit to wait for the file to finish
    playing. Also, most of the logic is now in an "on_event" callback, which
    receives an event name and the actual event object.

    The two events we handle are "start-file", which is emitted by mpv once
    it has loaded a new file, and "end-file", which signals the end of a
    file.

    In the former event, we again set the "pause" property to "no" so the
    movie starts playing. For the latter event, we tell the main program to
    quit by invoking $quit.

    This should conclude the basics of operation. There are a few more
    examples later in the documentation.

  ENCODING CONVENTIONS
    As a rule of thumb, all data you pass to this module to be sent to mpv
    is expected to be in unicode. To pass something that isn't, you need to
    escape it using "escape_binary".

    Data received from $mpv, however, is *not* decoded to unicode, as data
    returned by mpv is not generally encoded in unicode, and the encoding is
    usually unspecified. So if you receive data and expect it to be in
    unicode, you need to first decode it from UTF-8, but note that this
    might fail. This is not a limitation of this module - mpv simply does
    not specify nor guarantee a specific encoding, or any encoding at all,
    in its protocol.

  METHODS
    $mpv = AnyEvent::MPV->new (key => value...)
        Creates a new "mpv" object, but does not yet do anything. The
        support key-value pairs are:

        mpv => $path
            The path to the mpv binary to use - by default, "mpv" is used
            and therefore, uses your "PATH" to find it.

        args => [...]
            Arguments to pass to mpv. These arguments are passed after the
            hardcoded arguments used by this module, but before the
            arguments passed ot "start". It does not matter whether you
            specify your arguments using this key, or in the "start" call,
            but when you invoke mpv multiple times, typically the arguments
            used for all invocations go here, while arguments used for
            specific invocations (e..g filenames) are passed to "start".

        trace => false|true|coderef
            Enables tracing if true. In trace mode, output from mpv is
            printed to standard error using a "mpv>" prefix, and commands
            sent to mpv are printed with a ">mpv" prefix.

            If a code reference is passed, then instead of printing to
            standard errort, this coderef is invoked with a first arfgument
            being either "mpv>" or ">mpv", and the second argument being a
            string to display. The default implementation simply does this:

               sub {
                  warn "$_[0] $_[1]\n";
               }

        on_eof => $coderef->($mpv)
        on_event => $coderef->($mpv, $event, $data)
        on_key => $coderef->($mpv, $string)
            These are invoked by the default method implementation of the
            same name - see below.

    $string = $mpv->escape_binary ($string)
        This module excects all command data sent to mpv to be in unicode.
        Some things are not, such as filenames. To pass binary data such as
        filenames through a comamnd, you need to escape it using this
        method.

        The simplest example is a "loadfile" command:

           $mpv->cmd_recv (loadfile => $mpv->escape_binary ($path));

    $started = $mpv->start (argument...)
        Starts mpv, passing the given arguemnts as extra arguments to mpv.
        If mpv is already running, it returns false, otherwise it returns a
        true value, so you can easily start mpv on demand by calling "start"
        just before using it, and if it is already running, it will not be
        started again.

        The arguments passwd to mpv are a set of hardcoded built-in
        arguments, followed by the arguments specified in the constructor,
        followed by the arguments passwd to this method. The built-in
        arguments currently are --no-input-terminal, --really-quiet (or
        --quiet in "trace" mode), and "--input-ipc-client" (or equivalent).

        Some commonly used and/or even useful arguments you might want to
        pass are:

        --idle=yes or --idle=once to keep mpv from quitting when you don't
        specify a file to play.
        --pause, to keep mpv from instantly starting to play a file, in case
        you want to inspect/change properties first.
        --force-window=no (or similar), to keep mpv from instantly opening a
        window, or to force it to do so.
        --audio-client-name=yourappname, to make sure audio streams are
        associated witht eh right program.
        --wid=id, to embed mpv into another application.
        --no-terminal, --no-input-default-bindings, --no-input-cursor,
        --input-conf=/dev/null, --input-vo-keyboard=no - to ensure only you
        control input.

        The return value can be used to decide whether mpv needs
        initializing:

           if ($mpv->start) {
              $mpv->bind_key (...);
              $mpv->cmd (set => property => value);
              ...
           }

        You can immediately starting sending commands when this method
        returns, even if mpv has not yet started.

    $mpv->stop
        Ensures that mpv is being stopped, by killing mpv with a "TERM"
        signal if needed. After this, you can "->start" a new instance
        again.

    $mpv->on_eof
        This method is called when mpv quits - usually unexpectedly. The
        default implementation will call the "on_eof" code reference
        specified in the constructor, or do nothing if none was given.

        For subclassing, see *SUBCLASSING*, below.

    $mpv->on_event ($event, $data)
        This method is called when mpv sends an asynchronous event. The
        default implementation will call the "on_event" code reference
        specified in the constructor, or do nothing if none was given.

        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 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.

    $mpv->on_key ($string)
        Invoked when a key declared by "->bind_key" is pressed. The default
        invokes the "on_key" code reference specified in the constructor
        with the $mpv object and the key name as arguments, or do nothing if
        none was given.

        For more details and examples, see the "bind_key" method.

        For subclassing, see *SUBCLASSING*, below.

    $mpv->cmd ($command => $arg, $arg...)
        Queues a command to be sent to mpv, using the given arguments, and
        immediately return a condvar.

        See the mpv documentation
        <https://mpv.io/manual/stable/#list-of-input-commands> for details
        on individual commands.

        The condvar can be ignored:

           $mpv->cmd (set_property => "deinterlace", "yes");

        Or it can be used to synchronously wait for the command results:

           $cv = $mpv->cmd (get_property => "video-format");
           $format = $cv->recv;

           # or simpler:

           $format = $mpv->cmd (get_property => "video-format")->recv;

           # or even simpler:

           $format = $mpv->cmd_recv (get_property => "video-format");

        Or you can set a callback:

           $cv = $mpv->cmd (get_property => "video-format");
           $cv->cb (sub {
              my $format = $_[0]->recv;
           });

        On error, the condvar will croak when "recv" is called.

    $result = $mpv->cmd_recv ($command => $arg, $arg...)
        The same as calling "cmd" and immediately "recv" on its return
        value. Useful when you don't want to mess with mpv asynchronously or
        simply needs to have the result:

           $mpv->cmd_recv ("stop");
           $position = $mpv->cmd_recv ("get_property", "playback-time");

    $mpv->bind_key ($INPUT => $string)
        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 to the "on_key"
        handle when the key is proessed, e.g.:

           my $mpv = AnyEvent::MPV->new (
              on_key => sub {
                 my ($mpv, $key) = @_;

                 if ($key eq "letmeout") {
                    print "user pressed escape\n";
                 }
              },
           );

           $mpv_>bind_key (ESC => "letmeout");

        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
    in the object. If you want to subclass to provide your own "on_*"
    methods, be my guest and rummage around in the internals as much as you
    wish - the only guarantee that this module dcoes is that it will not use
    keys with double colons in the name, so youc an use those, or chose to
    simply not care and deal with the breakage.

    If you don't want to go to the effort of subclassing this module, you
    can also specify all event handlers as constructor keys.

SEE ALSO
    AnyEvent, the mpv command documentation
    <https://mpv.io/manual/stable/#command-interface>.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.3
Committed:	Mon Mar 20 12:31:31 2023 UTC (13 months, 4 weeks ago) by root
Branch:	MAIN
CVS Tags:	rel-0_2
Changes since 1.2:	+53 -4 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2			AnyEvent::MPV - remote control mpv (https://mpv.io)
3
4			SYNOPSIS
5			use AnyEvent::MPV;
6
7			DESCRIPTION
8	root	1.2	This module allows you to remote control mpv (a video player). It also
9			is an AnyEvent user, you need to make sure that you use and run a
10			supported event loop.
11
12			There are other modules doing this, and I haven't looked much at them
13			other than to decide that they don't handle encodings correctly, and
14			since none of them use AnyEvent, I wrote my own. When in doubt, have a
15			look at them, too.
16
17			Knowledge of the mpv command interface
18			<https://mpv.io/manual/stable/#command-interface> is required to use
19			this module.
20
21			Features of this module are:
22
23			uses AnyEvent, so integrates well into most event-based programs
24			supports asynchronous and synchronous operation
25			allows you to properly pass binary filenames
26			accepts data encoded in any way (does not crash when mpv replies with
27			non UTF-8 data)
28			features a simple keybind/event system
29
30			OVERVIEW OF OPERATION
31			This module forks an mpv process and uses --input-ipc-client (or
32			equivalent) to create a bidirectional communication channel between it
33			and the mpv process.
34
35			It then speaks the somewhat JSON-looking (but not really being JSON)
36			protocol that mpv implements to both send it commands, decode and handle
37			replies, and handle asynchronous events.
38
39			Here is a very simple client:
40
41			use AnyEvent;
42			use AnyEvent::MPV;
43
44			my $videofile = "./xyzzy.mp4";
45
46			my $mpv = AnyEvent::MPV->new (trace => 1);
47
48			$mpv->start ("--", $videofile);
49
50			my $timer = AE::timer 2, 0, my $quit = AE::cv;
51			$quit->recv;
52
53			This starts mpv with the two arguments "--" and $videofile, which it
54			should load and play. It then waits two seconds by starting a timer and
55			quits. The "trace" argument to the constructor makes mpv more verbose
56			and also prints the commands and responses, so you can have an idea what
57			is going on.
58
59			In my case, the above example would output something like this:
60
61			[uosc] Disabled because original osc is enabled!
62			mpv> {"event":"start-file","playlist_entry_id":1}
63			mpv> {"event":"tracks-changed"}
64			(+) Video --vid=1 (*) (h264 480x480 30.000fps)
65			mpv> {"event":"metadata-update"}
66			mpv> {"event":"file-loaded"}
67			Using hardware decoding (nvdec).
68			mpv> {"event":"video-reconfig"}
69			VO: [gpu] 480x480 cuda[nv12]
70			mpv> {"event":"video-reconfig"}
71			mpv> {"event":"playback-restart"}
72
73			This is not usually very useful (you could just run mpv as a simple
74			shell command), so let us load the file at runtime:
75
76			use AnyEvent;
77			use AnyEvent::MPV;
78
79			my $videofile = "./xyzzy.mp4";
80
81			my $mpv = AnyEvent::MPV->new (
82			trace => 1,
83			args => ["--pause", "--idle=yes"],
84			);
85
86			$mpv->start;
87			$mpv->cmd_recv (loadfile => $mpv->escape_binary ($videofile));
88			$mpv->cmd ("set", "pause", "no");
89
90			my $timer = AE::timer 2, 0, my $quit = AE::cv;
91			$quit->recv;
92
93			This specifies extra arguments in the constructor - these arguments are
94			used every time you "->start" mpv, while the arguments to "->start" are
95			only used for this specific clal to0 "start". The argument --pause keeps
96			mpv in pause mode (i.e. it does not play the file after loading it), and
97			"--idle=yes" tells mpv to not quit when it does not have a playlist - as
98			no files are specified on the command line.
99
100			To load a file, we then send it a "loadfile" command, which accepts, as
101			first argument, the URL or path to a video file. To make sure mpv does
102			not misinterpret the path as a URL, it was prefixed with ./ (similarly
103			to "protecting" paths in perls "open").
104
105			Since commands send to mpv are send in UTF-8, we need to escape the
106			filename (which might be in any encoding) using the "esscape_binary"
107			method - this is not needed if your filenames are just ascii, or
108			magically get interpreted correctly, but if you accept arbitrary
109			filenamews (e.g. from the user), you need to do this.
110
111			The "cmd_recv" method then queues the command, waits for a reply and
112			returns the reply data (or croaks on error). mpv would, at this point,
113			load the file and, if everything was successful, show the first frame
114			and pause. Note that, since mpv is implement rather synchronously
115			itself, do not expect commands to fail in many circumstances - for
116			example, fit he file does not exit, you will likely get an event, but
117			the "loadfile" command itself will run successfully.
118
119			To unpause, we send another command, "set", to set the "pause" property
120			to "no", this time using the "cmd" method, which queues the command, but
121			instead of waiting for a reply, it immediately returns a condvar that
122			cna be used to receive results.
123
124			This should then cause mpv to start playing the video.
125
126			It then again waits two seconds and quits.
127
128			Now, just waiting two seconds is rather, eh, unuseful, so let's look at
129			receiving events (using a somewhat embellished example):
130
131			use AnyEvent;
132			use AnyEvent::MPV;
133
134			my $videofile = "xyzzy.mp4";
135
136			my $quit = AE::cv;
137
138			my $mpv = AnyEvent::MPV->new (
139			trace => 1,
140			args => ["--pause", "--idle=yes"],
141			on_event => sub {
142			my ($mpv, $event, $data) = @_;
143
144			if ($event eq "start-file") {
145			$mpv->cmd ("set", "pause", "no");
146			} elsif ($event eq "end-file") {
147			print "end-file<$data->{reason}>\n";
148			$quit->send;
149			}
150			},
151			);
152
153			$mpv->start;
154			$mpv->cmd (loadfile => $mpv->escape_binary ($videofile));
155
156			$quit->recv;
157
158			This example uses a global condvar $quit to wait for the file to finish
159			playing. Also, most of the logic is now in an "on_event" callback, which
160			receives an event name and the actual event object.
161
162			The two events we handle are "start-file", which is emitted by mpv once
163			it has loaded a new file, and "end-file", which signals the end of a
164			file.
165
166			In the former event, we again set the "pause" property to "no" so the
167			movie starts playing. For the latter event, we tell the main program to
168			quit by invoking $quit.
169
170			This should conclude the basics of operation. There are a few more
171			examples later in the documentation.
172
173			ENCODING CONVENTIONS
174			As a rule of thumb, all data you pass to this module to be sent to mpv
175			is expected to be in unicode. To pass something that isn't, you need to
176			escape it using "escape_binary".
177
178			Data received from $mpv, however, is not decoded to unicode, as data
179			returned by mpv is not generally encoded in unicode, and the encoding is
180			usually unspecified. So if you receive data and expect it to be in
181			unicode, you need to first decode it from UTF-8, but note that this
182			might fail. This is not a limitation of this module - mpv simply does
183			not specify nor guarantee a specific encoding, or any encoding at all,
184			in its protocol.
185
186			METHODS
187			$mpv = AnyEvent::MPV->new (key => value...)
188			Creates a new "mpv" object, but does not yet do anything. The
189			support key-value pairs are:
190
191			mpv => $path
192			The path to the mpv binary to use - by default, "mpv" is used
193			and therefore, uses your "PATH" to find it.
194
195			args => [...]
196			Arguments to pass to mpv. These arguments are passed after the
197			hardcoded arguments used by this module, but before the
198			arguments passed ot "start". It does not matter whether you
199			specify your arguments using this key, or in the "start" call,
200			but when you invoke mpv multiple times, typically the arguments
201			used for all invocations go here, while arguments used for
202			specific invocations (e..g filenames) are passed to "start".
203
204			trace => false\|true\|coderef
205			Enables tracing if true. In trace mode, output from mpv is
206			printed to standard error using a "mpv>" prefix, and commands
207			sent to mpv are printed with a ">mpv" prefix.
208
209			If a code reference is passed, then instead of printing to
210			standard errort, this coderef is invoked with a first arfgument
211			being either "mpv>" or ">mpv", and the second argument being a
212			string to display. The default implementation simply does this:
213
214			sub {
215			warn "$_[0] $_[1]\n";
216			}
217
218			on_eof => $coderef->($mpv)
219			on_event => $coderef->($mpv, $event, $data)
220			on_key => $coderef->($mpv, $string)
221			These are invoked by the default method implementation of the
222			same name - see below.
223
224			$string = $mpv->escape_binary ($string)
225			This module excects all command data sent to mpv to be in unicode.
226			Some things are not, such as filenames. To pass binary data such as
227			filenames through a comamnd, you need to escape it using this
228			method.
229
230			The simplest example is a "loadfile" command:
231
232			$mpv->cmd_recv (loadfile => $mpv->escape_binary ($path));
233
234			$started = $mpv->start (argument...)
235			Starts mpv, passing the given arguemnts as extra arguments to mpv.
236			If mpv is already running, it returns false, otherwise it returns a
237			true value, so you can easily start mpv on demand by calling "start"
238			just before using it, and if it is already running, it will not be
239			started again.
240
241			The arguments passwd to mpv are a set of hardcoded built-in
242			arguments, followed by the arguments specified in the constructor,
243			followed by the arguments passwd to this method. The built-in
244			arguments currently are --no-input-terminal, --really-quiet (or
245			--quiet in "trace" mode), and "--input-ipc-client" (or equivalent).
246
247			Some commonly used and/or even useful arguments you might want to
248			pass are:
249
250			--idle=yes or --idle=once to keep mpv from quitting when you don't
251			specify a file to play.
252			--pause, to keep mpv from instantly starting to play a file, in case
253			you want to inspect/change properties first.
254			--force-window=no (or similar), to keep mpv from instantly opening a
255			window, or to force it to do so.
256			--audio-client-name=yourappname, to make sure audio streams are
257			associated witht eh right program.
258			--wid=id, to embed mpv into another application.
259			--no-terminal, --no-input-default-bindings, --no-input-cursor,
260			--input-conf=/dev/null, --input-vo-keyboard=no - to ensure only you
261			control input.
262
263			The return value can be used to decide whether mpv needs
264			initializing:
265
266			if ($mpv->start) {
267			$mpv->bind_key (...);
268			$mpv->cmd (set => property => value);
269			...
270			}
271
272			You can immediately starting sending commands when this method
273			returns, even if mpv has not yet started.
274
275			$mpv->stop
276			Ensures that mpv is being stopped, by killing mpv with a "TERM"
277			signal if needed. After this, you can "->start" a new instance
278			again.
279
280			$mpv->on_eof
281			This method is called when mpv quits - usually unexpectedly. The
282			default implementation will call the "on_eof" code reference
283			specified in the constructor, or do nothing if none was given.
284
285			For subclassing, see SUBCLASSING, below.
286
287			$mpv->on_event ($event, $data)
288			This method is called when mpv sends an asynchronous event. The
289			default implementation will call the "on_event" code reference
290			specified in the constructor, or do nothing if none was given.
291
292			The first/implicit argument is the $mpv object, the second is the
293			event name (same as "$data->{event}", purely for convenience), and
294	root	1.3	the third argument is the event object as sent by mpv (sans "event"
295			key). See List of events
296			<https://mpv.io/manual/stable/#list-of-events> in its documentation.
297	root	1.2
298			For subclassing, see SUBCLASSING, below.
299
300			$mpv->on_key ($string)
301			Invoked when a key declared by "->bind_key" is pressed. The default
302			invokes the "on_key" code reference specified in the constructor
303			with the $mpv object and the key name as arguments, or do nothing if
304			none was given.
305
306			For more details and examples, see the "bind_key" method.
307
308			For subclassing, see SUBCLASSING, below.
309
310			$mpv->cmd ($command => $arg, $arg...)
311			Queues a command to be sent to mpv, using the given arguments, and
312			immediately return a condvar.
313
314			See the mpv documentation
315			<https://mpv.io/manual/stable/#list-of-input-commands> for details
316			on individual commands.
317
318			The condvar can be ignored:
319
320			$mpv->cmd (set_property => "deinterlace", "yes");
321
322			Or it can be used to synchronously wait for the command results:
323
324			$cv = $mpv->cmd (get_property => "video-format");
325			$format = $cv->recv;
326
327			# or simpler:
328
329			$format = $mpv->cmd (get_property => "video-format")->recv;
330
331			# or even simpler:
332
333			$format = $mpv->cmd_recv (get_property => "video-format");
334
335			Or you can set a callback:
336
337			$cv = $mpv->cmd (get_property => "video-format");
338			$cv->cb (sub {
339			my $format = $_[0]->recv;
340			});
341
342			On error, the condvar will croak when "recv" is called.
343
344			$result = $mpv->cmd_recv ($command => $arg, $arg...)
345			The same as calling "cmd" and immediately "recv" on its return
346			value. Useful when you don't want to mess with mpv asynchronously or
347			simply needs to have the result:
348
349			$mpv->cmd_recv ("stop");
350			$position = $mpv->cmd_recv ("get_property", "playback-time");
351
352			$mpv->bind_key ($INPUT => $string)
353			This is an extension implement by this module to make it easy to get
354			key events. The way this is implemented is to bind a
355			"client-message" witha first argument of "AnyEvent::MPV" and the
356	root	1.3	$string you passed. This $string is then passed to the "on_key"
357	root	1.2	handle when the key is proessed, e.g.:
358
359			my $mpv = AnyEvent::MPV->new (
360			on_key => sub {
361			my ($mpv, $key) = @_;
362
363			if ($key eq "letmeout") {
364			print "user pressed escape\n";
365			}
366			},
367			);
368
369			$mpv_>bind_key (ESC => "letmeout");
370
371			The key configuration is lost when mpv is stopped and must be
372			(re-)done after every "start".
373
374	root	1.3	[$guard] = $mpv->observe_property ($name => $coderef->($mpv, $name,
375			$value))
376			[$guard] = $mpv->observe_property_string ($name => $coderef->($mpv,
377			$name, $value))
378			These methods wrap a registry system around mpv's "observe_property"
379			and "observe_property_string" commands - every time the named
380			property changes, the coderef is invoked with the $mpv object, the
381			name of the property and the new value.
382
383			For a list of properties that you can observe, see the mpv
384			documentation <https://mpv.io/manual/stable/#property-list>.
385
386			Due to the (sane :) way mpv handles these requests, you will always
387			get a property cxhange event right after registering an observer
388			(meaning you don't have to query the current value), and it is also
389			possible to register multiple observers for the same property - they
390			will all be handled properly.
391
392			When called in void context, the observer stays in place until mpv
393			is stopped. In any otrher context, these methods return a guard
394			object that, when it goes out of scope, unregisters the observe
395			using "unobserve_property".
396
397			Internally, this method uses observer ids of 2**52
398			(0x10000000000000) or higher - it will not interfere with lower
399			ovserver ids, so it is possible to completely ignore this system and
400			execute "observe_property" commands yourself, whilst listening to
401			"property-change" events - as long as your ids stay below 2**52.
402
403			Example: register observers for changtes in "aid" and "sid". Note
404			that a dummy statement is added to make sure the method is called in
405			void context.
406
407			sub register_observers {
408			my ($mpv) = @_;
409
410			$mpv->observe_property (aid => sub {
411			my ($mpv, $name, $value) = @_;
412			print "property aid (=$name) has changed to $value\n";
413			});
414
415			$mpv->observe_property (sid => sub {
416			my ($mpv, $name, $value) = @_;
417			print "property sid (=$name) has changed to $value\n";
418			});
419
420			() # ensure the above method is called in void context
421			}
422
423	root	1.2	SUBCLASSING
424			Like most perl objects, "AnyEvent::MPV" objects are implemented as
425			hashes, with the constructor simply storing all passed key-value pairs
426			in the object. If you want to subclass to provide your own "on_*"
427			methods, be my guest and rummage around in the internals as much as you
428			wish - the only guarantee that this module dcoes is that it will not use
429			keys with double colons in the name, so youc an use those, or chose to
430			simply not care and deal with the breakage.
431
432			If you don't want to go to the effort of subclassing this module, you
433			can also specify all event handlers as constructor keys.
434	root	1.1
435			SEE ALSO
436	root	1.2	AnyEvent, the mpv command documentation
437			<https://mpv.io/manual/stable/#command-interface>.
438	root	1.1
439			AUTHOR
440			Marc Lehmann <schmorp@schmorp.de>
441			http://home.schmorp.de/
442