Stream Desktop Screen as HLS using FFmpeg

This guide explains how to capture your desktop screen activity and broadcast it directly as an HTTP Live Streaming (HLS) feed using the FFmpeg command-line tool. You will learn the exact commands required for Windows, macOS, and Linux, along with a breakdown of the key parameters used to segment and package the video stream in real-time.

FFmpeg Commands by Operating System

To record your screen, FFmpeg uses different input devices depending on your operating system. Choose the command that matches your environment.

Windows (using gdigrab)

ffmpeg -f gdigrab -framerate 30 -i desktop -c:v libx264 -pix_fmt yuv420p -preset ultrafast -g 60 -keyint_min 60 -sc_threshold 0 -f hls -hls_time 4 -hls_list_size 5 -hls_flags delete_segments stream.m3u8

macOS (using avfoundation)

ffmpeg -f avfoundation -framerate 30 -i "1:none" -c:v libx264 -pix_fmt yuv420p -preset ultrafast -g 60 -keyint_min 60 -sc_threshold 0 -f hls -hls_time 4 -hls_list_size 5 -hls_flags delete_segments stream.m3u8

(Note: Use ffmpeg -f avfoundation -list_devices true -i "" to find the exact index of your screen if “1” is not your default display).

Linux (using x11grab)

ffmpeg -f x11grab -framerate 30 -video_size 1920x1080 -i :0.0 -c:v libx264 -pix_fmt yuv420p -preset ultrafast -g 60 -keyint_min 60 -sc_threshold 0 -f hls -hls_time 4 -hls_list_size 5 -hls_flags delete_segments stream.m3u8

(Note: Change 1920x1080 to match your actual screen resolution).

Command Parameter Breakdown

Understanding the flags used in these commands allows you to customize the quality and performance of your stream:

1. Input Options

• -f gdigrab / avfoundation / x11grab: Specifies the platform-specific device driver used to grab the desktop screen.
• -framerate 30: Captures the screen at 30 frames per second.
• -i desktop / :0.0 / "1:none": Defines the input source.

2. Video Encoding Options

• -c:v libx264: Encodes the video stream to H.264, which is required for maximum HLS compatibility.
• -pix_fmt yuv420p: Sets the pixel format to YUV 4:2:0, ensuring the video plays back correctly on standard browsers and mobile devices.
• -preset ultrafast: Instructs the CPU to encode with the lowest possible latency and resource usage.
• -g 60 -keyint_min 60 -sc_threshold 0: Forces a keyframe (I-frame) every 60 frames (every 2 seconds at 30fps). This is critical for clean alignment of HLS segments.

3. HLS Packaging Options

• -f hls: Tells FFmpeg to output the stream in the HLS format.
• -hls_time 4: Sets the target duration for each TS (Transport Stream) video segment to 4 seconds.
• -hls_list_size 5: Keeps a maximum of 5 segments in the .m3u8 playlist file. This creates a rolling live window.
• -hls_flags delete_segments: Automatically deletes older TS video segments from your local disk as new ones are created to prevent storage from filling up.
• stream.m3u8: The name of the master playlist file generated by FFmpeg.

Serving and Playing the HLS Feed

Once the command runs, FFmpeg continuously generates the stream.m3u8 playlist and several .ts media segments in your working directory.

To make this stream accessible to viewers, point a web server (such as Nginx or Apache) to the directory containing these files. Viewers can then load the URL of the stream.m3u8 file into any HLS-compatible media player, such as VLC Media Player, Safari, Safari on iOS, or web-based players like Hls.js and Video.js.