Broadcast Box lets you broadcast/screen-share to friends in sub-second time. It was designed to be simple to use and easily modifiable. Broadcast Box uses WebRTC, to learn more see the OBS WHIP Streaming Guide
Want to contribute to the development of Broadcast Box? See Contributing.
A public instance of Broadcast Box is hosted at b.siobud.com. Feel free to use this as much as you want. Go to Getting Started for instructions on running it locally.
To use Broadcast Box with OBS you must set your output to WebRTC and set a proper URL + Stream Key. You may use any Stream Key you like. The same stream key is used for broadcasting and playback.
Go to Settings -> Stream and set the following values.
- Service: WHIP
- Server: https://b.siobud.com/api/whip
- StreamKey: (Any Stream Key you like)
Your settings page should look like this:
OBS by default will have ~2 seconds of latency. If you want sub-second latency you can configure
this in Settings -> Output. Set your encoder to x264 and set tune to zerolatency. Your Output
page will look like this.
When you are ready to broadcast press Start Streaming and now time to watch!
The following broadcasts a test feed to https://b.siobud.com with a Bearer Token of ffmpeg-test
ffmpeg \
-re \
-f lavfi -i testsrc=size=1280x720 \
-f lavfi -i sine=frequency=440 \
-pix_fmt yuv420p -vcodec libx264 -profile:v baseline -r 25 -g 50 \
-acodec libopus -ar 48000 -ac 2 \
-f whip -authorization "ffmpeg-test" \
"https://b.siobud.com/api/whip"See the example script here.
Can broadcast gstreamer's test sources, or pulsesrc+v4l2src
Expects gstreamer-1.0, with good,bad,ugly plugins and gst-plugins-rs
Use of example scripts:
# testsrcs
./examples/gstreamer-broadcast.sh http://localhost:8080/api/whip testStream1
# v4l2src
./examples/gstreamer-broadcast.sh http://localhost:8080/api/whip testStream1 v4l2If you are broadcasting to the Stream Key StreamTest your video will be available at https://b.siobud.com/StreamTest.
You can also go to the home page and enter StreamTest. The following is a screenshot of OBS broadcasting and
the latency of 120 milliseconds observed.
Broadcast Box is made up of two parts. The server is written in Go and is in charge of ingesting and broadcasting WebRTC. The frontend is in react and connects to the Go backend. The Go server can be used to serve the HTML/CSS/JS directly. Use the following instructions to build from source or utilize Docker / Docker Compose.
Configurations can be made in .env.production, although the defaults should get things going.
React dependencies are installed by running npm install in the web directory and npm run build will build the frontend.
If everything is successful, you should see output similar to:
> broadcast-box@0.1.0 build
> vite build
[dotenv@17.2.3] injecting env (0) from ../.env.development,../.env -- tip: ⚙️ load multiple .env files with { path: ['.env.local', '.env'] }
Target Backend: http://localhost:8080
vite v6.4.1 building for production...
✓ 724 modules transformed.
build/index.html 0.84 kB │ gzip: 0.49 kB
build/assets/index-BZVYZNKC.css 20.37 kB │ gzip: 4.82 kB
build/assets/index-BeQC1JnS.js 1.43 kB │ gzip: 0.69 kB
build/assets/components-BcOZaJ_1.js 63.11 kB │ gzip: 16.08 kB
build/assets/node-DpLsG32O.js 239.39 kB │ gzip: 75.76 kB
✓ built in 601msGo dependencies are automatically installed.
To run the Go server, run go run . in the root of this project, you should see the following:
2022/12/11 16:02:14 Loading `.env.production`
2022/12/11 16:02:14 Running HTTP Server at `:8080`To use Broadcast Box navigate to: http://<YOUR_IP>:8080. In your broadcast tool of choice, you will broadcast to http://<YOUR_IP>:8080/api/whip.
A Docker image is also provided to make it easier to run locally and in production. The arguments you run the Dockerfile with depending on if you are using it locally or a server.
If you want to run locally execute docker run -e UDP_MUX_PORT=8080 -e NAT_1_TO_1_IP=127.0.0.1 -p 8080:8080 -p 8080:8080/udp seaduboi/broadcast-box.
This will make broadcast-box available on http://localhost:8080. The UDPMux is needed because Docker on macOS/Windows runs inside a NAT.
If you are running on AWS (or other cloud providers) execute. docker run --net=host -e INCLUDE_PUBLIC_IP_IN_NAT_1_TO_1_IP=yes seaduboi/broadcast-box
broadcast-box needs to be run in net=host mode. broadcast-box listens on random UDP ports to establish sessions.
A Docker Compose is included that uses LetsEncrypt for automated HTTPS. It also includes Watchtower so your instance of Broadcast Box will be automatically updated every night. If you are running on a VPS/Cloud server this is the quickest/easiest way to get started.
export URL=my-server.com
docker-compose up -dThe frontend can be configured by passing these URL Parameters.
cinemaMode=true- Forces the player into cinema mode by adding to end of URL like https://b.siobud.com/myStream?cinemaMode=true
| Variable | Description |
|---|---|
HTTP_ADDRESS |
Address for the HTTP server to bind to. |
ENABLE_HTTP_REDIRECT |
Enables automatic redirection from HTTP to HTTPS. |
HTTPS_REDIRECT_PORT |
Port to redirect HTTP traffic to HTTPS when using HTTPS. |
NETWORK_TEST_ON_START |
If "true", checks network connectivity on startup. |
DISABLE_STATUS |
Disables the status API endpoint. |
ENABLE_PROFILING |
Enables PPROF profiling on localhost:6060 |
| Variable | Description |
|---|---|
USE_SSL |
Setup the server to run with SSL. |
SSL_CERT |
Path to the SSL certificate file. |
SSL_KEY |
Path to the SSL key file. |
| Variable | Description |
|---|---|
STREAM_PROFILE_PATH |
Path to store stream profile configurations. |
STREAM_PROFILE_POLICY |
Policy configuration for stream profiles. Default is 'Anyone' See Stream Profile Policy. |
WEBHOOK_URL |
URL for webhook backend used for authentication and logging. see Webhook - Authentication and Logging. |
| Variable | Description |
|---|---|
DISABLE_FRONTEND |
Disables frontend serving. |
FRONTEND_PATH |
Path to frontend assets. |
FRONTEND_ADMIN_TOKEN |
Admin token for frontend access. |
| Variable | Description |
|---|---|
INCLUDE_PUBLIC_IP_IN_NAT_1_TO_1_IP |
Automatically includes public IPs in NAT configuration. |
NAT_1_TO_1_IP |
Manually specify IPs (like Public IP) to announce, delineated by | |
INTERFACE_FILTER |
Restrict UDP traffic to a specific network interface. |
NAT_ICE_CANDIDATE_TYPE |
Set to srflx to append IPs instead of overriding with NAT_1_TO_1_IP. |
NETWORK_TYPES |
List of network types to use delineated by | (e.g.,udp4 |udp6). |
INCLUDE_LOOPBACK_CANDIDATE |
Enables WebRTC traffic on loopback interface. |
UDP_MUX_PORT |
Port to multiplex all UDP traffic. Uses random port by default. |
UDP_MUX_PORT_WHEP |
Port to multiplex WHEP traffic only. |
UDP_MUX_PORT_WHIP |
Port to multiplex WHIP traffic only. |
TCP_MUX_ADDRESS |
Address to serve WebRTC traffic over TCP. |
TCP_MUX_FORCE |
Forces WebRTC traffic to use TCP only. |
APPEND_CANDIDATE |
Appends ICE candidates not generated by the agent. |
| Variable | Description |
|---|---|
STUN_SERVERS |
List of STUN servers separated by |. |
These values are parsed by the Go backend and applied to WHIP/WHEP PeerConnection configuration server-side. Clients do not fetch ICE server configuration from an API endpoint.
| Variable | Description |
|---|---|
DEBUG_PRINT_OFFER |
Prints WebRTC offers received from clients. |
DEBUG_PRINT_ANSWER |
Prints WebRTC answers sent to clients. |
DEBUG_INCOMING_API_REQUEST |
Logs incoming API request paths. |
DEBUG_PRINT_SSE_MESSAGES |
Logs Server-Sent Events messages. |
| Variable | Description |
|---|---|
LOGGING_ENABLED |
Enables logging system. |
LOGGING_DIRECTORY |
Directory to store log files. |
LOGGING_SINGLEFILE |
Logs everything into a single file called 'log'. Default is log files are stamped with current date. |
LOGGING_NEW_FILE_ON_STARTUP |
Creates a new log file on each startup. Either a new 'log' file, or replaces the current dates log file. |
LOGGING_API_ENABLED |
Enables logging API to show current log entries on the backend. /api/log |
LOGGING_API_KEY |
When set, the logging API requires a bearer token that uses this key. |
The STREAM_PROFILE_POLICY environment variable controls who is allowed to initiate streaming sessions based on profile reservation status.
| Value | Description |
|---|---|
ANYONE_WITH_RESERVED |
If Stream keys are reserved in advance, only a valid token can be used with them. If not reserved, anyone can used the streamkey |
RESERVED |
Only users with a valid token and a reserved stream key are allowed to stream. This is the most restrictive mode. |
To prevent random users from streaming to your server, you can set the WEBHOOK_URL and validate/process requests in your code. This enables you to separate the authorization between broadcasting (whip) and watching (whep). So you can safely share a watch link without exposing the key used for broadcasting.
If the request succeeds (meaning the stream key is accepted), broadcast-box redirects the stream to an url given by the external server, otherwise the streaming request is dropped.
See here. For an example Webhook Server that only allows the stream broadcastBoxRulez
For a more advanced example of a webhook server implementation making use of separating the key for streaming from the key for watching, see the broadcastbox-webhookserver repository.
When running in Docker Broadcast Box runs a network tests on startup. This tests that WebRTC traffic can be established against your server. If you server is misconfigured Broadcast Box will not start.
If the network test is enabled this will be printed on startup
NETWORK_TEST_ON_START is enabled. If the test fails Broadcast Box will exit.
See the README.md for how to debug or disable NETWORK_TEST_ON_STARTIf the test passed you will see
Network Test passed.
Have fun using Broadcast BoxIf the test failed you will see the following. The middle sentence will change depending on the error.
Network Test failed.
Network Test client reported nothing in 30 seconds
Please see the README and join Discord for helpJoin the Discord and we are ready to help! To debug check the following.
- Have you allowed UDP traffic?
- Do you have any restrictions on ports?
- Is your server publicly accessible?
If you wish to disable the test set the environment variable NETWORK_TEST_ON_START to false.
The backend exposes the following endpoints to support WebRTC streaming and server-side monitoring:
| Endpoint | Description |
|---|---|
/api/whip |
Initiates a WHIP session for broadcasting video via WebRTC. Requires the Authorization header with a bearer token |
/api/whep |
Initiates a WHEP session for video playback via WebRTC. |
/api/status |
Returns the status of all active WHIP streams. If a Stream Profile is not public, it will not be included. |
/api/log |
Retrieves current server logs. Useful for debugging and monitoring runtime activity. |