Configure FFmpeg WebSocket Stream Hosting

This article provides a step-by-step guide on how to configure FFmpeg to host a live stream using the WebSocket (websocket) protocol. You will learn the required FFmpeg command-line syntax, how to enable the listening mode so FFmpeg acts as the host server, and how to format the output stream for compatibility with web-based clients.

Verify FFmpeg WebSocket Support

Before hosting a stream, you must ensure that your FFmpeg build supports the WebSocket protocol. This protocol relies on the libwebsockets library. Run the following command in your terminal to check for support:

ffmpeg -protocols | grep ws

If configured correctly, the output should list ws (WebSocket) and wss (Secure WebSocket) under the enabled protocols.

Hosting a Direct WebSocket Stream (Listen Mode)

To host a stream directly from FFmpeg without an external web server, you must configure FFmpeg to run in "listen" mode. This is achieved by adding the ?listen=1 parameter to your WebSocket output URL.

Here is the standard command to host an input file or camera feed as an MPEG-TS stream over WebSockets:

ffmpeg -re -i input.mp4 -f mpegts -codec:v mpeg1video -b:v 800k -codec:a mp2 -ar 44100 ws://0.0.0.0:8080?listen=1

Command Breakdown:

  • -re: Tells FFmpeg to read the input in real-time (essential for live streaming).
  • -i input.mp4: Specifies your input source (this can be a file, an RTMP feed, or a hardware camera device).
  • -f mpegts: Forces the container format to MPEG Transport Stream (MPEG-TS), which is highly compatible with live streaming over raw network sockets.
  • -codec:v mpeg1video -b:v 800k: Encodes the video to MPEG-1 at a bitrate of 800 kbps (frequently used for low-latency browser players like JSMpeg).
  • -codec:a mp2 -ar 44100: Encodes the audio to MP2 with a sample rate of 44.1 kHz.
  • ws://0.0.0.0:8080?listen=1: Configures the WebSocket server. 0.0.0.0 allows connections from any IP address on port 8080, and ?listen=1 instructs FFmpeg to act as the server and wait for an incoming client connection.

Connecting a Client to the Stream

Once FFmpeg is running the command above, it will pause and wait for a client to connect before it begins encoding and transmitting the stream.

You can connect to this stream from a web browser or a compatible media player using the host's IP address. For example, if you are running the client on the same machine, the connection URL will be:

ws://localhost:8080

For web browser playback, you can use a JavaScript-based player such as JSMpeg to decode the MPEG-TS stream directly in an HTML5 canvas.

Important Considerations

  • Single Client Limitation: FFmpeg’s native ?listen=1 mode is designed to handle only one connection at a time. If a second client attempts to connect, they will be blocked. For multi-user distribution, stream from FFmpeg to an intermediate WebSocket relay server (like a Node.js relay) which then duplicates the stream to multiple clients.
  • Firewall Configuration: Ensure that the port you choose (e.g., 8080) is open in your system's firewall to allow external traffic to connect to the stream.