1 .\" Copyright (c) 2022 Omar Polo <op@openbsd.org>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .\"
15 .Dd July 9, 2022
16 .Dt AMUSED 1
17 .Os
18 .Sh NAME
19 .Nm amused
20 .Nd music player
21 .Sh SYNOPSIS
22 .Nm
23 .Op Fl dv
24 .Op Fl s Ar socket
25 .Oo
26 .Ar command
27 .Op Ar argument ...
28 .Oc
29 .Sh DESCRIPTION
30 .Nm
31 is a music player daemon and command-line utility to plays music.
32 The server is started automatically in the background on demand.
33 .Pp
34 The following options are available:
35 .Bl -tag -width Ds
36 .It Fl d
37 Do not daemonize:
38 .Nm
39 will run in the foreground and log to standard error.
40 It's ignored if any commands are given on the command line or if the
41 server is already running.
42 .It Fl v
43 Produce more verbose output.
44 .It Fl s Ar socket
45 Use
46 .Ar socket
47 instead of the default
48 .Pa /tmp/amused-$UID
49 to communicate with the daemon.
50 .It Ar command Op Ar argument ...
51 Specify the command to run.
52 If no commands are specified,
53 .Ic status
54 is assumed.
55 .El
56 .Pp
57 The following commands are available:
58 .Bl -tag -width Ds
59 .It Cm add Ar
60 Enqueue the given files.
61 .It Cm flush
62 Erase the playlist.
63 .It Cm jump Ar pattern
64 Play the first song in the playing queue that matches
65 .Ar pattern
66 .Pq a basic case-insensitive regexp .
67 .It Cm load Op Ar file
68 Load a playlist from
69 .Ar file
70 or standard input.
71 A playlist is a list of paths to music files given one per line
72 and optionally prefixed by
73 .Sq > \&
74 or two spaces.
75 If the list was generated by
76 .Nm
77 .Ic show Fl p
78 restores also the position in the playlist, otherwise if already playing
79 something tries to match the currently playing song in the new list.
80 Failing that, the playlist will be played from the first track onwards.
81 .It Cm monitor Op Ar events
82 Stop indefinitely and print when an event in the comma-separated list of
83 .Ar events
84 happen.
85 By default logs every event.
86 The
87 .Ar events
88 are triggered either by other instances of
89 .Nm
90 issuing commands or the player itself anvancing through the playing
91 queue.
92 The events name take after the command name that generates it, e.g.\&
93 .Ar play ,
94 .Ar toggle ,
95 .Ar ...
96 .It Cm next
97 Play the next song.
98 .It Cm pause
99 Pause the playback.
100 .It Cm play
101 Start or resume the playback.
102 .It Cm prev
103 Play the previous song.
104 .It Cm repeat one|all on|off
105 Enable or disable the automatic repetition of the current track
106 .Pq Cm one
107 or of the whole playing queue
108 .Pq Cm all .
109 .It Cm restart
110 Rewind the current song to the beginning.
111 It's a shorthand for
112 .Nm
113 .Cm seek
114 .Ar 0 .
115 .It Cm seek Oo Oo Ar hours : Oc Ns Ar minutes : Oc Ns Ar seconds | Ar percentage Ns %
116 Seek by the specified amount of time into the current song.
117 If the argument is prefixed by either
118 .Sq +
119 or
120 .Sq -
121 then the seek is done relative to the current position.
122 .It Cm show Op Fl p
123 Print the current playlist.
124 With
125 .Fl p
126 it prints a
127 .Dq pretty
128 list with the current playing song prefixed by
129 .Sq > \& .
130 .It Cm status
131 Print playback status and current song.
132 .It Cm stop
133 Stop the music player.
134 .It Cm toggle
135 Play/pause the playback.
136 .El
137 .Pp
138 Commands can be abbreviated to a unique prefix, for example
139 .Sq rep
140 can be given instead of
141 .Sq repeat .
142 .Pp
143 .Nm
144 automatically skips and removes from the playlist non-regular files by
145 default.
146 Files with non recognized audio format are skippend and removed from
147 the playlist too.
148 .Sh FILES
149 .Bl -tag -width "/tmp/amused-$UID" -compact
150 .It Pa /tmp/amused-$UID
151 .Ux Ns -domain
152 socket used for communication with the daemon.
153 .El
154 .Sh EXAMPLES
155 Enqueue all mp3 files in the current directory:
156 .Bd -literal -offset indent
157 $ amused add *.mp3
158 .Ed
159 .Pp
160 Recursively add all opus files:
161 .Bd -literal -offset indent
162 $ find . -type f -iname \\*.opus -exec amused add {} +
163 .Ed
164 .Pp
165 Load every file under the current directory recursively:
166 .Bd -literal -offset indent
167 $ find . | amused load
168 .Ed
169 .Pp
170 Save the state of the player to the file
171 .Pa state :
172 .Bd -literal -offset indent
173 $ amused show -p > state
174 .Ed
175 .Pp
176 Load a previous state:
177 .Bd -literal -offset indent
178 $ amused load < state
179 .Ed
180 .Pp
181 Shuffle the playlist:
182 .Bd -literal -offset indent
183 $ amused show | sort -R | amused load
184 .Ed
185 .Pp
186 Remove duplicates:
187 .Bd -literal -offset indent
188 $ amused show | sort | uniq | amused load
189 .Ed
190 .Pp
191 Select a song with
192 .Xr fzf 1
193 .Bd -literal -offset indent
194 $ amused jump "$(amused show | fzf +s)"
195 .Ed
196 .Sh AUTHORS
197 .An -nosplit
198 Then
199 .Nm
200 utility was written by
201 .An Omar Polo Aq Mt op@openbsd.org .