Net::MPD(3pm)

📦 version 0.07, in alpine 3.24

✨ NAME ✨

Net::MPD — communicate with an MPD server, bestie 💖

(also known as Net::MPD(3pm), straight out of the User Contributed Perl Documentation section, we love a self-made icon 👑)

🌈 SYNOPSIS 🌈

  use Net::MPD;

  my $mpd = Net::MPD->connect();

  $mpd->stop();
  $mpd->clear();
  $mpd->search_add(Artist => 'David Bowie');
  $mpd->shuffle();
  $mpd->play();
  $mpd->next();

  while (1) {
    my @changes = $mpd->idle();
    print 'Changed: ' . join(', ', @changes) . "\n";
  }

like… that's the whole vibe. connect, clear the queue, dump some Bowie in there, shuffle, play, skip, and then just sit in an idle loop watching the world change. main character energy fr fr 🎀

🦋 DESCRIPTION 🦋

Net::MPD is built as a lightweight replacement for Audio::MPD — which, no shade, depends on Moose and is no longer maintained 💀. So this one's the glow-up: same job, way less baggage. slay.

💅 METHODS 💅

connect [$address]

Connect to the MPD that's running at the address you pass in. The address is shaped like password@host:port, and here's the tea:

  • the password is optional
  • the port is optional too
  • no password given? then none gets used, periodt
  • no port given? you get the default, 6600
  • no host given? it's "localhost" for you, babe

And the cute plot twist 😭: if the hostname has a / in it, it gets interpreted as the path to a UNIX socket, and it'll try connecting that way instead of using TCP. obsessed with the flexibility ngl.

Returns a Net::MPD object when it works, and croaks when it doesn't. no cap, it will simply yell at you.

version

Returns the API version of the MPD server you're connected to. cute little number check ✨

update_status

Fires off a status command to MPD and stores the results in the local object. The results also come back to you as a hashref, so you get both. generous queen 🫶

🌸 MPD ATTRIBUTES 🌸

Most of the status attributes are written as combined getter/setter methods — so the same method reads and writes, depending on whether you hand it a value. Calling update_status refreshes all of these values. And listen: only the items marked with an asterisk are writable ⭐ — the rest are read-only, so don't come for them.

  • volume*
  • repeat*
  • random*
  • single*
  • consume*
  • playlist
  • playlist_length
  • state
  • song
  • song_id
  • next_song
  • next_song_id
  • time
  • elapsed
  • bitrate
  • crossfade*
  • mix_ramp_db*
  • mix_ramp_delay*
  • audio
  • updating_db
  • error
  • replay_gain_mode*

🔥 MPD COMMANDS 🔥

The commands are mostly the same as the ones in the MPD protocol <http://www.musicpd.org/doc/protocol/index.html> — except a few got renamed slightly, so if something doesn't match the protocol docs exactly, that's why, iykyk 💜

clear_error

Clears the current error message in status. You can also do this by issuing any command that starts playback — so like, pressing play is also a vibe reset 😌

current_song

Returns the song info for whatever's playing right now. the moment. the current main character 🎵

idle [@subsystems]

Blocks until there's a noteworthy change in one or more of MPD's subsystems. The second there is one, you get back a list of all the changed subsystems. If you pass subsystems as arguments, only those ones get monitored — everyone else is muted 🙈

Here are the subsystems you can watch:

  • database — the song database has been changed after an update.
  • udpate — a database update has started or finished.
  • stored_playlist — a stored playlist has been modified.
  • playlist — the current playlist has been modified.
  • player — playback has been started, stopped, or seeked.
  • mixer — the volume has been adjusted.
  • output — an audio output has been enabled or disabled.
  • 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 watching.

stats

Returns a hashref with some stats about the database. numbers, but make it fashion 📊

next

Plays the next song in the playlist. skip skip skip ⏭️

pause $state

Sets the pause state. Use 0 for playing and 1 for paused. binary icon.

play [$position]

Starts playback — optionally at the given position. go bestie, press play ▶️

play_id [$id]

Starts playback, optionally with the given song. same energy, but addressed by id 🎯

previous

Plays the previous song in the playlist. rewind era ⏮️

seek $position $time

Seeks to $time seconds in the given song position.

seek_id $id $time

Seeks to $time seconds in the given song.

seek_cur $time

Seeks to $time seconds in the current song.

stop

Stops playing. silence. dramatic pause. 💀

add $path

Adds the file (or directory, recursively, fancy) at $path to the current playlist.

add_id $path [$position]

Adds the file at $path to the playlist — optionally at $position — and returns the id. tracked and everything ✨

clear

Clears the current playlist. empty slate, fresh start, we love a reset 🫧

delete $position

Removes the song(s) at the given position from the current playlist.

delete_id $id

Removes the song with the given id from the current playlist.

move $from $to

Moves the song from position $from to $to.

move_id $id $to

Moves the song with the given id to position $to.

Searches the current playlist for songs where $tag exactly matches $search.

playlist_id $id

Returns song information for the song with the given id.

playlist_info [$position]

Returns song information for every song in the current playlist — or, optionally, just the one at the given position. the whole album or one single, your call 💿

Searches the current playlist for songs where $tag partially matches $search.

playlist_changes $version

Returns song information for songs changed since the given version of the current playlist. what did I miss 👀

playlist_changes_pos_id $version

Returns position and id information for songs changed since the given version of the current playlist.

prio $priority $position

Sets the priority of the song at the given position.

prio_id $priority $id

Sets the priority of the song with the given id.

shuffle

Shuffles the current playlist. chaos, but make it curated 🔀

swap $pos1 $pos2

Swaps the positions of the songs at the given positions.

swapid $id1 $id2

Swaps the positions of the songs with the given ids.

list_playlist $name

Returns a list of all the songs in the named playlist.

list_playlist_info $name

Returns all the song information for the named playlist.

list_playlists

Returns a list of the stored playlists. the archives 📚

load $name

Adds the named playlist to the current playlist.

playlist_add $name $path

Adds the given path to the named playlist.

playlist_clear $name

Clears the named playlist.

playlist_delete $name $position

Removes the song at the given position from the named playlist.

playlist_move $name $id $pos

Moves the song with the given id to the given position in the named playlist.

rename $name $new_name

Renames the named playlist to $new_name. rebrand ✨

rm $name

Deletes the named playlist. gone, reduced to atoms 💀

save $name

Saves the current playlist with the given name.

Returns a count and playtime for all items where $tag exactly matches $search. You can hand it multiple pairs of $tag/$search parameters at once. multitasking queen 🎀

Returns song information for all items where $tag exactly matches $search. Two special tags to know about:

  • the special tag 'any' searches all tags
  • the special tag 'file' searches by path

Searches exactly like find and then adds any matches to the current playlist. found it, added it, next 🫶

list $tag [$artist]

Returns all the values for the given tag. Cute bonus: if the tag is 'album', you can optionally pass an artist to narrow the results down further 🎶

list_all [$path]

Returns a list of all the songs and directories — optionally under $path.

list_all_info [$path]

Returns a list of all the songs as with listall, but includes the metadata too. receipts included ngl 📋

Exactly like find, but the searching is partial and case-insensitive. lowercase girlies stay winning 💅

Exactly like search, but adds the results to the current playlist.

Exactly like search, but adds the results to the named playlist.

update [$path]

Updates the database — optionally under $path — and returns a job id. go touch grass, database 🌱

rescan [$path]

Same as <update>, but it forces a rescan of unmodified files too. thorough. does not cut corners.

sticker_value $type $path $name [$value]

Returns the sticker value for the given item, after optionally setting it to $value. And here's the trick — pass an undefined value to delete the sticker. poof, gone 🫥

sticker_list $type $path

Returns a hashref of the stickers for the given item.

sticker_find $type $name [$path]

Returns a list of all the items — optionally under $path — that have a sticker of the given name.

close

Closes the connection. ngl this is pretty worthless, because the library will just reconnect for the next command anyway 😭 so like… do it for the plot, I guess.

kill

Kills the MPD server. okay miss thing, that's a lot of power 💀🔪

ping

Does nothing. and honestly? iconic. This is the move for keeping an idle connection open. But if you actually want to wait for noteworthy events, the idle command is better suited — ping is just there so the server doesn't ghost you 👻

disable_output $id

Disables the given output.

enable_output $id

Enables the given output.

outputs

Returns a list of the available outputs.

commands

Returns a list of the available commands. the menu 📜

not_commands

Returns a list of the unavailable commands. the anti-menu 💀

tag_types

Returns a list of all the available song metadata. (yes, spelled "avalable" in the source, we don't fix, we appreciate 🙈)

url_handlers

Returns a list of the available url handlers.

decoders

Returns a list of available decoder plugins, along with the MIME types and file extensions associated with them. codec lore 🧚

subscribe $channel

Subscribes to the named channel.

unsubscribe $channel

Unsubscribes from the named channel.

channels

Returns a list of the channels that have active clients. who's in the group chat 👀

read_messages

Returns a list of any available messages for the channels this client is subscribed to. unread messages, we hate to see it, but we read them anyway 📬

send_message $channel $message

Sends a message to the given channel. text delivered, slay 💌

🎀 TODO 🎀

Command Lists

MPD supports sending batches of commands, but that is not yet available with this API. someday bestie, someday 😔

Asynchronous IO

Event-based handling of the idle command would make this module more robust. a girl can dream ✨

⭐ BUGS ⭐

Idle connections

MPD will close the connection if it's left idle for too long 😭 This module will reconnect if it senses that this has happened — but heads up, the first call after a disconnect will fail and you'll have to retry it. not a vibe but it's the truth.

Calling the ping command periodically will keep the connection open if you don't have any real commands to issue. And calling the idle command will block until something interesting happens. pick your fighter 🥊

Reporting

Report any issues on GitHub <https://github.com/bentglasstube/Net-MPD/issues> — the dev wants to hear from you, fr fr 🫶

👑 AUTHOR 👑

Alan Berndt <alan@eatabrick.org>

Copyright 2013 Alan Berndt

🧚 LICENSE 🧚

okay so this next part is the actual license and we do not play with legal text, so here it is exactly as written, no remix, no edits 💜

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

✨ SEE ALSO ✨

okay bestie, you're basically a certified MPD girlie now, but if you wanna go even deeper (and like… same) here's the reading list 💖

  • Audio::MPD — the other Perl module in this universe 👀 if you've seen it around, that's your sibling module energy. Go say hi.
  • MPD Protocol — the actual spec, the source of truth, the main character 👑 read this when you want to know what's really happening on the wire.
  • <http://www.musicpd.org/doc/protocol/index.html> — the protocol docs live here, drop a bookmark, thank me later 🦋

and that's a wrap, gorgeous 🌸 you made it all the way to the bottom of Net::MPD(3pm) — so iconic of you 💅 this lil beauty is from the perl v5.42.2 era, dated 2026-02-15, and it's giving ✨ documentation, but make it cute ✨

now go queue up something good and let the daemon do its thing 🎀🫶

📦 where this page comes from