[ViewVC] Diff of: cvs/AnyEvent-MPV/MPV.pm

Comparing AnyEvent-MPV/MPV.pm (file contents):
Revision 1.5 by root, Sun Mar 19 23:13:25 2023 UTC vs.
Revision 1.20 by root, Sat Apr 1 06:32:32 2023 UTC

…		…
3	AnyEvent::MPV - remote control mpv (https://mpv.io)	3	AnyEvent::MPV - remote control mpv (https://mpv.io)
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use AnyEvent::MPV;	7	use AnyEvent::MPV;
		8
		9	my $videofile = "path/to/file.mkv";
		10	use AnyEvent;
		11	my $mpv = AnyEvent::MPV->new (trace => 1);
		12	$mpv->start ("--idle=yes");
		13	$mpv->cmd (loadfile => $mpv->escape_binary ($videofile));
		14	my $quit = AE::cv;
		15	$mpv->register_event (end_file => $quit);
		16	$quit->recv;
		17
8		18
9	=head1 DESCRIPTION	19	=head1 DESCRIPTION
10		20
11	This module allows you to remote control F<mpv> (a video player). It also	21	This module allows you to remote control F<mpv> (a video player). It also
12	is an L<AnyEvent> user, you need to make sure that you use and run a	22	is an L<AnyEvent> user, you need to make sure that you use and run a
…		…
50	Here is a very simple client:	60	Here is a very simple client:
51		61
52	use AnyEvent;	62	use AnyEvent;
53	use AnyEvent::MPV;	63	use AnyEvent::MPV;
54		64
55	my $videofile = "./xyzzy.mp4";	65	my $videofile = "./xyzzy.mkv";
56		66
57	my $mpv = AnyEvent::MPV->new (trace => 1);	67	my $mpv = AnyEvent::MPV->new (trace => 1);
58		68
59	$mpv->start ("--", $videofile);	69	$mpv->start ("--", $videofile);
60		70
…		…
62	$quit->recv;	72	$quit->recv;
63		73
64	This starts F<mpv> with the two arguments C<--> and C<$videofile>, which	74	This starts F<mpv> with the two arguments C<--> and C<$videofile>, which
65	it should load and play. It then waits two seconds by starting a timer and	75	it should load and play. It then waits two seconds by starting a timer and
66	quits. The C<trace> argument to the constructor makes F<mpv> more verbose	76	quits. The C<trace> argument to the constructor makes F<mpv> more verbose
67	and also prints the commands and responses, so you cna have an idea what	77	and also prints the commands and responses, so you can have an idea what
68	is going on.	78	is going on.
		79
		80	In my case, the above example would output something like this:
		81
		82	[uosc] Disabled because original osc is enabled!
		83	mpv> {"event":"start-file","playlist_entry_id":1}
		84	mpv> {"event":"tracks-changed"}
		85	(+) Video --vid=1 (*) (h264 480x480 30.000fps)
		86	mpv> {"event":"metadata-update"}
		87	mpv> {"event":"file-loaded"}
		88	Using hardware decoding (nvdec).
		89	mpv> {"event":"video-reconfig"}
		90	VO: [gpu] 480x480 cuda[nv12]
		91	mpv> {"event":"video-reconfig"}
		92	mpv> {"event":"playback-restart"}
69		93
70	This is not usually very useful (you could just run F<mpv> as a simple	94	This is not usually very useful (you could just run F<mpv> as a simple
71	shell command), so let us load the file at runtime:	95	shell command), so let us load the file at runtime:
72		96
73	use AnyEvent;	97	use AnyEvent;
74	use AnyEvent::MPV;	98	use AnyEvent::MPV;
75		99
76	my $videofile = "./xyzzy.mp4";	100	my $videofile = "./xyzzy.mkv";
77		101
78	my $mpv = AnyEvent::MPV->new (	102	my $mpv = AnyEvent::MPV->new (
79	trace => 1,	103	trace => 1,
80	args => ["--pause", "--idle=yes"],	104	args => ["--pause", "--idle=yes"],
81	);	105	);
…		…
126	receiving events (using a somewhat embellished example):	150	receiving events (using a somewhat embellished example):
127		151
128	use AnyEvent;	152	use AnyEvent;
129	use AnyEvent::MPV;	153	use AnyEvent::MPV;
130		154
131	my $videofile = "xyzzy.mp4";	155	my $videofile = "xyzzy.mkv";
132		156
133	my $quit = AE::cv;	157	my $quit = AE::cv;
134		158
135	my $mpv = AnyEvent::MPV->new (	159	my $mpv = AnyEvent::MPV->new (
136	trace => 1,	160	trace => 1,
137	args => ["--pause", "--idle=yes"],	161	args => ["--pause", "--idle=yes"],
138	on_event => sub {
139	my ($mpv, $event, $data) = @_;
140
141	if ($event eq "start-file") {
142	$mpv->cmd ("set", "pause", "no");
143	} elsif ($event eq "end-file") {
144	print "end-file<$data->{reason}>\n";
145	$quit->send;
146	}
147	},
148	);	162	);
149		163
150	$mpv->start;	164	$mpv->start;
		165
		166	$mpv->register_event (start_file => sub {
		167	$mpv->cmd ("set", "pause", "no");
		168	});
		169
		170	$mpv->register_event (end_file => sub {
		171	my ($mpv, $event, $data) = @_;
		172
		173	print "end-file<$data->{reason}>\n";
		174	$quit->send;
		175	});
		176
151	$mpv->cmd (loadfile => $mpv->escape_binary ($videofile));	177	$mpv->cmd (loadfile => $mpv->escape_binary ($videofile));
152		178
153	$quit->recv;	179	$quit->recv;
154		180
155	This example uses a global condvar C<$quit> to wait for the file to finish	181	This example uses a global condvar C<$quit> to wait for the file to finish
156	playing. Also, most of the logic is now in an C<on_event> callback, which	182	playing. Also, most of the logic is now implement in event handlers.
157	receives an event name and the actual event object.
158		183
159	The two events we handle are C<start-file>, which is emitted by F<mpv>	184	The two events handlers we register are C<start-file>, which is emitted by
160	once it has loaded a new file, and C<end-file>, which signals the end	185	F<mpv> once it has loaded a new file, and C<end-file>, which signals the
161	of a file.	186	end of a file (underscores are internally replaced by minus signs, so you
		187	cna speicfy event names with either).
162		188
163	In the former event, we again set the C<pause> property to C<no> so the	189	In the C<start-file> event, we again set the C<pause> property to C<no>
164	movie starts playing. For the latter event, we tell the main program to	190	so the movie starts playing. For the C<end-file> event, we tell the main
165	quit by invoking C<$quit>.	191	program to quit by invoking C<$quit>.
166		192
167	This should conclude the basics of operation. There are a few more	193	This should conclude the basics of operation. There are a few more
168	examples later in the documentation.	194	examples later in the documentation.
169		195
170	=head2 ENCODING CONVENTIONS	196	=head2 ENCODING CONVENTIONS
171		197
172	As a rule of thumb, all data you pass to this module to be sent to F<mpv>	198	As a rule of thumb, all data you pass to this module to be sent to F<mpv>
173	is expected to be in unicode. To pass something that isn't, you need to	199	is expected to be in unicode. To pass something that isn't, you need to
174	escape it using C<escape_binary>.	200	escape it using C<escape_binary>.
175		201
176	Data received from C<$mpv>, however, is I<not> decoded to unicode, as data	202	Data received from F<mpv>, however, is I<not> decoded to unicode, as data
177	returned by F<mpv> is not generally encoded in unicode, and the encoding	203	returned by F<mpv> is not generally encoded in unicode, and the encoding
178	is usually unspecified. So if you receive data and expect it to be in	204	is usually unspecified. So if you receive data and expect it to be in
179	unicode, you need to first decode it from UTF-8, but note that this might	205	unicode, you need to first decode it from UTF-8, but note that this might
180	fail. This is not a limitation of this module - F<mpv> simply does not	206	fail. This is not a limitation of this module - F<mpv> simply does not
181	specify nor guarantee a specific encoding, or any encoding at all, in its	207	specify nor guarantee a specific encoding, or any encoding at all, in its
…		…
195	use Scalar::Util ();	221	use Scalar::Util ();
196		222
197	use AnyEvent ();	223	use AnyEvent ();
198	use AnyEvent::Util ();	224	use AnyEvent::Util ();
199		225
		226	our $VERSION = '1.03';
		227
		228	sub OBSID() { 2**52 }
		229
200	our $JSON = eval { require JSON::XS; JSON::XS:: }	230	our $JSON = eval { require JSON::XS; JSON::XS:: }
201	\|\| do { require JSON::PP; JSON::PP:: };	231	\|\| do { require JSON::PP; JSON::PP:: };
202		232
203	our $JSON_CODER =	233	our $JSON_ENCODER = $JSON->new->utf8;
204		234	our $JSON_DECODER = $JSON->new->latin1;
205	our $VERSION = '0.1';
206		235
207	our $mpv_path; # last mpv path used	236	our $mpv_path; # last mpv path used
208	our $mpv_optionlist; # output of mpv --list-options	237	our $mpv_optionlist; # output of mpv --list-options
209		238
210	=item $mpv = AnyEvent::MPV->new (key => value...)	239	=item $mpv = AnyEvent::MPV->new (key => value...)
…		…
367	exit 1;	396	exit 1;
368	}	397	}
369		398
370	$self->{fh} = $fh;	399	$self->{fh} = $fh;
371		400
372	my $trace = delete $self->{trace} \|\| sub { };	401	my $trace = $self->{trace} \|\| sub { };
373		402
374	$trace = sub { warn "$_[0] $_[1]\n" } if $trace && !ref $trace;	403	$trace = sub { warn "$_[0] $_[1]\n" } if $trace && !ref $trace;
375		404
376	my $buf;	405	my $buf;
377	my $wbuf;
378		406
379	Scalar::Util::weaken $self;	407	Scalar::Util::weaken $self;
380		408
381	$self->{rw} = AE::io $fh, 0, sub {	409	$self->{rw} = AE::io $fh, 0, sub {
382	if (sysread $fh, $buf, 8192, length $buf) {	410	if (sysread $fh, $buf, 8192, length $buf) {
383	while ($buf =~ s/^([^\n]+)\n//) {	411	while ($buf =~ s/^([^\n]+)\n//) {
384	$trace->("mpv>" => "$1");	412	$trace->("mpv>" => "$1");
385		413
386	if ("{" eq substr $1, 0, 1) {	414	if ("{" eq substr $1, 0, 1) {
387	eval {	415	eval {
388	my $reply = $JSON->new->latin1->decode ($1);	416	my $reply = $JSON_DECODER->decode ($1);
389		417
390	if (exists $reply->{event}) {	418	if (defined (my $event = delete $reply->{event})) {
391	if (	419	if (
392	$reply->{event} eq "client-message"	420	$event eq "client-message"
393	and $reply->{args}[0] eq "AnyEvent::MPV"	421	and $reply->{args}[0] eq "AnyEvent::MPV"
394	) {	422	) {
395	if ($reply->{args}[1] eq "key") {	423	if ($reply->{args}[1] eq "key") {
396	(my $key = $reply->{args}[2]) =~ s/\\x(..)/chr hex $1/ge;	424	(my $key = $reply->{args}[2]) =~ s/\\x(..)/chr hex $1/ge;
397	$self->on_key ($key);	425	$self->on_key ($key);
398	}	426	}
		427	} elsif (
		428	$event eq "property-change"
		429	and OBSID <= $reply->{id}
		430	) {
		431	if (my $cb = $self->{obscb}{$reply->{id}}) {
		432	$cb->($self, $event, $reply->{data});
		433	}
399	} else {	434	} else {
		435	if (my $cbs = $self->{evtcb}{$event}) {
		436	for my $evtid (keys %$cbs) {
		437	my $cb = $cbs->{$evtid}
		438	or next;
		439	$cb->($self, $event, $reply);
		440	}
		441	}
		442
400	$self->on_event ($reply->{event}, $reply);	443	$self->on_event ($event, $reply);
401	}	444	}
402	} elsif (exists $reply->{request_id}) {	445	} elsif (exists $reply->{request_id}) {
403	my $cv = delete $self->{cmd_cv}{$reply->{request_id}};	446	my $cv = delete $self->{cmdcv}{$reply->{request_id}};
404		447
405	unless ($cv) {	448	unless ($cv) {
406	warn "no cv found for request id <$reply->{request_id}>\n";	449	warn "no cv found for request id <$reply->{request_id}>\n";
407	next;	450	next;
408	}	451	}
…		…
428	$self->stop;	471	$self->stop;
429	$self->on_eof;	472	$self->on_eof;
430	}	473	}
431	};	474	};
432		475
		476	my $wbuf;
		477	my $reqid;
		478
433	$self->{_send} = sub {	479	$self->{_cmd} = sub {
434	$wbuf .= "$_[0]\n";	480	my $cv = AE::cv;
435		481
		482	$self->{cmdcv}{++$reqid} = $cv;
		483
		484	my $cmd = $JSON_ENCODER->encode ({ command => ref $_[0] ? $_[0] : \@_, request_id => $reqid*1 });
		485
		486	# (un-)apply escape_binary hack
		487	$cmd =~ s/\xf4\x8e\x97\x9f(..)/sprintf sprintf "\\x%02x", hex $1/ges; # f48e979f == 10e5df in utf-8
		488
436	$trace->(">mpv" => "$_[0]");	489	$trace->(">mpv" => $cmd);
437		490
438	$self->{ww} \|\|= AE::io $fh, 1, sub {	491	$wbuf .= "$cmd\n";
		492
		493	my $wcb = sub {
439	my $len = syswrite $fh, $wbuf;	494	my $len = syswrite $fh, $wbuf;
440	substr $wbuf, 0, $len, "";	495	substr $wbuf, 0, $len, "";
441	undef $self->{ww} unless length $wbuf;	496	undef $self->{ww} unless length $wbuf;
442	};	497	};
		498
		499	$wcb->();
		500	$self->{ww} \|\|= AE::io $fh, 1, $wcb if length $wbuf;
		501
		502	$cv
443	};	503	};
444		504
445	1	505	1
		506	}
		507
		508	sub DESTROY {
		509	$_[0]->stop;
446	}	510	}
447		511
448	=item $mpv->stop	512	=item $mpv->stop
449		513
450	Ensures that F<mpv> is being stopped, by killing F<mpv> with a C<TERM>	514	Ensures that F<mpv> is being stopped, by killing F<mpv> with a C<TERM>
…		…
465	kill TERM => $self->{pid};	529	kill TERM => $self->{pid};
466		530
467	}	531	}
468		532
469	delete $self->{pid};	533	delete $self->{pid};
470	delete $self->{cmd_cv};	534	delete $self->{cmdcv};
		535	delete $self->{evtid};
		536	delete $self->{evtcb};
		537	delete $self->{obsid};
		538	delete $self->{obscb};
		539	delete $self->{wbuf};
471	}	540	}
472		541
473	=item $mpv->on_eof	542	=item $mpv->on_eof
474		543
475	This method is called when F<mpv> quits - usually unexpectedly. The	544	This method is called when F<mpv> quits - usually unexpectedly. The
…		…
490		559
491	This method is called when F<mpv> sends an asynchronous event. The default	560	This method is called when F<mpv> sends an asynchronous event. The default
492	implementation will call the C<on_event> code reference specified in the	561	implementation will call the C<on_event> code reference specified in the
493	constructor, or do nothing if none was given.	562	constructor, or do nothing if none was given.
494		563
495	The first/implicit argument is the C<$mpv> object, the second is the event	564	The first/implicit argument is the C<$mpv> object, the second is the
496	name (same as C<< $data->{event} >>, purely for convenience), and the	565	event name (same as C<< $data->{event} >>, purely for convenience), and
497	third argument is the full event object as sent by F<mpv>. See L<List of	566	the third argument is the event object as sent by F<mpv> (sans C<event>
498	events\|https://mpv.io/manual/stable/#list-of-events> in its documentation.	567	key). See L<List of events\|https://mpv.io/manual/stable/#list-of-events>
		568	in its documentation.
499		569
500	For subclassing, see I<SUBCLASSING>, below.	570	For subclassing, see I<SUBCLASSING>, below.
501		571
502	=cut	572	=cut
503		573
504	sub on_event {	574	sub on_event {
505	my ($self, $key) = @_;	575	my ($self, $event, $data) = @_;
506		576
507	$self->{on_event}($self, $key) if $self->{on_event};	577	$self->{on_event}($self, $event, $data) if $self->{on_event};
508	}	578	}
509		579
510	=item $mpv->on_key ($string)	580	=item $mpv->on_key ($string)
511		581
512	Invoked when a key declared by C<< ->bind_key >> is pressed. The default	582	Invoked when a key declared by C<< ->bind_key >> is pressed. The default
…		…
562	On error, the condvar will croak when C<recv> is called.	632	On error, the condvar will croak when C<recv> is called.
563		633
564	=cut	634	=cut
565		635
566	sub cmd {	636	sub cmd {
567	my ($self, @cmd) = @_;	637	my $self = shift;
568		638
569	my $cv = AE::cv;	639	$self->{_cmd}->(@_)
570
571	my $reqid = ++$self->{reqid};
572	$self->{cmd_cv}{$reqid} = $cv;
573
574	my $cmd = $JSON->new->utf8->encode ({ command => ref $cmd[0] ? $cmd[0] : \@cmd, request_id => $reqid*1 });
575
576	# (un-)apply escape_binary hack
577	$cmd =~ s/\xf4\x8e\x97\x9f(..)/sprintf sprintf "\\x%02x", hex $1/ges; # f48e979f == 10e5df in utf-8
578
579	$self->{_send}($cmd);
580
581	$cv
582	}	640	}
583		641
584	=item $result = $mpv->cmd_recv ($command => $arg, $arg...)	642	=item $result = $mpv->cmd_recv ($command => $arg, $arg...)
585		643
586	The same as calling C<cmd> and immediately C<recv> on its return	644	The same as calling C<cmd> and immediately C<recv> on its return
…		…
596	&cmd->recv	654	&cmd->recv
597	}	655	}
598		656
599	=item $mpv->bind_key ($INPUT => $string)	657	=item $mpv->bind_key ($INPUT => $string)
600		658
601	This is an extension implement by this module to make it easy to get key events. The way this is implemented	659	This is an extension implement by this module to make it easy to get key
602	is to bind a C<client-message> witha first argument of C<AnyEvent::MPV> and the C<$string> you passed. This C<$string> is then	660	events. The way this is implemented is to bind a C<client-message> witha
603	passed ot the C<on_key> handle when the key is proessed, e.g.:	661	first argument of C<AnyEvent::MPV> and the C<$string> you passed. This
		662	C<$string> is then passed to the C<on_key> handle when the key is
		663	proessed, e.g.:
604		664
605	my $mpv = AnyEvent::MPV->new (	665	my $mpv = AnyEvent::MPV->new (
606	on_key => sub {	666	on_key => sub {
607	my ($mpv, $key) = @_;	667	my ($mpv, $key) = @_;
608		668
…		…
612	},	672	},
613	);	673	);
614		674
615	$mpv_>bind_key (ESC => "letmeout");	675	$mpv_>bind_key (ESC => "letmeout");
616		676
		677	You cna find a list of key names L<in the mpv
		678	documentation\|https://mpv.io/manual/stable/#key-names>.
		679
617	The key configuration is lost when F<mpv> is stopped and must be (re-)done	680	The key configuration is lost when F<mpv> is stopped and must be (re-)done
618	after every C<start>.	681	after every C<start>.
619		682
620	=cut	683	=cut
621		684
622	sub bind_key {	685	sub bind_key {
623	my ($self, $key, $event) = @_;	686	my ($self, $key, $event) = @_;
624		687
625	$event =~ s/([^A-Za-z0-9\-_])/sprintf "\\x%02x", ord $1/ge;	688	$event =~ s/([^A-Za-z0-9\-_])/sprintf "\\x%02x", ord $1/ge;
626	$self->cmd (keybind => $key => "no-osd script-message AnyEvent::MPV key $event");	689	$self->cmd (keybind => $key => "no-osd script-message AnyEvent::MPV key $event");
		690	}
		691
		692	=item [$guard] = $mpv->register_event ($event => $coderef->($mpv, $event, $data))
		693
		694	This method registers a callback to be invoked for a specific
		695	event. Whenever the event occurs, it calls the coderef with the C<$mpv>
		696	object, the C<$event> name and the event object, just like the C<on_event>
		697	method.
		698
		699	For a lst of events, see L<the mpv
		700	documentation\|https://mpv.io/manual/stable/#list-of-events>. Any
		701	underscore in the event name is replaced by a minus sign, so you can
		702	specify event names using underscores for easier quoting in Perl.
		703
		704	In void context, the handler stays registered until C<stop> is called. In
		705	any other context, it returns a guard object that, when destroyed, will
		706	unregister the handler.
		707
		708	You can register multiple handlers for the same event, and this method
		709	does not interfere with the C<on_event> mechanism. That is, you can
		710	completely ignore this method and handle events in a C<on_event> handler,
		711	or mix both approaches as you see fit.
		712
		713	Note that unlike commands, event handlers are registered immediately, that
		714	is, you can issue a command, then register an event handler and then get
		715	an event for this handler I<before> the command is even sent to F<mpv>. If
		716	this kind of race is an issue, you can issue a dummy command such as
		717	C<get_version> and register the handler when the reply is received.
		718
		719	=cut
		720
		721	sub AnyEvent::MPV::Unevent::DESTROY {
		722	my ($evtcb, $event, $evtid) = @{$_[0]};
		723	delete $evtcb->{$event}{$evtid};
		724	}
		725
		726	sub register_event {
		727	my ($self, $event, $cb) = @_;
		728
		729	$event =~ y/_/-/;
		730
		731	my $evtid = ++$self->{evtid};
		732	$self->{evtcb}{$event}{$evtid} = $cb;
		733
		734	defined wantarray
		735	and bless [$self->{evtcb}, $event, $evtid], AnyEvent::MPV::Unevent::
		736	}
		737
		738	=item [$guard] = $mpv->observe_property ($name => $coderef->($mpv, $name, $value))
		739
		740	=item [$guard] = $mpv->observe_property_string ($name => $coderef->($mpv, $name, $value))
		741
		742	These methods wrap a registry system around F<mpv>'s C<observe_property>
		743	and C<observe_property_string> commands - every time the named property
		744	changes, the coderef is invoked with the C<$mpv> object, the name of the
		745	property and the new value.
		746
		747	For a list of properties that you can observe, see L<the mpv
		748	documentation\|https://mpv.io/manual/stable/#property-list>.
		749
		750	Due to the (sane :) way F<mpv> handles these requests, you will always
		751	get a property cxhange event right after registering an observer (meaning
		752	you don't have to query the current value), and it is also possible to
		753	register multiple observers for the same property - they will all be
		754	handled properly.
		755
		756	When called in void context, the observer stays in place until F<mpv>
		757	is stopped. In any otrher context, these methods return a guard
		758	object that, when it goes out of scope, unregisters the observe using
		759	C<unobserve_property>.
		760
		761	Internally, this method uses observer ids of 2**52 (0x10000000000000) or
		762	higher - it will not interfere with lower ovserver ids, so it is possible
		763	to completely ignore this system and execute C<observe_property> commands
		764	yourself, whilst listening to C<property-change> events - as long as your
		765	ids stay below 2**52.
		766
		767	Example: register observers for changtes in C<aid> and C<sid>. Note that
		768	a dummy statement is added to make sure the method is called in void
		769	context.
		770
		771	sub register_observers {
		772	my ($mpv) = @_;
		773
		774	$mpv->observe_property (aid => sub {
		775	my ($mpv, $name, $value) = @_;
		776	print "property aid (=$name) has changed to $value\n";
		777	});
		778
		779	$mpv->observe_property (sid => sub {
		780	my ($mpv, $name, $value) = @_;
		781	print "property sid (=$name) has changed to $value\n";
		782	});
		783
		784	() # ensure the above method is called in void context
		785	}
		786
		787	=cut
		788
		789	sub AnyEvent::MPV::Unobserve::DESTROY {
		790	my ($mpv, $obscb, $obsid) = @{$_[0]};
		791
		792	delete $obscb->{$obsid};
		793
		794	if ($obscb == $mpv->{obscb}) {
		795	$mpv->cmd (unobserve_property => $obsid+0);
		796	}
		797	}
		798
		799	sub _observe_property {
		800	my ($self, $type, $property, $cb) = @_;
		801
		802	my $obsid = OBSID + ++$self->{obsid};
		803	$self->cmd ($type => $obsid+0, $property);
		804	$self->{obscb}{$obsid} = $cb;
		805
		806	defined wantarray and do {
		807	my $unobserve = bless [$self, $self->{obscb}, $obsid], AnyEvent::MPV::Unobserve::;
		808	Scalar::Util::weaken $unobserve->[0];
		809	$unobserve
		810	}
		811	}
		812
		813	sub observe_property {
		814	my ($self, $property, $cb) = @_;
		815
		816	$self->_observe_property (observe_property => $property, $cb)
		817	}
		818
		819	sub observe_property_string {
		820	my ($self, $property, $cb) = @_;
		821
		822	$self->_observe_property (observe_property_string => $property, $cb)
627	}	823	}
628		824
629	=back	825	=back
630		826
631	=head2 SUBCLASSING	827	=head2 SUBCLASSING
…		…
639	care and deal with the breakage.	835	care and deal with the breakage.
640		836
641	If you don't want to go to the effort of subclassing this module, you can	837	If you don't want to go to the effort of subclassing this module, you can
642	also specify all event handlers as constructor keys.	838	also specify all event handlers as constructor keys.
643		839
		840	=head1 EXAMPLES
		841
		842	Here are some real-world code snippets, thrown in here mainly to give you
		843	some example code to copy.
		844
		845	=head2 doomfrontend
		846
		847	At one point I replaced mythtv-frontend by my own terminal-based video
		848	player (based on rxvt-unicode). I toyed with the diea of using F<mpv>'s
		849	subtitle engine to create the user interface, but that is hard to use
		850	since you don't know how big your letters are. It is also where most of
		851	this modules code has originally been developed in.
		852
		853	It uses a unified input queue to handle various remote controls, so its
		854	event handling needs are very simple - it simply feeds all events into the
		855	input queue:
		856
		857	my $mpv = AnyEvent::MPV->new (
		858	mpv => $MPV,
		859	args => \@MPV_ARGS,
		860	on_event => sub {
		861	input_feed "mpv/$_[1]", $_[2];
		862	},
		863	on_key => sub {
		864	input_feed $_[1];
		865	},
		866	on_eof => sub {
		867	input_feed "mpv/quit";
		868	},
		869	);
		870
		871	...
		872
		873	$mpv->start ("--idle=yes", "--pause", "--force-window=no");
		874
		875	It also doesn't use complicated command line arguments - the file search
		876	options have the most impact, as they prevent F<mpv> from scanning
		877	directories with tens of thousands of files for subtitles and more:
		878
		879	--audio-client-name=doomfrontend
		880	--osd-on-seek=msg-bar --osd-bar-align-y=-0.85 --osd-bar-w=95
		881	--sub-auto=exact --audio-file-auto=exact
		882
		883	Since it runs on a TV without a desktop environemnt, it tries to keep complications such as dbus
		884	away and the screensaver happy:
		885
		886	# prevent xscreensaver from doing something stupid, such as starting dbus
		887	$ENV{DBUS_SESSION_BUS_ADDRESS} = "/"; # prevent dbus autostart for sure
		888	$ENV{XDG_CURRENT_DESKTOP} = "generic";
		889
		890	It does bind a number of keys to internal (to doomfrontend) commands:
		891
		892	for (
		893	List::Util::pairs qw(
		894	ESC return
		895	q return
		896	ENTER enter
		897	SPACE pause
		898	[ steprev
		899	] stepfwd
		900	j subtitle
		901	BS red
		902	i green
		903	o yellow
		904	b blue
		905	D triangle
		906	UP up
		907	DOWN down
		908	RIGHT right
		909	LEFT left
		910	),
		911	(map { ("KP$_" => "num$_") } 0..9),
		912	KP_INS => 0, # KP0, but different
		913	) {
		914	$mpv->bind_key ($_->[0] => $_->[1]);
		915	}
		916
		917	It also reacts to sponsorblock chapters, so it needs to know when vidoe
		918	chapters change. Preadting C<AnyEvent::MPV>, it handles observers
		919	manually:
		920
		921	$mpv->cmd (observe_property => 1, "chapter-metadata");
		922
		923	It also tries to apply an F<mpv> profile, if it exists:
		924
		925	eval {
		926	# the profile is optional
		927	$mpv->cmd ("apply-profile" => "doomfrontend");
		928	};
		929
		930	Most of the complicated parts deal with saving and restoring per-video
		931	data, such as bookmarks, playing position, selected audio and subtitle
		932	tracks and so on. However, since it uses L<Coro>, it can conveniently
		933	block and wait for replies, which is n ot possible in purely event based
		934	programs, as you are not allowed to block inside event callbacks in most
		935	event loops. This simplifies the code quite a bit.
		936
		937	When the file to be played is a Tv recording done by mythtv, it uses the
		938	C<appending> protocol and deinterlacing:
		939
		940	if (is_myth $mpv_path) {
		941	$mpv_path = "appending://$mpv_path";
		942	$initial_deinterlace = 1;
		943	}
		944
		945	Otherwise, it sets some defaults and loads the file (I forgot what the
		946	C<dummy> argument is for, but I am sure it is needed by some F<mpv>
		947	version):
		948
		949	$mpv->cmd ("script-message", "osc-visibility", "never", "dummy");
		950	$mpv->cmd ("set", "vid", "auto");
		951	$mpv->cmd ("set", "aid", "auto");
		952	$mpv->cmd ("set", "sid", "no");
		953	$mpv->cmd ("set", "file-local-options/chapters-file", $mpv->escape_binary ("$mpv_path.chapters"));
		954	$mpv->cmd ("loadfile", $mpv->escape_binary ($mpv_path));
		955	$mpv->cmd ("script-message", "osc-visibility", "auto", "dummy");
		956
		957	Handling events makes the main bulk of video playback code. For example,
		958	various ways of ending playback:
		959
		960	if ($INPUT eq "mpv/quit") { # should not happen, but allows user to kill etc. without consequence
		961	$status = 1;
		962	mpv_init; # try reinit
		963	last;
		964
		965	} elsif ($INPUT eq "mpv/idle") { # normal end-of-file
		966	last;
		967
		968	} elsif ($INPUT eq "return") {
		969	$status = 1;
		970	last;
		971
		972	Or the code that actually starts playback, once the file is loaded:
		973
		974	our %SAVE_PROPERTY = (aid => 1, sid => 1, "audio-delay" => 1);
		975
		976	...
		977
		978	my $oid = 100;
		979
		980	} elsif ($INPUT eq "mpv/file-loaded") { # start playing, configure video
		981	$mpv->cmd ("seek", $playback_start, "absolute+exact") if $playback_start > 0;
		982
		983	my $target_fps = eval { $mpv->cmd_recv ("get_property", "container-fps") } \|\| 60;
		984	$target_fps *= play_video_speed_mult;
		985	set_fps $target_fps;
		986
		987	unless (eval { $mpv->cmd_recv ("get_property", "video-format") }) {
		988	$mpv->cmd ("set", "file-local-options/lavfi-complex", "[aid1] asplit [ao], showcqt=..., format=yuv420p [vo]");
		989	};
		990
		991	for my $prop (keys %SAVE_PROPERTY) {
		992	if (exists $PLAYING_STATE->{"mpv_$prop"}) {
		993	$mpv->cmd ("set", "$prop", $PLAYING_STATE->{"mpv_$prop"} . "");
		994	}
		995
		996	$mpv->cmd ("observe_property", ++$oid, $prop);
		997	}
		998
		999	play_video_set_speed;
		1000	$mpv->cmd ("set", "osd-level", "$OSD_LEVEL");
		1001	$mpv->cmd ("observe_property", ++$oid, "osd-level");
		1002	$mpv->cmd ("set", "pause", "no");
		1003
		1004	$mpv->cmd ("set_property", "deinterlace", "yes")
		1005	if $initial_deinterlace;
		1006
		1007	There is a lot going on here. First it seeks to the actual playback
		1008	position, if it is not at the start of the file (it would probaby be more
		1009	efficient to set the starting position before loading the file, though,
		1010	but this is good enough).
		1011
		1012	Then it plays with the display fps, to set it to something harmonious
		1013	w.r.t. the video framerate.
		1014
		1015	If the file does not have a video part, it assumes it is an audio file and
		1016	sets a visualizer.
		1017
		1018	Also, a number of properties are not global, but per-file. At the moment,
		1019	this is C<audio-delay>, and the current audio/subtitle track, which it
		1020	sets, and also creates an observer. Again, this doesn'T use the observe
		1021	functionality of this module, but handles it itself, assigning obsevrer
		1022	ids 100+ to temporary/per-file observers.
		1023
		1024	Lastly, it sets some global (or per-youtube-uploader) parameters, such as
		1025	speed, and unpauses. Property changes are handled like other input events:
		1026
		1027	} elsif ($INPUT eq "mpv/property-change") {
		1028	my $prop = $INPUT_DATA->{name};
		1029
		1030	if ($prop eq "chapter-metadata") {
		1031	if ($INPUT_DATA->{data}{TITLE} =~ /^\[SponsorBlock\]: (.*)/) {
		1032	my $section = $1;
		1033	my $skip;
		1034
		1035	$skip \|\|= $SPONSOR_SKIP{$_}
		1036	for split /\s,\s/, $section;
		1037
		1038	if (defined $skip) {
		1039	if ($skip) {
		1040	# delay a bit, in case we get two metadata changes in quick succession, e.g.
		1041	# because we have a skip at file load time.
		1042	$skip_delay = AE::timer 2/50, 0, sub {
		1043	$mpv->cmd ("no-osd", "add", "chapter", 1);
		1044	$mpv->cmd ("show-text", "skipped sponsorblock section \"$section\"", 3000);
		1045	};
		1046	} else {
		1047	undef $skip_delay;
		1048	$mpv->cmd ("show-text", "NOT skipping sponsorblock section \"$section\"", 3000);
		1049	}
		1050	} else {
		1051	$mpv->cmd ("show-text", "UNRECOGNIZED sponsorblock section \"$section\"", 60000);
		1052	}
		1053	} else {
		1054	# cancel a queued skip
		1055	undef $skip_delay;
		1056	}
		1057
		1058	} elsif (exists $SAVE_PROPERTY{$prop}) {
		1059	$PLAYING_STATE->{"mpv_$prop"} = $INPUT_DATA->{data};
		1060	::state_save;
		1061	}
		1062
		1063	This saves back the per-file properties, and also handles chapter changes
		1064	in a hacky way.
		1065
		1066	Most of the handlers are very simple, though. For example:
		1067
		1068	} elsif ($INPUT eq "pause") {
		1069	$mpv->cmd ("cycle", "pause");
		1070	$PLAYING_STATE->{curpos} = $mpv->cmd_recv ("get_property", "playback-time");
		1071	} elsif ($INPUT eq "right") {
		1072	$mpv->cmd ("osd-msg-bar", "seek", 30, "relative+exact");
		1073	} elsif ($INPUT eq "left") {
		1074	$mpv->cmd ("osd-msg-bar", "seek", -5, "relative+exact");
		1075	} elsif ($INPUT eq "up") {
		1076	$mpv->cmd ("osd-msg-bar", "seek", +600, "relative+exact");
		1077	} elsif ($INPUT eq "down") {
		1078	$mpv->cmd ("osd-msg-bar", "seek", -600, "relative+exact");
		1079	} elsif ($INPUT eq "select") {
		1080	$mpv->cmd ("osd-msg-bar", "add", "audio-delay", "-0.100");
		1081	} elsif ($INPUT eq "start") {
		1082	$mpv->cmd ("osd-msg-bar", "add", "audio-delay", "0.100");
		1083	} elsif ($INPUT eq "intfwd") {
		1084	$mpv->cmd ("no-osd", "frame-step");
		1085	} elsif ($INPUT eq "audio") {
		1086	$mpv->cmd ("osd-auto", "cycle", "audio");
		1087	} elsif ($INPUT eq "subtitle") {
		1088	$mpv->cmd ("osd-auto", "cycle", "sub");
		1089	} elsif ($INPUT eq "triangle") {
		1090	$mpv->cmd ("osd-auto", "cycle", "deinterlace");
		1091
		1092	Once a file has finished playing (or the user strops playback), it pauses,
		1093	unobserves the per-file observers, and saves the current position for to
		1094	be able to resume:
		1095
		1096	$mpv->cmd ("set", "pause", "yes");
		1097
		1098	while ($oid > 100) {
		1099	$mpv->cmd ("unobserve_property", $oid--);
		1100	}
		1101
		1102	$PLAYING_STATE->{curpos} = $mpv->cmd_recv ("get_property", "playback-time");
		1103
		1104	And thats most of the F<mpv>-related code.
		1105
		1106	=head2 F<Gtk2::CV>
		1107
		1108	F<Gtk2::CV> is low-feature image viewer that I use many times daily
		1109	because it can handle directories with millions of files without falling
		1110	over. It also had the ability to play videos for ages, but it used an
		1111	older, crappier protocol to talk to F<mpv> and used F<ffprobe> before
		1112	playing each file instead of letting F<mpv> handle format/size detection.
		1113
		1114	After writing this module, I decided to upgprade Gtk2::CV by making use
		1115	of it, with the goal of getting rid of F<ffprobe> and being ablew to
		1116	reuse F<mpv> processes, which would have a multitude of speed benefits
		1117	(for example, fork+exec of F<mpv> caused the kernel to close all file
		1118	descriptors, which could take minutes if a large file was being copied via
		1119	NFS, as the kernel waited for thr buffers to be flushed on close - not
		1120	having to start F<mpv> gets rid of this issue).
		1121
		1122	Setting up is only complicated by the fact that F<mpv> needs to be
		1123	embedded into an existing window. To keep control of all inputs,
		1124	F<Gtk2::CV> puts an eventbox in front of F<mpv>, so F<mpv> receives no
		1125	input events:
		1126
		1127	$self->{mpv} = AnyEvent::MPV->new (
		1128	trace => $ENV{CV_MPV_TRACE},
		1129	);
		1130
		1131	# create an eventbox, so we receive all input events
		1132	my $box = $self->{mpv_eventbox} = new Gtk2::EventBox;
		1133	$box->set_above_child (1);
		1134	$box->set_visible_window (0);
		1135	$box->set_events ([]);
		1136	$box->can_focus (0);
		1137
		1138	# create a drawingarea that mpv can display into
		1139	my $window = $self->{mpv_window} = new Gtk2::DrawingArea;
		1140	$box->add ($window);
		1141
		1142	# put the drawingarea intot he eventbox, and the eventbox into our display window
		1143	$self->add ($box);
		1144
		1145	# we need to pass the window id to F<mpv>, which means we need to realise
		1146	# the drawingarea, so an X window is allocated for it.
		1147	$self->show_all;
		1148	$window->realize;
		1149	my $xid = $window->window->get_xid;
		1150
		1151	Then it starts F<mpv> using this setup:
		1152
		1153	local $ENV{LC_ALL} = "POSIX";
		1154	$self->{mpv}->start (
		1155	"--no-terminal",
		1156	"--no-input-terminal",
		1157	"--no-input-default-bindings",
		1158	"--no-input-cursor",
		1159	"--input-conf=/dev/null",
		1160	"--input-vo-keyboard=no",
		1161
		1162	"--loop-file=inf",
		1163	"--force-window=yes",
		1164	"--idle=yes",
		1165
		1166	"--audio-client-name=CV",
		1167
		1168	"--osc=yes", # --osc=no displays fading play/pause buttons instead
		1169
		1170	"--wid=$xid",
		1171	);
		1172
		1173	$self->{mpv}->cmd ("script-message" => "osc-visibility" => "never", "dummy");
		1174	$self->{mpv}->cmd ("osc-idlescreen" => "no");
		1175
		1176	It also prepares a hack to force a ConfigureNotify event on every vidoe
		1177	reconfig:
		1178
		1179	# force a configurenotify on every video-reconfig
		1180	$self->{mpv_reconfig} = $self->{mpv}->register_event (video_reconfig => sub {
		1181	my ($mpv, $event, $data) = @_;
		1182
		1183	$self->mpv_window_update;
		1184	});
		1185
		1186	The way this is done is by doing a "dummy" resize to 1x1 and back:
		1187
		1188	$self->{mpv_window}->window->resize (1, 1),
		1189	$self->{mpv_window}->window->resize ($self->{w}, $self->{h});
		1190
		1191	Without this, F<mpv> often doesn't "get" the correct window size. Doing
		1192	it this way is not nice, but I didn't fine a nicer way to do it.
		1193
		1194	When no file is being played, F<mpv> is hidden and prepared:
		1195
		1196	$self->{mpv_eventbox}->hide;
		1197
		1198	$self->{mpv}->cmd (set_property => "pause" => "yes");
		1199	$self->{mpv}->cmd ("playlist_remove", "current");
		1200	$self->{mpv}->cmd (set_property => "video-rotate" => 0);
		1201	$self->{mpv}->cmd (set_property => "lavfi-complex" => "");
		1202
		1203	Loading a file is a bit more complicated, as bluray and DVD rips are
		1204	supported:
		1205
		1206	if ($moviedir) {
		1207	if ($moviedir eq "br") {
		1208	$mpv->cmd (set => "bluray-device" => $path);
		1209	$mpv->cmd (loadfile => "bd://");
		1210	} elsif ($moviedir eq "dvd") {
		1211	$mpv->cmd (set => "dvd-device" => $path);
		1212	$mpv->cmd (loadfile => "dvd://");
		1213	}
		1214	} elsif ($type eq "video/iso-bluray") {
		1215	$mpv->cmd (set => "bluray-device" => $path);
		1216	$mpv->cmd (loadfile => "bd://");
		1217	} else {
		1218	$mpv->cmd (loadfile => $mpv->escape_binary ($path));
		1219	}
		1220
		1221	After this, C<Gtk2::CV> waits for the file to be loaded, video to be
		1222	configured, and then queries the video size (to resize its own window)
		1223	and video format (to decide whether an audio visualizer is needed for
		1224	audio playback). The problematic word here is "wait", as this needs to be
		1225	imploemented using callbacks.
		1226
		1227	This made the code much harder to write, as the whole setup is very
		1228	asynchronous (C<Gtk2::CV> talks to the command interface in F<mpv>, which
		1229	talks to the decode and playback parts, all of which run asynchronously
		1230	w.r.t. each other. In practise, this can mean that C<Gtk2::CV> waits for
		1231	a file to be loaded by F<mpv> while the command interface of F<mpv> still
		1232	deals with the previous file and the decoder still handles an even older
		1233	file). Adding to this fact is that Gtk2::CV is bound by the glib event
		1234	loop, which means we cannot wait for replies form F<mpv> anywhere, so
		1235	everything has to be chained callbacks.
		1236
		1237	The way this is handled is by creating a new empty hash ref that is unique
		1238	for each loaded file, and use it to detect whether the event is old or
		1239	not, and also store C<AnyEvent::MPV> guard objects in it:
		1240
		1241	# every time we loaded a file, we create a new hash
		1242	my $guards = $self->{mpv_guards} = { };
		1243
		1244	Then, when we wait for an event to occur, delete the handler, and, if the
		1245	C<mpv_guards> object has changed, we ignore it. Something like this:
		1246
		1247	$guards->{file_loaded} = $mpv->register_event (file_loaded => sub {
		1248	delete $guards->{file_loaded};
		1249	return if $guards != $self->{mpv_guards};
		1250
		1251	Commands do not have guards since they cnanot be cancelled, so we don't
		1252	have to do this for commands. But what prevents us form misinterpreting
		1253	an old event? Since F<mpv> (by default) handles commands synchronously,
		1254	we can queue a dummy command, whose only purpose is to tell us when all
		1255	previous commands are done. We use C<get_version> for this.
		1256
		1257	The simplified code looks like this:
		1258
		1259	Scalar::Util::weaken $self;
		1260
		1261	$mpv->cmd ("get_version")->cb (sub {
		1262
		1263	$guards->{file_loaded} = $mpv->register_event (file_loaded => sub {
		1264	delete $guards->{file_loaded};
		1265	return if $guards != $self->{mpv_guards};
		1266
		1267	$mpv->cmd (get_property => "video-format")->cb (sub {
		1268	return if $guards != $self->{mpv_guards};
		1269
		1270	# video-format handling
		1271	return if eval { $_[0]->recv; 1 };
		1272
		1273	# no video? assume audio and visualize, cpu usage be damned
		1274	$mpv->cmd (set => "lavfi-complex" => ...");
		1275	});
		1276
		1277	$guards->{show} = $mpv->register_event (video_reconfig => sub {
		1278	delete $guards->{show};
		1279	return if $guards != $self->{mpv_guards};
		1280
		1281	$self->{mpv_eventbox}->show_all;
		1282
		1283	$w = $mpv->cmd (get_property => "dwidth");
		1284	$h = $mpv->cmd (get_property => "dheight");
		1285
		1286	$h->cb (sub {
		1287	$w = eval { $w->recv };
		1288	$h = eval { $h->recv };
		1289
		1290	$mpv->cmd (set_property => "pause" => "no");
		1291
		1292	if ($w && $h) {
		1293	# resize our window
		1294	}
		1295
		1296	});
		1297	});
		1298
		1299	});
		1300
		1301	});
		1302
		1303	Most of the rest of the code is much simpler and just deals with forwarding user commands:
		1304
		1305	} elsif ($key == $Gtk2::Gdk::Keysyms{Right}) { $mpv->cmd ("osd-msg-bar" => seek => "+10");
		1306	} elsif ($key == $Gtk2::Gdk::Keysyms{Left} ) { $mpv->cmd ("osd-msg-bar" => seek => "-10");
		1307	} elsif ($key == $Gtk2::Gdk::Keysyms{Up} ) { $mpv->cmd ("osd-msg-bar" => seek => "+60");
		1308	} elsif ($key == $Gtk2::Gdk::Keysyms{Down} ) { $mpv->cmd ("osd-msg-bar" => seek => "-60");
		1309	} elsif ($key == $Gtk2::Gdk::Keysyms{a}) ) { $mpv->cmd ("osd-msg-msg" => cycle => "audio");
		1310	} elsif ($key == $Gtk2::Gdk::Keysyms{j} ) { $mpv->cmd ("osd-msg-msg" => cycle => "sub");
		1311	} elsif ($key == $Gtk2::Gdk::Keysyms{o} ) { $mpv->cmd ("no-osd" => "cycle-values", "osd-level", "2", "3", "0", "2");
		1312	} elsif ($key == $Gtk2::Gdk::Keysyms{p} ) { $mpv->cmd ("no-osd" => cycle => "pause");
		1313	} elsif ($key == $Gtk2::Gdk::Keysyms{9} ) { $mpv->cmd ("osd-msg-bar" => add => "ao-volume", "-2");
		1314	} elsif ($key == $Gtk2::Gdk::Keysyms{0} ) { $mpv->cmd ("osd-msg-bar" => add => "ao-volume", "+2");
		1315
644	=head1 SEE ALSO	1316	=head1 SEE ALSO
645		1317
646	L<AnyEvent>, L<the mpv command documentation\|https://mpv.io/manual/stable/#command-interface>.	1318	L<AnyEvent>, L<the mpv command documentation\|https://mpv.io/manual/stable/#command-interface>.
647		1319
648	=head1 AUTHOR	1320	=head1 AUTHOR

Diff Legend

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

Comparing AnyEvent-MPV/MPV.pm (file contents): Revision 1.5 by root, Sun Mar 19 23:13:25 2023 UTC vs. Revision 1.20 by root, Sat Apr 1 06:32:32 2023 UTC

Diff Legend

Comparing AnyEvent-MPV/MPV.pm (file contents):
Revision 1.5 by root, Sun Mar 19 23:13:25 2023 UTC vs.
Revision 1.20 by root, Sat Apr 1 06:32:32 2023 UTC