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) or libao
23  - libmd (optional; needed by amused-web on linux and Mac)
24 
25 Then, to build:
26 
27 	$ ./configure
28 	$ make
29 	# make install # eventually
30 
31 To compile the web control interface, amused-web, run:
32 
33 	$ make web
34 	# make install-web # eventually
35 
36 The build can be customized by passing arguments to the configure
37 script or by using a `configure.local` file; see `./configure -h`
38 and [`configure.local.example`](configure.local.example) for more
39 information.
40 
41 For each library the `configure` script first tries to see if they're
42 available without any extra flags, then tries again with some
43 hard-coded flags (e.g. `-lFLAC` for flac) and finally resorts to
44 pkg-config if available.  pkg-config auto-detection can be disable by
45 passing `PKG_CONFIG=false` (or the empty string)
46 
47 For Linux users with libbsd installed, the configure script can be
48 instructed to use libbsd exclusively as follows:
49 
50 	$ CFLAGS="$(pkg-config --cflags libbsd-overlay)" \
51 		./configure LDFLAGS="$(pkg-config --libs libbsd-overlay)"
52 
53 To force the use of one specific audio backend and not simply the first
54 one found, pass `--backend` as:
55 
56 	$ ./configure --backend=alsa # or sndio, or ao
57 
58 
59 ## Usage
60 
61 The fine man page has all nitty gritty details, but the TL;DR is
62 
63  - enqueue music with `amused add files...` or `amused load <playlist`
64  - control the playback with `amused play|pause|toggle|stop`
65  - check the status with `amused status` and the current playlist with
66    `amused show`
67 
68 amused tries to be usable in composition with other more familiar tools
69 instead of providing everything itself.  For instance, there isn't a
70 command to remove an item from the playlist, or shuffle it; instead,
71 standard UNIX tools can be used:
72 
73 	$ amused show | grep -vi kobayashi | amused load
74 	$ amused show | sort -R | amused load
75 	$ amused show | sort | uniq | amused load
76 
77 It also doesn't provide any means to manage a music collection.  It
78 plays nice with find(1) however:
79 
80 	$ find . | amused load
81 
82 Non-music files found in the playlist are automatically skipped and
83 removed, so there's no harm in loading everything under a certain
84 directory.
85 
86 I wrote a bit more about the background of amused [in a blog
87 post](https://www.omarpolo.com/post/amused.html).
88 
89 
90 ## Building on Android (termux) -- Experimental
91 
92 amused can be built on android using the oboe [oboe][oboe] backend,
93 although this has only been tested so far under [termux][termux].
94 First, oboe needs to be built locally.  Then build amused with:
95 
96 	$ ./configure BACKEND=oboe \
97 		CXXFLAGS="-I /path/to/oboe/include" \
98 		LDADD="/path/to/liboboe.a"
99 	[...]
100 	$ make
101 
102 tip: use `termux-setup-storage` to access the android storage in
103 `~/storage`.
104 
105 amused-web works and can be used to control the playback, but as amused
106 doesn't respond to the events (calls, headsets buttons, other apps
107 playing music, etc...) it's not particularly handy to be used.
108 
109 contrib/amused-termux-notification shows a persistent notification with
110 the song file name and buttons to control the playback, making slightly
111 more nicer to use amused on android.
112 
113 [oboe]: https://github.com/google/oboe/
114 [termux]: https://termux.dev/en/