XMMS2(1)

💖 NAME 💖

xmms2 — the official XMMS2 command line interface. That's the whole name, bestie. (And yes, you're reading XMMS2(1), General Commands Manual — it's giving iconic.)

✨ SYNOPSIS ✨

xmms2 [command] [arguments]
xmms2 help [command]

🦋 DESCRIPTION 🦋

Okay so picture this: XMMS2 is a full-on redesign of the XMMS music player (yes, that one — https://en.wikipedia.org/wiki/XMMS). It's got a client-server model, which means multiple user interfaces can be connected at the same time — even simultaneously! — and they can be textual or graphical. Literally both, no cap. All common audio formats are supported using plugins, and on top of that there's a flexible media library to organise your music. 💅

And xmms2? It's the official CLI XMMS2 client. Main character energy fr fr.

🎀 INVOCATION 🎀

🌸 Inline mode 🌸

If xmms2 is passed a command as an argument, that command will be interpreted and xmms2 will exit after it is finished. One command, in and out, done. ✨

🦋 Interactive mode 🦋

xmms2 features a powerful shell-like environment via readline that allows you to enter commands at a prompt and have the usual cool features such as pathname expansion and line editing. It's giving cozy little command shell and we're obsessed. 🫶

👑 COMMANDS 👑

All commands accept the option -h/--help which displays the command's help. 💖

pattern refers to a collection definition. (See PATTERN below.)

position is a pattern to match playlist positions. When absent in a command, the default is the end of the playlist. (See POSITION PATTERN below.)

🌈 General Commands 🌈

✨ add ✨

add [ -f [-N] [-P] [-A key=value]... ] [-p playlist] [-n | -a position] [-o prop[,...]] [-j] arguments...
add [-p playlist] [-n | -a position] [-o prop[,...]] [-j] pattern...

Add media to a playlist. It will attempt to guess whether arguments constitute a pattern or represent file paths. This behaviour can be overridden by forcing the type with -f and -t. If file paths contain * or ? characters, it will attempt to expand them. Failing to find a match, the * and ? characters will be attempted to be added as a part of the URL.

• -f, --file — Force treating arguments as file paths.
• -P, --pls — Force treating arguments as playlist files. This option implies -f.
• -t, --pattern — Force treating arguments as a pattern.
• -N, --non-recursive — Do not add directories recursively.
• -p, --playlist playlist — Add media to playlist instead of the active playlist.
• -n, --next — Add media after the current track.
• -a, --at position — Add media at the given position.
• -A, --attribute key=value — Add media with given key=value attribute. May occur multiple times. Only valid when adding new files to the media library.
• -o, --order prop[,...] — Add media sorted by the given comma-separated list of properties. If a property is prefixed by -, media are sorted in reverse order on that property.
• -j, --jump — Jump to and start playing the newly-added media.

exit

Exit the shell-like interface. Bye bestie. 👋

help

help [-a] command

Show the help on command. This is equivalent to command -h. If command is an alias, show the alias definition. If no command is provided, list all available commands.

• -a, --alias — List available aliases if command is not provided. Otherwise, have no effect.

info

info [pattern | positions...]

Display the properties of all media matching pattern or at the given positions. Without argument, display the properties of the current track.

jump

jump [-b] pattern|position

Jump to the first media matching pattern or to the given position.

• -b, --backward — Jump backward to the first media matching the pattern.

list

list [-p name] [pattern | positions...]

List the contents of a playlist (the active one by default). If pattern is provided, contents are further filtered and only the matching media are displayed.

• -p, --playlist — List playlist, instead of the active playlist.

move

move [-p playlist] [-n | -a position] pattern | positions...

Move entries inside a playlist (the active one by default).

• -p, --playlist playlist — The playlist to act on.
• -n, --next — Move the matching tracks after the current track.
• -a, --at position — Move the matching tracks by an offset or to a position.

next

next [offset]

Jump to the next song. If offset is provided, act like jump +offset.

pause

Pause playback.

play

Start playback.

prev

prev [offset]

Jump to the previous song. If offset is provided, act like jump -offset.

remove

remove [-p playlist] pattern | positions...

Remove the matching media from a playlist (the active one by default).

• -p, --playlist playlist — Remove from playlist, instead of the active playlist.

current

current [-r seconds] [-f format]

Display playback status, either continuously or once.

• -r, --refresh seconds — Set the delay, in seconds, between each refresh of the current playback metadata. If 0, the metadata is only printed once (default) and the command exit immediately. When in refresh mode, basic control is provided on the active playlist.
• -f, --format format — Set the format string used to display status information, instead of the one from the configuration file (see FORMAT STRING below).

search

search [-o prop1[,prop2...]] [-l prop1[,prop2...] ] pattern

Search and print all media matching pattern.

• -o, --order prop1[,prop2...] — Display search results sorted by the given list of properties. If a property is prefixed by -, results are sorted in reverse order on that property.
• -l, --columns prop1[,prop2...] — List of properties to use as columns.

seek

seek time | offset

Seek to a relative or an absolute time in the current track.

stop

Stop playback.

toggle

Toggle playback.

🎵 Playlist Commands 🎵

playlist clear

playlist clear [playlist]

Clear a playlist. By default, clear the active playlist.

playlist config

playlist config [-t type] [-s history] [-u upcoming] [-i coll] [-j playlist] [playlist]

Configure a playlist by changing its type, attributes, etc. By default, configure the active playlist.

• -t, --type type — Change the type of the playlist: list, queue, pshuffle.
• -s, --history size — The size of the history of played tracks (for queue, pshuffle).
• -u, --upcoming upcoming — Number of upcoming tracks to maintain (for pshuffle).
• -i, --input collection — Input collection for the playlist (for pshuffle). Default to 'All Media'.
• -j, --jumplist playlist — Jump to another playlist when the end of the playlist is reached.

playlist create

playlist create [-s] [-p playlist] name

Create a new playlist.

• -s, --switch — Switch to the newly created playlist.
• -p, --playlist playlist — Copy the content of the playlist into the new playlist.

playlist list

playlist list [-a]

List all playlists.

• -a, --all — Include hidden playlists.

playlist remove

playlist remove playlist

Remove the given playlist.

playlist rename

playlist rename [-f] [-p playlist] newname

Rename a playlist. By default, rename the active playlist.

• -f, --force — Force the rename of the playlist, overwrite an existing playlist if needed.
• -p, --playlist — Rename the given playlist.

playlist shuffle

playlist shuffle [playlist]

Shuffle a playlist. By default, shuffle the active playlist.

playlist sort

playlist sort [-p playlist] [prop] ...

Sort a playlist. By default, sort the active playlist. Prefix properties by - for reverse sorting. If no properties are specified, the playlist is sorted by artist, album, and track number.

• -p, --playlist — Rename the given playlist. (No bestie, I'm not joking — the manpage literally says "Rename" under playlist sort. I'm keeping it exactly as written. Iconic. 💅)

playlist switch

playlist switch playlist

Change the active playlist.

🍓 Collection Commands 🍓

collection config

collection config collection [attrname [attrvalue]]

Get or set attributes for the given collection. If no attribute name is provided, list all attributes. If only an attribute name is provided, display the value of the attribute. If both attribute name and value are provided, set the new value of the attribute.

collection create

collection create [-f] [-e] [-c collection] name [pattern]

Create a new collection. If pattern is provided, it is used to define the collection. Otherwise, the new collection contains the whole media library.

• -f, --force — Force creating of the collection, overwrite an existing collection if needed.
• -c, --collection collection — Copy an existing collection to the new one.
• -e, --empty — Initialize an empty collection.

collection list

List all collections.

collection show

collection show collection

Display a human-readable description of a collection.

collection remove

collection remove collection

Remove a collection.

collection rename

collection rename [-f] oldname newname

Rename a collection.

• -f, --force — Force renaming of the collection, overwrite an existing collection if needed.

🧚 Server Commands 🧚

server browse

server browse URL

Browse a URL via the xform plugins available in the daemon.

server config

server config [name [value]]

Get or set configuration values. If no name or value is provided, list all configuration values. If only a name is provided, display the content of the corresponding configuration value. If both name and a value are provided, set the new content of the configuration value.

The name of the configuration value is subject to shell wildcard expansion so that multiple values can be queried (but not set) at once.

server import

server import [-N] path

Import new files into the media library. By default, directories are imported recursively.

• -N, --non-recursive — Do not import directories recursively.

server plugins

List the plugins loaded in the server.

server property

server property [-i | -s | -D] [-S] mid [name [value]]

Get or set properties for a given media. If no name or value is provided, list all properties. If only a name is provided, display the value of the property. If both a name and a value are provided, set the new value of the property.

By default, set operations use source "client/xmms2-cli", while list and display operations use source-preference. Use the --source option to override this behaviour.

By default, the value will be used to determine whether it should be saved as a string or an integer. Use the --int or --string flag to override this behaviour.

• -i, --int — force the value to be treated as an integer, no arguments 💅
• -s, --string — force the value to be treated as a string, periodt
• -D, --delete — delete the selected property (poof, gone 🫶)
• -S, --source — property source

server rehash [pattern]

Rehash the media matched by the pattern — or, if you don't pass a pattern, the whole media library gets rehashed. all of it. iconic.

server remove [pattern]

Remove the matching media from the media library. bye bestie 💀

server shutdown

Shut the server down. yes, that's it, that's the command.

server stats

Displays stats about the server: uptime, version, size of the medialib, etc. a little selfie of your server ✨

server sync

Immediately save collections to disk. (Otherwise this only happens on shutdown, or 10 seconds after the last change to collections.) so like, if you're the impatient type, this is your girl 🧚

server volume [-c name] [value]

Get or set the audio volume — range is 0-100. Pass a value and it sets the volume to it; don't pass one and it just shows you the current volume. By default it applies to all audio channels, so use the --channel flag if you wanna override that. Also!! relative changes are a thing — just prefix value with + or -. so +10 goes up, -10 goes down, math is math 🎀

• -c, --channel — get or set the volume only for the named channel

---

🦋 PATTERN

Patterns are how you search for songs in the media library. Some of these need escaping (with '\') depending on which shell you're living in — check yourself before you wreck yourself. The properties you can use are in the output of xmms2 info. iykyk 🌸

<property>:<string>

Match songs whose property matches the string. A ? in the string means a single wildcard character, and a * means multiple wildcard characters.

<property>~<string>

Match songs whose property fuzzily matches the string. Equal to matching by <property>:*<string>*. lowkey the same thing, highkey convenient 💅

<property><operation><number>

The operation can be <, <=, >, or >=. The pattern matches songs whose property is a numerical value that's smaller than, smaller than or equal to, bigger than, or bigger than or equal to the number.

+<property>

Match songs that have the property.

in:<namespace>/<collection>

Match songs in the given collection. The namespace may be Playlists or Collections.

NOT <pattern>

Match the complement of the pattern. the opposite girlie 🙈

<pattern> <pattern> <pattern> AND <pattern>

Match songs matched by both patterns.

<pattern> OR <pattern>

Match songs matched by at least one of the two patterns.

( <pattern> )

Match songs matched by the pattern — this one's for grouping AND and OR matches, okurrr 🔥

<string>

Match songs whose artist, title, or album match the string.

~<string>

Match songs whose artist, title, or album fuzzily match the string.

#<number>

Match a specific media library id. one specific song, main character energy 👑

---

🎀 POSITION PATTERN

Position patterns get used together with commands that operate on playlist content. here's the whole menu:

M_N

Select playlist entries ranging from M positions before the current song to N positions after. Both M and N may be omitted and will then default to 0.

-N

Select the song N positions before the current song.

+N

Select the song N positions after the current song.

pos0,pos1,...,posN

Select one to many playlist positions. a whole little list of them 🍓

---

⭐ FORMAT STRING

Commands that output formatted metadata can be customized with user-defined format strings, like this:

´${artist} - ${title}´

When you pass metadata, the name of the artist and the title get inserted into the resulting string. And on top of the metadata supplied from the media library, these properties are also available:

position

The current playlist position.

playback_status

The playback status as a string (Stopped, Playing, Paused, Unknown).

playtime

The playtime of the currently playing song.

duration

The duration of the current song, as zero-padded minutes:seconds.

minutes

The minutes part, zero-padded, of the current song duration.

seconds

The seconds part, zero-padded, of the current song duration.

---

💜 ALIASES

A list of command aliases is read from the configuration file in the [alias] section at runtime. The syntax of xmms2 aliases is somewhat similar to bash and other shells. An alias is defined by a list of semicolon-separated commands and arguments. Parameter expansion is supported (see Expansion below). no cap, it's giving shell 🫶

The default configuration includes these aliases:

addpls

add -f -P $@

clear

playlist clear

status

current -f $1

ls

list

mute

server volume 0

quit

server shutdown

repeat

seek 0

scap

stop ; playlist clear ; add $@ ; play

✨ Expansion

Positional Parameters

An alias can use positional parameters, for example:

foo = add -f $1 $3

foo ctkoz.ogg and slre.ogg

Will result in:

add -f ctkoz.ogg slre.ogg

Special Parameters

$@ This expands to all parameters passed to the alias. literally all of them 💖

---

🌈 CONFIGURATION

All control characters are interpreted as expected, including ANSI escape sequences. fancy ✨

AUTO_UNIQUE_COMPLETE Boolean. Completes an abbreviation of a command and its arguments. For example: serv vol 42 will complete to server volume 42. (Note: abbreviations must be non-ambiguous.)

CLASSIC_LIST Boolean. Format list output similar to the classic cli.

CLASSIC_LIST_FORMAT String to format classic list output with.

GUESS_PLS Boolean. Try to guess if the URL is a playlist and add accordingly. (Not reliable.) bestie said "maybe" 😭

HISTORY_FILE File to save command history to.

PLAYLIST_MARKER String to use to mark the current active entry in the playlist.

PROMPT String to use as a prompt in INTERACTIVE MODE.

SERVER_AUTOSTART Boolean. If true, xmms2 will attempt to start xmms2d(1) if it's not running already.

SHELL_START_MESSAGE Boolean. If true, xmms2 will display a greeting message and basic help when started in INTERACTIVE MODE.

STATUS_FORMAT String to format status output with.

---

🎀 FILES

• $XDG_CACHE_HOME/xmms2/nyxmms2_history — default command history file if HISTORY_FILE is unset.
• $XDG_CONFIG_HOME/xmms2/clients/nycli.conf — the configuration file for xmms2.

---

🦋 ENVIRONMENT

• XMMS_PATH — override the default connection path.
  • To connect via IPv4:

tcp://IPv4-Address:port

• To connect via IPv6:

tcp://[IPv6-Address]:port

• To connect via unix socket:

unix:///path/to/socket

---

💀 BUGS

Please report all bugs at https://github.com/xmms2. do it for the culture 🙏

---

👑 AUTHORS

Igor Assis, Anders Waldenborg, Anthony Garcia, Sebastien Cevey, and Jonne Lehtinen, Daniel Svensson, Raphaël Bois.

See the AUTHORS file in the XMMS2 source distribution for more info.

The blame for this man page is on Anthony.

If you contributed and feel you should be listed here please send me a mail.

---

and that's the whole thing, bestie — we ate, no crumbs 🍓 the page signs off as XMMS2(1), and the source/version + date live down there in the real footer if you need to check when this icon was published 💖🎀✨