Blob


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 25, 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 play 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 consume Op Cm on|off
62 Enable or disable the consume mode.
63 When consume mode is enabled the tracks are removed from the playlist
64 once played until the end.
65 Without arguments toggle the current status.
66 .It Cm flush
67 Erase the playlist.
68 .It Cm jump Ar pattern
69 Play the first song in the playing queue that matches
70 .Ar pattern
71 .Pq a basic case-insensitive regexp .
72 .It Cm load Op Ar file
73 Load a playlist from
74 .Ar file
75 or standard input.
76 A playlist is a list of paths to music files given one per line
77 and optionally prefixed by
78 .Sq > \&
79 or two spaces.
80 If the list was generated by
81 .Nm
82 .Ic show Fl p
83 restore also the position in the playlist.
84 Otherwise, if already playing something, try to match the currently
85 song in the new list.
86 Failing that, the playlist will be played from the first track
87 onwards.
88 .It Cm monitor Op Ar events
89 Stop indefinitely and print when an event in the comma-separated list
90 of
91 .Ar events
92 happened, or all if not given.
93 The available
94 .Ar events
95 are:
96 .Pp
97 .Bl -tag -compact -width Ds
98 .It add
99 Added a song to the playlist.
100 .It jump
101 Jumped to a different song in the playlist.
102 .It load
103 Loaded a new playlist.
104 .It mode
105 Mode changed
106 .Pq repeat or consume .
107 .It next
108 Advanced to next song.
109 .It pause
110 Paused.
111 .It play
112 Playing or resuming a song.
113 .It prev
114 Gone back to previous song.
115 .It seek
116 Seeked in the current track.
117 .It stop
118 Stopped.
119 .El
120 .It Cm next
121 Play the next song.
122 .It Cm pause
123 Pause the playback.
124 .It Cm play
125 Start or resume the playback.
126 .It Cm prev
127 Play the previous song.
128 .It Cm repeat one|all Op Cm on|off
129 Enable or disable the automatic repetition of the current track
130 .Pq Cm one
131 or of the whole playing queue
132 .Pq Cm all .
133 Without arguments toggle the given repeat mode.
134 .It Cm restart
135 Rewind the current song to the beginning.
136 It's a shorthand for
137 .Nm
138 .Cm seek
139 .Ar 0 .
140 .It Cm seek Oo Oo Ar hours : Oc Ns Ar minutes : Oc Ns Ar seconds | Ar percentage Ns %
141 Seek by the specified amount of time into the current song.
142 If the argument is prefixed by either
143 .Sq +
144 or
145 .Sq -
146 then the seek is relative to the current position.
147 .It Cm show Op Fl p
148 Show the playlist.
149 With
150 .Fl p
151 it prints a
152 .Dq pretty
153 list with the current playing song prefixed by
154 .Sq > \& .
155 .It Cm status Op Fl f Ar format
156 Print playback status and current song.
157 The
158 .Ar format
159 is a comma-separated list of words that select the information to
160 print, in order.
161 It defaults to
162 .Ev AMUSED_STATUS_FORMAT
163 or to
164 .Dq status,time:oneline,mode:oneline
165 if not defined.
166 The formats available are:
167 .Pp
168 .Bl -tag -compact -width time:percentage
169 .It path
170 Path of the current song
171 .It mode:oneline
172 Mode status in a single line.
173 .It mode
174 Repeat all, one and consume, one per line.
175 .It status
176 Playback status by the path to the current song.
177 .It time:oneline
178 Position and duration in a single line.
179 .It time:percentage
180 Percentage of the current position.
181 .It time:raw
182 Current position and duration in seconds.
183 .It time
184 Current position and duration in a human-readable format.
185 .El
186 .It Cm stop
187 Stop the music player.
188 .It Cm toggle
189 Play/pause the playback.
190 .El
191 .Pp
192 Commands can be abbreviated to a unique prefix, for example
193 .Sq rep
194 can be given instead of
195 .Sq repeat .
196 .Pp
197 .Nm
198 automatically skips and removes from the playlist non-regular files.
199 Files with non recognized audio format are skippend and removed from
200 the playlist too.
201 .Sh ENVIRONMENT
202 .Bl -tag -width AMUSED_STATUS_FORMAT
203 .It Ev AMUSED_STATUS_FORMAT
204 The default format used by
205 .Nm
206 .Cm status .
207 .El
208 .Sh FILES
209 .Bl -tag -width "/tmp/amused-$UID" -compact
210 .It Pa /tmp/amused-$UID
211 .Ux Ns -domain
212 socket used for communication with the daemon.
213 .El
214 .Sh EXAMPLES
215 Load every file under the current directory recursively:
216 .Bd -literal -offset indent
217 $ find . | amused load
218 .Ed
219 .Pp
220 Enqueue all mp3 files in the current directory:
221 .Bd -literal -offset indent
222 $ amused add *.mp3
223 .Ed
224 .Pp
225 Recursively add all opus files:
226 .Bd -literal -offset indent
227 $ find . -type f -iname \\*.opus -exec amused add {} +
228 .Ed
229 .Pp
230 Save the state of the player to the file
231 .Pa state :
232 .Bd -literal -offset indent
233 $ amused show -p > state
234 .Ed
235 .Pp
236 Load a previous state:
237 .Bd -literal -offset indent
238 $ amused load < state
239 .Ed
240 .Pp
241 Shuffle the playlist:
242 .Bd -literal -offset indent
243 $ amused show | sort -R | amused load
244 .Ed
245 .Pp
246 Remove duplicates:
247 .Bd -literal -offset indent
248 $ amused show | sort | uniq | amused load
249 .Ed
250 .Pp
251 Select a song with
252 .Xr fzf 1
253 .Bd -literal -offset indent
254 $ amused jump "$(amused show | fzf +s)"
255 .Ed
256 .Sh AUTHORS
257 .An -nosplit
258 Then
259 .Nm
260 utility was written by
261 .An Omar Polo Aq Mt op@openbsd.org .