Quickstart ​

A working radio station on your own machine in about five minutes. You need Quikcast installed. The test tone uses FFmpeg; to use BUTT instead, skip to Connect an encoder.

1. Make a folder and a password ​

Your encoder needs a password to broadcast. Quikcast reads it from a file, so it never sits in your config.

sh
mkdir quikcast && cd quikcast
mkdir secrets
openssl rand -hex 16 > secrets/radio-source

That makes a random 32-character password. Anything from 16 to 512 bytes works.

2. Write the config ​

Create quikcast.toml:

toml
[[mounts]]
path = "/radio.mp3"
secret_file = "secrets/radio-source"

That's the whole file: one mount, a stream at /radio.mp3, and where its password lives. Everything else has a default, including listening on 127.0.0.1:8000.

Paths are relative to the config file

secrets/radio-source is looked up next to quikcast.toml, wherever you start the program from.

3. Check it, then start it ​

sh
quikcast --config quikcast.toml --check
# quikcast.toml: configuration ok

quikcast --config quikcast.toml

--check reads every file your config mentions and reports any problem without starting the server. Use it before every change.

Look for the log line quikcast accepting connections, and leave this window open.

4. Send some audio ​

In a second terminal, from the same folder, play a 440 Hz test tone into your mount:

sh
ffmpeg -re -f lavfi -i "sine=frequency=440" \
  -c:a libmp3lame -b:a 128k -content_type audio/mpeg -f mp3 \
  "icecast://source:$(cat secrets/radio-source)@127.0.0.1:8000/radio.mp3"

The username is source (the default), and the password is the contents of your secret file.

5. Listen ​

Open this in a browser, VLC, or any media player:

text
http://127.0.0.1:8000/radio.mp3

You should hear the tone.

6. Look around ​

Quikcast also runs a private admin address, only reachable from your own machine:

sh
curl http://127.0.0.1:9090/health/ready
curl http://127.0.0.1:9090/metrics | head

/health/ready answers 200 when the server is accepting work. /metrics is for monitoring tools.

What just happened? ​

FFmpeg authenticated as the owner of /radio.mp3 and sent audio, and Quikcast passed it to your player. If you stop FFmpeg the stream ends; players reconnect when the encoder returns.

Next steps ​