Audioserve

Audioserve is a web audiobook server with a minimalist design. It focuses on delivering audio based on the directory structure you’ve created, eschewing tags embedded in the audio files. Anyone who has worked with internet-sourced audio content will know wisdom of this approach.

Installation

Create an audioserve user and obtain the latest static binary and web client

sudo adduser --system --home /opt/audioserve --disabled-password --disabled-login  audioserve

# Download the latest binary to a version folder and create a link for it.
cd /opt/audioserve/
wget -q -O - https://github.com/izderadicka/audioserve/releases/latest/download/audioserve_static.tar.gz | sudo tar xvz
sudo ln -s audioserve_static*/* audioserve

# Download the web-client.
# You'll have to check on the web at https://github.com/izderadicka/audioserve-web/releases/latest/ to see what the current relase is.
# and updat the VER variable accordingly (and check the sketchy nature of using this naming convention in a script)
VER=0.3.3
sudo mkdir /opt/audioserve/audioserve-web-release_v${VER}
cd /opt/audioserve/audioserve-web-release_v${VER}
wget -q -O - https://github.com/izderadicka/audioserve-web/releases/download/v${VER}/audioserve-web-release_v${VER}.tgz | sudo tar xvz
sudo ln -s /opt/audioserve/audioserve-web-release_v${VER} /opt/audioserve/web

Get a ffmpeg binary. Audioserve needs ffmpeg for transcoding media that clients cant directly play. The apt package is quite large, but you can download the static binary at a fraction of the size.

wget -q -O - https://johnvansickle.com/ffmpeg/builds/ffmpeg-git-amd64-static.tar.xz | \
sudo tar -C /usr/local/bin -xvJ --strip-components 1 --wildcards "*ffmpeg" "*ffprobe"

Create a service script. This has the parameter no-authentication as we’ll be relying on a web server proxy to do that for us.

sudo vi /etc/systemd/system/audioserve.service

[Unit]
Description=Audioserve

[Service]
ExecStart=/opt/audioserve/audioserve --config /etc/audioserve.conf --no-authentication
User=audioserve

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable audioserve.service

Configuration

sudo vi /etc/audioserve.conf

behind_proxy: true
client_dir: /opt/audioserve/web
base_dirs:
  - /some/place/where/your/audio/is
  - /some/place/where/other/audio/is

Operation

Start the service and check it with:

sudo systemctl start audioserve.service
sudo systemctl status audioserve.service
sudo journalctl -u audioserve.service

You can access the web client on port 3000. It may display a banner about the lack of SSL but that is safe to ignore as you test it out. Having more than one base_dir in the config will populate a drop-down at the top. This is convenient if you have separated your library into genres, like Fantasy, Fiction, etc.

To display metadata, simply put image and text file in the folders alongside the audio files. In each folder, the first available image (jpeg or png) is taken as a cover/author picture and first text file (html, txt, md) is taken as description.

Proxy

A good choice is Caddy, and a config file with just these lines in it will work just fine - as long as you actually own the some.web.server domain. This will pop up a login box ala web basic auth and serve it up at the root of that DNS name.

caddy hash-password

sudo vi /etc/caddy/Caddyfile

(auth) {
        basicauth {
                you ABIGLONGHASHFromAbove
	}
}



some.web.server {
        import auth
        reverse_proxy * http://localhost:3000
}

sudo caddy reload

After you have things working the way you want, you can disable direct access to audioserve by adding this to the config

listen: "127.0.0.1:3000"

Note: Securing the web client this way is more secure, but it prevents the android client from working. Workarounds with wireguard and such can be done but take additional setup.

Troubleshooting

# Launch it in the foreground to see the errors up close
/opt/audioserve/audioserve --no-authentication --config /etc/audioserve.conf

# Print out all the options
/opt/audioserve/audioserve --help

# Figure out what should be in a YAML file by specifiying all the options on the command line and then printing the config. Can be tricky
/opt/audioserve/audioserve --config /etc/audioserve.conf --no-authentication --print-config

If you decide not to proxy with a web server, you’ll want to:

  • remove the --no-authentication parameter from the service unit file
  • and add shared_secret: somePassword and remove behind_proxy from the conf file

Last modified April 14, 2026: Old site imports (677647f)