Quickstart

In about five minutes you will have a working radio station on your own machine. You will create a password, write a three-line config, start the server, send it a test tone, and listen.

You need Quikcast installed. The test tone uses FFmpeg; if you would rather use BUTT, skip to Connect an encoder.

1. Make a folder and a password

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

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

That creates a random 32-character password. Anything between 16 and 512 bytes works.

2. Write the config

Create quikcast.toml:

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

That's the whole file. It defines one mount, a stream at /radio.mp3, and says where its password lives. Everything else has a sensible 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

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

quikcast --config quikcast.toml

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

You should see a log line like quikcast accepting connections. 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:

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:

http://127.0.0.1:8000/radio.mp3

You should hear the tone. You have a radio station.

6. Look around

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

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 started sending audio. When your player asked for the same address, Quikcast handed it the live audio. Stop FFmpeg and the listener's stream ends, which is how live streaming works. Players reconnect when the encoder returns.

Next steps

• Use a real encoder: Connect an encoder
• Add more streams or a backup: Streams and mounts, Backup streams
• Make it reachable from the internet safely: HTTPS and proxies
• See every setting: Configuration reference