amused.1

.\" Copyright (c) 2022, 2023, 2024 Omar Polo <op@omarpolo.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd September 22, 2024
.Dt AMUSED 1
.Os
.Sh NAME
.Nm amused
.Nd music player
.Sh SYNOPSIS
.Nm
.Op Fl dv
.Op Fl s Ar socket
.Oo
.Ar command
.Op Ar argument ...
.Oc
.Sh DESCRIPTION
.Nm
is a music player.
It manages a playing queue of music files.
When it finishes to play a track,
.Nm
proceeds to the next file in the queue, or with the first one if
the currently playing track is not in the playing queue.
When it reaces the end, by default, it wraps back to the first track.
.Pp
.Nm
automatically skips and removes from the playing queue non-regular files,
or ones with a non-recognized audio format.
.Pp
The following options are available:
.Bl -tag -width Ds
.It Fl d
Do not daemonize:
.Nm
will run in the foreground and log to standard error.
It's ignored if any commands are given on the command line, or if the
server is already running.
.It Fl s Ar socket
Use
.Ar socket
instead of the default
.Pa /tmp/amused-UID
to communicate with the daemon.
.It Fl v
Produce more verbose output.
.It Ar command Op Ar argument ...
Specify the command to run.
If no commands are specified,
.Ic status
is assumed.
Commands may be abbreviated to a unique prefix, for example
.Sq rep
can be given instead of
.Ic repeat .
.El
.Pp
The following commands are available:
.Bl -tag -width Ds
.It Cm add Ar
Enqueue the given files at the end of the playing queue.
.It Cm consume Op Cm on Ns | Ns Cm off
Enable or disable the consume mode.
When consume mode is enabled the tracks are removed from the playing queue
once played completely.
Without arguments toggle the current status.
.It Cm flush
Erase the playlist.
.It Cm jump Ar pattern
Play the first song in the playing queue that matches
.Ar pattern ,
a basic case-insensitive regexp.
.It Cm load Op Ar file
Load a playlist from
.Ar file
or standard input.
A playlist is a list of paths to music files given one per line
and optionally prefixed by
.Sq > \&
or two spaces.
If the list was generated by
.Nm
.Ic show Fl p ,
restore also the position in the playing queue.
Otherwise, if already playing something, try to match the currently
played song in the new queue.
.It Cm monitor Op Ar events
Stop indefinitely and print when an event in the comma-separated list
of
.Ar events
happened, or all if not given.
The available
.Ar events
are:
.Pp
.Bl -tag -compact -width Ds
.It add
Added a song to the playlist.
.It jump
Jumped to a different song in the playlist.
.It load
Loaded a new playlist.
.It mode
Mode changed
.Pq repeat or consume .
.It next
Advanced to next song.
.It pause
Paused.
.It play
Playing or resuming a song.
.It previous
Gone back to previous song.
.It seek
Seeked in the current track.
.It stop
Stopped.
.El
.It Cm next
Play the next song.
.It Cm pause
Pause the playback.
.It Cm play
Start or resume the playback.
.It Cm previous
Play the previous song.
.It Cm repeat one Ns | Ns Cm all Op Cm on Ns | Ns Cm off
Enable or disable the automatic repetition of the current track
.Pq Cm one
or of the whole playing queue
.Pq Cm all .
Without arguments toggle the given repeat mode.
.It Cm restart
Play the current song from the beginning.
It's a shorthand for
.Nm
.Cm seek
0.
.It Cm seek Oo +- Oc Ns Ar time Ns Op %
Seek by the specified amount of
.Ar time
into the current song.
If the argument is prefixed by either
.Sq +
or
.Sq -
then the seek is relative to the current position, otherwise is
absolute.
With a trailing
.Sq % ,
the
.Ar time
is interpreted as a percentage of the length of the track.
.Pp
The
.Ar time
can also be expressed as
.Oo Oo Ar hours : Oc Ns Ar minutes : Oc Ns Ar seconds ,
but in this case no trailing
.Sq %
is allowed.
.It Cm show Op Fl p
Show the playlist.
With
.Fl p
it prints a
.Dq pretty
list with the current playing song prefixed by
.Sq > \& .
.It Cm shuffle Op Fl a
Shuffle the playing queue after the currently playing track until the
end.
If
.Fl a
is given, all the tracks in the playing queue are shuffled, with
the currently playing one moved at the top.
.It Cm status Op Fl f Ar format
Print playback status and current song.
The
.Ar format
is a comma-separated list of words that select the information to
print, in order.
It defaults to
.Ev AMUSED_STATUS_FORMAT
or to
.Dq status,time:oneline,mode:oneline
if not defined.
The formats available are:
.Pp
.Bl -tag -compact -width time:percentage
.It path
Path of the current song
.It mode:oneline
Mode status in a single line.
.It mode
Repeat all, one and consume, one per line.
.It status
Playback status by the path to the current song.
.It time:oneline
Position and duration in a single line.
.It time:percentage
Percentage of the current position.
.It time:raw
Current position and duration in seconds.
.It time
Current position and duration in a human-readable format.
.El
.It Cm stop
Stop the playback.
.It Cm toggle
Play/pause the playback.
.El
.Sh ENVIRONMENT
.Bl -tag -width AMUSED_STATUS_FORMAT
.It Ev AMUSED_STATUS_FORMAT
The default format used by
.Nm
.Cm status .
.It Ev TEMPDIR
Path to the directory where the control socket is created.
Defaults to
.Pa /tmp .
.El
.Sh FILES
.Bl -tag -width "/tmp/amused-UID" -compact
.It Pa /tmp/amused-UID
.Ux Ns -domain
socket used for communication with the daemon.
.El
.Sh EXAMPLES
Load every file under the current directory recursively:
.Bd -literal -offset indent
$ find . | amused load
.Ed
.Pp
Enqueue all mp3 files in the current directory:
.Bd -literal -offset indent
$ amused add *.mp3
.Ed
.Pp
Recursively add all opus files:
.Bd -literal -offset indent
$ find . -type f -iname \\*.opus -exec amused add {} +
.Ed
.Pp
Save the state of the player to the file
.Pa amused.dump :
.Bd -literal -offset indent
$ amused show -p > amused.dump
.Ed
.Pp
Load a previous state:
.Bd -literal -offset indent
$ amused load < amused.dump
.Ed
.Pp
Remove duplicates:
.Bd -literal -offset indent
$ amused show | sort | uniq | amused load
.Ed
.Pp
Select a song with
.Xr fzf 1
.Bd -literal -offset indent
$ amused jump "$(amused show | fzf +s)"
.Ed
.Sh SEE ALSO
.Xr amused-mpris2 1 ,
.Xr amused-web 1
.Sh AUTHORS
.An -nosplit
The
.Nm
utility was written by
.An Omar Polo Aq Mt op@omarpolo.com .