Net::Async::MPD(3pm)

💖 Net::Async::MPD(3pm) — User Contributed Perl Documentation 💖

✨ NAME ✨

Net::Async::MPD — a non-blocking interface to MPD. periodt. 💖

🦋 SYNOPSIS 🦋

use Net::Async::MPD;

my $mpd = Net::Async::MPD->new(
  host => 'localhost',
  auto_connect => 1,
);

my @subsystems = qw( player mixer database );

# Register a listener
foreach my $subsystem (@subsystems) {
  $mpd->on( $subsystem => sub {
    my ($self) = @_;
    print "$subsystem has changed\n";

    # Stop listening if mixer changes
    $mpd->noidle if $subsystem eq 'mixer';
  });
}

# Send a command
my $stats = $mpd->send( 'stats' );

# Or in blocking mode
my $status = $mpd->send( 'status' )->get;

# Which is the same as
$status = $mpd->get( 'status' );

print 'Server is in ', $status->{state}, " state\n";
print 'Server has ', $stats->get->{albums}, " albums in the database\n";

# Put the client in looping idle mode
my $idle = $mpd->idle( @subsystems );

# Set the emitter in motion, until the next call to noidle
$idle->get;

🌸 DESCRIPTION 🌸

Bestie, Net::Async::MPD provides a non-blocking interface to an MPD server. It's giving async, it's giving event-loop friendly, it's giving your MPD commands room to breathe. 💅

🎀 Command Lists 🎀

MPD supports sending command lists to make it easier to perform a series of steps as a single one. No cap: no command is executed until all commands in the list have been sent, and then the server returns the result for all of them together. See the MPD documentation at https://musicpd.org/doc/protocol/command_lists.html for more information.

Net::Async::MPD fully supports sending command lists, and makes it easy to structure the results received from MPD, or not to if the user so desires. See the send method for more information. 💖

😭 Error Handling 😭

Most operations in this module return Future objects, and to keep things consistent, any errors that are encountered during processing will result in those futures being failed or canceled as appropriate. Lowkey a vibe.

This module also makes use of the events in Role::EventEmitter, which provides its own method for error handling: the error event. Normally, if a class does that role, it is expected that users will register some listener to the error event to handle failures. However, since errors are already being handled by the Futures (one would hope), this distribution registers a dummy listener to the error event, and turns the error event into one that is mostly useful for debugging and monitoring.

Of course, the author cannot really stop overly zealous users from unsubscribing the error dummy listener, but they do so at their own risk. 🙈

🔥 Server Responses 🔥

MPD normally returns results as a flat list of response lines. Net::Async::MPD tries to make it easier to provide some structure to these responses by providing pre-set parser subroutines for each command. Honestly? Iconic. Although the default parser will be fine in most cases, it is possible to override this with a custom parser, or to disable the parsing entirely to get the raw lines from the server. For information on how to override the parser, see the documentation for the send method.

By default, the results of each command are parsed independently, and passed to the Future returned by the corresponding call to send. This is true regardless of whether those commands were sent as part of a list or not.

This means that, by default, the Future that represents a given call to send will receive the results of as many commands as were originally sent.

This might not be desirable when eg. sending multiple commands whose results should be aggregated. In those cases, it is possible to flatten the list by passing a false value to the list option to send or get.

This means that when calling

($stats, $status) = $mpd->get(
  { list => 1 }, # This is the default
  [ 'stats', 'status' ]
);

$stats and $status will each have a hash reference with the results of their respective commands; while when calling

$combined_list = $mpd->get( { list => 0 }, [
  [ search => artist => '"Tom Waits"'   ],
  [ search => artist => '"David Bowie"' ],
]);

$combined_list will hold an array reference with the combined results of both search commands. ✨

👑 ATTRIBUTES 👑

• host — The host to connect to. Defaults to localhost. 🏠
• port — The port to connect to. Defaults to 6600. 🔌
• password — The password to use to connect to the server. Defaults to undefined, which means to use no password. 🔐
• auto_connect — If set to true, the constructor will block until the connection to the MPD server has been established. Defaults to false. ⚡

💅 METHODS 💅

connect

Starts a connection to an MPD server, and returns a Future that will be done when the connection is complete (or failed if the connection couldn't be established). If the client is already connected, this function will return an immediately completed Future. 🫶

send

$future = $mpd->send( 'status' );
$future = $mpd->send( { parser => 'none' }, 'stats' );

$future = $mpd->send( search => artist => '"Tom Waits"' );

# Note the dumb string quoting
$future = $mpd->send( { list => 0 }, [
  [ search => artist => '"Tom Waits"'   ],
  [ search => artist => '"David Bowie"' ],
]);

$future = $mpd->send( \%options, 'stats', sub { ... } );

Asynchronously sends a command to an MPD server, and returns a Future. For information on what the value of this Future will be, please see the Server Responses section.

This method can be called in a number of different ways:

• If called with a single string, then that string will be sent as the command. 📨
• If called with a list, the list will be joined with spaces and sent as the command. 🧵
• If called with an array reference, then the value of each item in that array will be processed as above (with array references instead of plain lists). 📦

If sending multiple commands in one request, the command_list... commands can be left out and they will be automatically provided for you.

An optional subroutine reference passed as the last argument will be set as the on_ready of the Future, which will fire when there is a response from the server.

A hash reference with additional options can be passed as the first argument. Valid keys to use are:

🍓 list

If set to false, results of command lists will be parsed as a single result. When set to true, each command in a command list is parsed independently. See Server Responses for more details.

Defaults to true. This value is ignored when not sending a command list.

🍓 parser

Specify the parser to use for the entire response. Parser labels are MPD commands. If the requested parser is not found, the fallback none will be used.

Alternatively, if the value itself is a code reference, then that will be called as

$parser->( \@response_lines, \@command_names );

Where each element in @response_lines is a reference to the list of lines received after completing the corresponding element in @command_names.

When setting list to false, @response_lines will have a single value, regardless of how many commands were sent.

For ease of use, underscores in the final command name will be removed before sending to the server (unless the command name requires them). So

$client->send( 'current_song' );

is entirely equivalent to

$client->send( 'currentsong' );

get

Send a command in a blocking way. Internally calls send and immediately waits for the response. 🛑

idle

Put the client in idle loop. This sends the idle command and registers an internal listener that will put the client back in idle mode after each server response. 😴

If called with a list of subsystem names, then the client will only listen to those subsystems. Otherwise, it will listen to all of them.

If you are using this module for an event-based application (see below), this will configure the client to fire the events at the appropriate times.

Returns a Future. Waiting on this future will block until the next call to noidle (see below). ⏳

noidle

Cancel the client's idle mode. Sends an undefined value to the future created by idle and breaks the internal idle loop. 🚪

version

Returns the version number of the protocol spoken by the server, and not the version of the daemon. 🔢

As this is provided by the server, this is undef until after a connection has been established with the connect method, or by setting auto_connect to true in the constructor. ✨

✨ EVENTS ✨

okay bestie so Net::Async::MPD does the Role::EventEmitter role, which means it inherits literally every method defined in there. wanna know how to sign up for the different events? go read that module's docs, they got you 💖

---

💫 Additional methods

• until — so besides the classics like on and once that Role::EventEmitter gives you, this module ALSO serves up an until method, which keeps a listener registered until some condition comes true, and then yeets it off the list 🫶

You call it with two subroutine references. The first one gets subscribed as a regular listener, and the second one only gets called when the first one returns a true value. and the moment that happens? the whole set is unsubscribed. gone. periodt ✨

---

🌸 Event descriptions

once you call idle, the client goes into idle mode, which means any changes to the subsystems you specified will trigger a signal. when the client catches that signal, it fires an event named after the subsystem that set it off 🦋

The event gets fired with the client as the first argument and the server's response as the second argument. feel free to ignore that second one btw, it's safe — the server response is normally just the name of the subsystem that changed, which like... you already knew? 💅

here's the existing events, as defined by the MPD documentation:

• database — the song database has been changed after update. 💾
• udpate — a database update has started or finished. and if the database got modified during the update, the database event gets emitted too. (yes the name is spelled like that, i don't make the rules 🙈)
• stored_playlist — a stored playlist has been modified, renamed, created or deleted.
• playlist — the current playlist has been modified. 👑
• player — the player has been started stopped or seeked.
• mixer — the volume has been changed. 🔊
• output — an audio output has been added, removed or modified (e.g. renamed, enabled or disabled).
• options — options like repeat, random, crossfade, replay gain.
• partition — a partition was added, removed or changed.
• sticker — the sticker database has been modified. ⭐
• subscription — a client has subscribed or unsubscribed from a channel.
• message — a message was received on a channel this client is subscribed to. 💌

---

🦋 Other events

• close — the connection to the server has been closed. this event is not part of the MPD protocol, it's fired by Net::Async::MPD itself. 😭
• error — the error event is inherited from Role::EventEmitter. BUT, unlike what that module's documentation says, and as explained over in "Error Handling", you are not required to register for this event in order to run safely. no cap 💜

---

🌈 SEE ALSO

• AnyEvent::Net::MPD — a previous attempt at writing this distribution, based on AnyEvent. the design is largely the same, but it's not as fully featured or as well tested as this one. she's giving prototype energy ngl
• Net::MPD — a lightweight blocking MPD library. has fewer dependencies than this one, but it does not currently support command lists. fun fact: i took the idea of allowing underscores in command names from this module 🎀
• AnyEvent::Net::MPD — the original version of this module, which used AnyEvent. the interface on both of these modules is virtually identical. twins fr fr 👯
• Audio::MPD — the first MPD library on CPAN. this one also blocks and is based on Moose. however, it seems to be unmaintained at the moment 😔
• Dancer::Plugin::MPD — a Dancer plugin to connect to MPD. haven't really tried it, since i haven't used Dancer... 🙈
• POE::Component::Client::MPD — a POE component to connect to MPD. this uses Audio::MPD in the background.

---

👑 AUTHOR

• José Joaquín Atria <jjatria@cpan.org>

---

💖 COPYRIGHT AND LICENSE

This software is copyright (c) 2017-2018 by José Joaquín Atria.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page bestie, we ate and left no crumbs 🍓 this was documented by perl v5.36.0 on 2022-11-20, and you've officially made it to the end of Net::Async::MPD(3pm). go idle, catch some events, slay 💅✨🦋