ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MPV/README
(Generate patch)

Comparing AnyEvent-MPV/README (file contents):
Revision 1.1 by root, Sun Mar 19 19:36:40 2023 UTC vs.
Revision 1.2 by root, Sun Mar 19 23:26:01 2023 UTC

… …
3 3
4SYNOPSIS 4SYNOPSIS
5 use AnyEvent::MPV; 5 use AnyEvent::MPV;
6 6
7DESCRIPTION 7DESCRIPTION
8 This module allows you to remote control mpv (a video player). It also
8 This module is an AnyEvent user, you need to make sure that you use and 9 is an AnyEvent user, you need to make sure that you use and run a
9 run a supported event loop. 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 the third argument is the full event object as sent by mpv. See List
295 of events <https://mpv.io/manual/stable/#list-of-events> in its
296 documentation.
297
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 $string you passed. This $string is then passed ot the "on_key"
357 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 SUBCLASSING
375 Like most perl objects, "AnyEvent::MPV" objects are implemented as
376 hashes, with the constructor simply storing all passed key-value pairs
377 in the object. If you want to subclass to provide your own "on_*"
378 methods, be my guest and rummage around in the internals as much as you
379 wish - the only guarantee that this module dcoes is that it will not use
380 keys with double colons in the name, so youc an use those, or chose to
381 simply not care and deal with the breakage.
382
383 If you don't want to go to the effort of subclassing this module, you
384 can also specify all event handlers as constructor keys.
10 385
11SEE ALSO 386SEE ALSO
12 AnyEvent. 387 AnyEvent, the mpv command documentation
388 <https://mpv.io/manual/stable/#command-interface>.
13 389
14AUTHOR 390AUTHOR
15 Marc Lehmann <schmorp@schmorp.de> 391 Marc Lehmann <schmorp@schmorp.de>
16 http://home.schmorp.de/ 392 http://home.schmorp.de/
17 393

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines