1 # amused
2 
3 amused is a music player.  It doesn't have any amazing features
4 built-in, on the contrary: it's quite minimal (a fancy word to say
5 that does very little.)  It composes well, or aims to do so, with
6 other tools though.
7 
8 The main feature is that audio decoding runs in a sandboxed process
9 under `pledge("stdio recvfd audio")` (on OpenBSD at least.)
10 
11 It's available on the OpenBSD port tree starting from 7.1
12 
13 
14 ## Building
15 
16 The dependencies are:
17 
18  - flac
19  - libmpg123
20  - libvorbis
21  - opusfile
22  - libsndio or libasound (ALSA)
23 
24 Then, to build:
25 
26 	$ ./configure
27 	$ make
28 	# make install # eventually
29 
30 To compile the web control interface, amused-web, run:
31 
32 	$ make web
33 	# make install-web # eventually
34 
35 The build can be customized by passing arguments to the configure
36 script or by using a `configure.local` file; see `./configure -h`
37 and [`configure.local.example`](configure.local.example) for more
38 information.
39 
40 For each library the `configure` script first tries to see if they're
41 available without any extra flags, then tries again with some
42 hard-coded flags (e.g. `-lFLAC` for flac) and finally resorts to
43 pkg-config if available.  pkg-config auto-detection can be disable by
44 passing `PKG_CONFIG=false` (or the empty string)
45 
46 For Linux users with libbsd installed, the configure script can be
47 instructed to use libbsd exclusively as follows:
48 
49 	$ CFLAGS="$(pkg-config --cflags libbsd-overlay)" \
50 		./configure LDFLAGS="$(pkg-config --libs libbsd-overlay)"
51 
52 To force the use of one specific audio backend and not simply the first
53 one found, pass `--backend` as:
54 
55 	$ ./configure --backend=alsa # or sndio
56 
57 
58 ## Usage
59 
60 The fine man page has all nitty gritty details, but the TL;DR is
61 
62  - enqueue music with `amused add files...` or `amused load <playlist`
63  - control the playback with `amused play|pause|toggle|stop`
64  - check the status with `amused status` and the current playlist with
65    `amused show`
66 
67 amused tries to be usable in composition with other more familiar tools
68 instead of providing everything itself.  For instance, there isn't a
69 command to remove an item from the playlist, or shuffle it; instead,
70 standard UNIX tools can be used:
71 
72 	$ amused show | grep -vi kobayashi | amused load
73 	$ amused show | sort -R | amused load
74 	$ amused show | sort | uniq | amused load
75 
76 It also doesn't provide any means to manage a music collection.  It
77 plays nice with find(1) however:
78 
79 	$ find . | amused load
80 
81 Non-music files found in the playlist are automatically skipped and
82 removed, so there's no harm in loading everything under a certain
83 directory.
84 
85 I wrote a bit more about the background of amused [in a blog
86 post](https://www.omarpolo.com/post/amused.html).