smpcp.1

.TH "SMPCP" "1" "0.1.9.4" "December 2023" "Super Music Player Client Plus"
.SH NAME
\fB\fCsmpcp\fR \- smpcp documentation\.
.SH "SYNOPSIS"
.B smpcp [<\fICOMMAND\fR> [\fIOPTIONS\fR] [++ <\fICOMMAND\fR> [\fIOPTIONS\fR] ++ ...]
.SH "DESCRIPTION"
.PP
\fBsmpcp\fR is a command line client for \fBMPD\fR.
.SH "CONFIGURATION"
See \fBsmpcp.conf(5)\fR.
.SH "DAEMON"
To enable auto-playlists, playback statistics and notifications, \fBsmpcpd\fR - the \fBsmpcp\fR daemon - must be running. A systemd unit is provided for this purpose.
.TP
To enable the daemon:
.B systemctl --user enable smpcpd
.TP
To start the daemon:
.B systemctl --user start smpcpd
.SH "COMMANDS"
If no command is given, \fBsmpcp\fR prints its version and the current status.

Commands can be chained with \fB++\fR operator.

Command auto-completion is available for \fBzsh\fR and \fBbash\fR.

.SS Player Commands

\fBplay\fR [\fIpos\fR]
  Starts playing the specified song by its position in the queue.

\fBplayalbum\fR [<\fIartist\fR> <\fIalbum\fR>]
  Starts playing given album or starts playing album for current song. If \fIsong\fR or \fIalbum\fR mode is enabled, new songs are added to the queue when the last song starts playing.

\fBpause\fR
  Pauses or unpauses playback.

\fBtoggle\fR [\fIpos\fR]
  Same as play. Pauses if currently playing.

\fBnext\fR
  Plays the next song in the queue.

\fBnextalbum\fR
  Plays another random album (see \fBMODES\fR for more info).

\fBskip\fR
  Same as next. Increments skip count (see \fBMODES\fR for more info).

\fBunskip\fR
  Resets skip count of the current song.

\fBprev\fR
  Plays previous song or plays the current song from the start.

\fBseek\fR <[\fI+\fR|\fI-\fR][[\fIHH:\fR]\fIMM:\fR]\fISS\fR>|[\fI+\fR|\fI-\fR]<\fI0-100%\fR>
  seeks within the current song by hours, minutes, seconds (hours and minutes are optional) or by percentage. If + or - is used, seek is performed relatively to the current song position.

.SS Playback Options

If no option is given for the following commands, \fBsmpcp\fR prints their current status.

\fBrepeat\fR [\fI-n\fR] [\fIon\fR|\fIoff\fR]
  Sets repeat mode.

\fBrandom\fR [\fI-n\fR] [\fIon\fR|\fIoff\fR]
  Sets random mode.

\fBsingle\fR [\fI-n\fR] [\fIon\fR|\fIoff\fR]
  Sets single mode.

\fBoneshot\fR [\fI-n\fR] [\fIon\fR|\fIoff\fR]
  Sets oneshot mode. \fI-n\fR displays a notification.

\fBconsume\fR [\fI-n\fR] [\fIon\fR|\fIoff\fR]
  Sets consume mode.

\fBxfade\fR [\fIduration\fR]
  Sets crossfade duration (in seconds).

\fBreplaygain\fR [\fItrack\fR|\fIalbum\fR|\fIauto\fR|\fIoff\fR]
  Sets replay gain mode.

.SS Modes

\fBmode\fR [\fIsong\fR|\fIalbum\fR|\fInormal\fR|\fIoff\fR]
  Sets mode (see \fBMODES\fR for more info.)

.SS Volume Control
\fBvol\fR [\fI-n\fR] [\fI+\fR|\fI-\fR][\fI0-100\fR]
  Sets volume. If no value is given, prints current volume. \fI-n\fR option displays a notification.

\fBdim\fR [\fI-n\fR]
  Toggles volume dimmer. If on, volume is dimmed by 50%. \fI-n\fR option displays a notification.

.SS Queue Management

\fBls\fR [\fI-f\fR]|[\fI-f\fR [\fIformat\fR]]
Pretty prints the current queue. \fI-f\fR option prints filenames only or uses \fIformat\fR (see \fBOUTPUT FORMATTING\fR).

\fBadd\fR <\fIuri\fR>
  Adds songs to the queue. \fBadd\fR command can also read from stdin.

\fBaddsong\fR <\fIartist\fR> <\fItitle\fR>
  Add a specific song to the queue and set its priority so that it will be played right after the current song.

\fBgetrnd\fR [\fI-a\fR] <\fIcount\fR>
  Prints <\fIcount\fR> random songs or albums (\fI-a\fB).

\fBdelete\fR <\fIpos\fR>|<\fIstart-end\fR>
  Deletes songs from the queue.

\fBmove\fR <\fIpos\fR>|<\fIstart-end\fR> <\fIto\fR>
  Moves songs within the queue.

\fBcrop\fR
  Deletes all songs from the queue except the current one.

\fBclear\fR
  Clears the queue.

.SS Stored Playlists
\fBpls\fR [\fIname\fR]
  Prints available stored playlists or prints content of the given playlist.

\fBload\fR <\fIname\fR> [\fIpos1\fR|\fIstart-end\fR ... \fIposN\fR|\fIstart-end\fR]
  Adds a playlist or the specified entries to the current queue.

\fBcload\fR <\fIname\fR> [\fIpos1\fR|\fIstart-end\fR ... \fIposN\fR|\fIstart-end\fR]
  Same as load. Clears the queue first and starts playing when the playlist is loaded.
  (similar to \fBsmpcp clear ++ load my_playlist ++ play)

\fBsave\fR <\fIname\fR>
  Saves the current queue to a playlist. If <\fIname\fR> already exists, it is overwritten.

\fBremove\fR <\fIname\fR>
  Removes a playlist.

.SS Status and Info
\fBstatus\fR
  Shows status.

\fBstate\fR [\fI-p\fR]
  Playback state. Returns 0 if playing or paused, 1 if stopped. If \fI-p\fR option is used, prints actual playback state (play, pause or stop).

\fBsonginfo\fR
  Prints info about current song.

\fBalbuminfo\fR
  Prints info about current album.

\fBalbums\fR [\fIartist\fR]
  Prints available albums for current artist.

\fBgetcurrent\fR [\fIformat\fR]
  Prints current song in the given format or its uri.

\fBgetnext\fR [\fIformat\fR]
  Prints next song in the given format or its uri.

\fBgetprev\fR [\fIformat\fR]
  Prints previous song in the given format or its uri.

\fBgetduration\fR [\fI-h\fR]
  Prints current song duration in seconds or in a human readable format (\fI-h\fB).

\fBgetelapsed\fR [\fI-h\fR]
  Prints elapsed time for current song in seconds or in a human readable format (\fI-h\fB).

\fBlsalbums\fR [\fIartist\fR]
  Prints all albums or albums for the given artist.

\fBlsartists\fR
  Prints all album artists.

\fBlsdir\fR [\fIuri\fR]
  Lists directory contents.

\fBhistory\fR
  Prints playback history.

\fBhelp\fR
  Shows a help screen.

.SS Audio CD
\fBcdadd\fR [\fItrack\fR|\fIstart-end\fR|\fItrack1\fR \fItrack2\fR ... \fItrackN\fR]
  Add all or given tracks from an audio CD to the queue.

\fBcdplay\fR
  Play an audio CD.

.SS Outputs
\fBlsoutputs\fR
  Prints available outputs.

\fBoutput\fR <\fIname\fR> [\fIon\fR|\fIoff\fR]
  Sets output. If no option is given, display output current status.

.SS Statistics

\fBrating\fR [\fI1-5\fR]
  Gives currents song a rating between 1 and 5. Without argument, it prints current song rating.

\fBdbplaytime\fR
  Prints sum of all song durations in the database.

\fBplaytime\fR
  Prints total time played.

.SS Plugins
More commands may be available if plugins are installed. When invoking \fBhelp\fR, new commands are shown at the end of the list.

\fBplugins\fR
  Prints a list of installed plugins.

.SH "STATUS"
When invoking \fBsmpcp\fR without argument or with the \fBstatus\fR command, it prints current status including playback state and playback options.
.PP
.IP "" 4
.nf
.B [> [song] -z-cx- ****- x11
.B Orbital - Nothing Left 1
.PP
.IP "" 0
.fi
Playback options are shown as a single letter:
.PP
.IP "" 4
.nf
.B r - repeat
.B z - random
.B s - single
.B 1 - oneshot
.B c - consume
.B x - crossfade
.B d - dim
.PP
.IP "" 0
.fi
.SH "MODES"
\fBsmpcp\fR has three modes: \fInormal\fR, \fIsong\fR and \fIalbum\fR.

To see what mode is currently used: \fBmode\fR

In order to use \fIalbum\fR and \fIsong\fR modes, the \fBsmpcp\fR daemon (\fBsmpcpd\fR) must be up and running.

.SS Song Mode

In this mode, random songs are automatically and continuously added to the queue and the following playback options are turned on: random, consume and 10 seconds crossfade. New songs are added when the last song in the queue starts playing.

Songs are discarded if they apply these rules:
.IP "" 4
.nf
Song is in the playback history.

Song skip count is greater or equal to the limit.
.fi
.IP "" 0
(see \fBINFO AND STATISTICS\fR and read \fBsmpcp.conf(5)\fR for more info.)

To enable \fIsong\fR mode: \fBmode song\fR

.SS Album Mode

In this mode, a random album is added to the queue and consume is enabled. Another album is added when the last song starts playing.

To enable \fIalbum\fR mode: \fBmode album\fR

.SS Normal Mode

\fINormal\fR mode is the default. In this mode, you have to manage the queue manually.

To enable \fInormal\fR mode: \fBmode normal\fR
.SH "INFO AND STATISTICS"
When \fBsmpcp\fR daemon is running, it keep track of played songs and statistics are stored in \fBMPD\fR sticker database:
.PP
.IP "" 4
- date last played
.br
- play count
.br
- skip count
.br
- rating
.fi
.IP "" 0
A song is added to history if:
.PP
.IP "" 4
.nf
- \fBnext\fR or \fBskip\fR command is invoked.
- The song has been played thoroughly.
.fi
.IP "" 0
Song playcount is incremented if it was played until the end.
.br
Song skipcount is incremented when using \fBskip\fR command.
.PP
You can obtain information about current song with the \fBsonginfo\fR command.
.SH "OUTPUT FORMATTING"
Some commands can use a format to display songs (i.e \fBgetcurrent\fR).
.PP
Interpreted metadata are:
.IP "" 4
.nf
.TP
\fB%file%\fR
file path relative to music directory
.TP
\fB%ext%\fR
lowercase file extension
.TP
\fB%last-modified%\fR
file modification date
.TP
\fB%artist%\fR
artist name
.TP
\fB%albumartist%\fR
artist of album (defaults to %artist% if not found)
.TP
\fB%name%\fR
internet radio name
.TP
\fB%album%\fR
album title
.TP
\fB%title%\fR
song title
.TP
\fB%track%\fR
track number
.TP
\fB%disc%\fR
disc number
.TP
\fB%genre%\fR
genre
.TP
\fB%date%\fR
date
.TP
\fB%time%\fR
song duration in seconds (integer)
.TP
\fB%duration%\fR
song duration in seconds (float)
.TP
\fB%pos%\fR
song position in the queue
.TP
\fB%id%\fR
unique song id in the queue
.fi
.IP "" 0
.PP
If no format is given when a command expects one, it defaults to \fB%file%\fR.

If a tag is empty or missing, it is stripped from the source string.

A substring enclosed in double square brackets is also stripped if it contains an empty or missing tag.

For example:
.IP "" 4
.nf
\fBNow playing\\n[[artist: %artist%\\n]]title: %title%\fR
.IP "" 0
.fi
.PP
assuming %artist% tag is not found, would output:
.IP "" 4
.nf
.B Now playing
.B title: song title
.IP "" 0
.fi
.SH "SEE ALSO"
\fBsmpcp.conf(5)\fR, \fBmpd(1)\fR.
.SH "REPORTING BUGS"
\fIhttps://github.com/teegre/smpcp/issues\fR
.SH "LICENSE"
License GPL-v3

This is free software provided \fBAS IS\fR with \fBNO WARRANTY\fR.
.br
Feel free to change and redistribute.

For more info, see \fB$XDG_DATA_HOME/.local/share/licenses/smpcp/LICENSE\fR
.SH "AUTHOR"
.TP
Stéphane MEYER (Teegre)
.SH "COPYRIGHT"
.TP
2023 Stéphane MEYER (Teegre)