Skip to main content
Version: Developer

Video Streaming Mode

KasmVNC includes a video streaming mode that uses hardware-accelerated or software video encoders to efficiently stream desktop content to web clients. This feature enables low-latency, high-quality remote desktop experiences using modern video codecs.

Overview​

Video streaming mode leverages FFmpeg and optionally VAAPI (Video Acceleration API) or NVENC hardware acceleration to encode the desktop in real-time using H.264, H.265/HEVC, and AV1 codecs. The encoded video stream is transmitted to web clients.

Key Features​

  • Hardware Acceleration: Automatic detection and use of VAAPI-compatible GPUs or NVIDIA GPUs with NVENC support
  • Multiple Codecs: Support for H.264, H.265/HEVC, and AV1
  • Low Latency: Optimized for real-time streaming with minimal buffering
  • Automatic Fallback: Gracefully falls back to software encoding if hardware acceleration is unavailable

Supported Codecs​

H.264/AVC​

The most widely supported codec with excellent compatibility across all modern browsers.

Variants:

  • h264_vaapi or avc_vaapi - Hardware-accelerated via VAAPI
  • h264_nvenc or avc_nvenc - Hardware-accelerated via NVIDIA NVENC
  • h264 - Software encoding via libx264
  • avc - Alias for h264

Recommended for: Maximum compatibility, balanced performance

H.265/HEVC​

Better compression than H.264, resulting in lower bandwidth usage for the same quality.

Variants:

  • h265_vaapi or hevc_vaapi - Hardware-accelerated via VAAPI
  • h265_nvenc or hevc_nvenc - Hardware-accelerated via NVIDIA NVENC
  • h265 - Software encoding via libx265
  • hevc - Alias for h265

Recommended for: Bandwidth-constrained scenarios

AV1​

Modern codec with strong compression efficiency. Browser and GPU support varies more than H.264 and H.265/HEVC, so test client compatibility before making it the only allowed codec.

Variants:

  • av1_vaapi - Hardware-accelerated via VAAPI
  • av1_nvenc - Hardware-accelerated via NVIDIA NVENC
  • av1 - AV1 codec selector

Recommended for: Experimental deployments where all clients and the selected GPU support AV1

Configuration​

Command-Line Parameters​

VideoCodec​

Specifies which video codec(s) to use for streaming.

-VideoCodec <codec1,codec2,...>

Options:

  • auto - Automatically select the best available encoder (default behavior)
  • h264 - Force H.264 software encoding
  • avc - Alias for h264
  • h264_vaapi - Force H.264 VAAPI hardware encoding
  • avc_vaapi - Alias for h264_vaapi
  • h264_nvenc - Force H.264 NVIDIA NVENC hardware encoding
  • avc_nvenc - Alias for h264_nvenc
  • h265 - Force H.265 software encoding
  • hevc - Alias for h265
  • h265_vaapi - Force H.265 VAAPI hardware encoding
  • hevc_vaapi - Alias for h265_vaapi
  • h265_nvenc - Force H.265 NVIDIA NVENC hardware encoding
  • hevc_nvenc - Alias for h265_nvenc
  • av1 - Force AV1 encoding
  • av1_vaapi - Force AV1 VAAPI hardware encoding
  • av1_nvenc - Force AV1 NVIDIA NVENC hardware encoding

You can specify multiple codecs as fallback options (comma-separated without space, tried in order):

Xvnc :1 -VideoCodec h265_nvenc,h265_vaapi,h264_nvenc,h264_vaapi,h264

When set to auto, KasmVNC probes available encoders in preference order and uses the first encoder that is supported by both the server and the client. Hardware encoders are preferred when available.

VideoQualityCRFCQP​

Controls the video encoding quality using CRF (Constant Rate Factor) for software encoders or CQP (Constant Quantization Parameter) for hardware encoders.

-VideoQualityCRFCQP <0-63>

Default: 17

Guidelines:

  • 0 - Lossless encoding, maximum bandwidth
  • 1-18 - Very high quality, maximum bandwidth
  • 18-23 - High quality, recommended for most use cases
  • 23-28 - Medium quality, balanced
  • 28-35 - Lower quality, bandwidth constrained
  • 35-51 - Low quality, minimal bandwidth for H.264/H.265
  • 52-63 - Lowest quality AV1 range

Lower values = better quality + higher bitrate

Recommended Quality Presets:

H.264 Software (libx264):

  • Preset 0: CRF 0 (Excellent - near lossless)
  • Preset 1: CRF 18 (High quality)
  • Preset 2: CRF 26 (Balanced)
  • Preset 3: CRF 33 (Low bandwidth)
  • Preset 4: CRF 42 (Minimum quality)

H.264 FFMPEG VAAPI:

  • Preset 0: QP 0 (Excellent)
  • Preset 1: QP 18 (High quality)
  • Preset 2: QP 26 (Balanced)
  • Preset 3: QP 33 (Low bandwidth)
  • Preset 4: QP 39 (Minimum quality)

H.264/H.265 NVENC:

  • Preset 0: CQP 18 (High quality)
  • Preset 1: CQP 23 (Balanced)
  • Preset 2: CQP 28 (Medium bandwidth)
  • Preset 3: CQP 39 (Low bandwidth)
  • Preset 4: CQP 50 (Minimum quality)

AV1 NVENC:

  • Preset 0: CQP 19 (High quality)
  • Preset 1: CQP 23 (Balanced)
  • Preset 2: CQP 28 (Medium bandwidth)
  • Preset 3: CQP 39 (Low bandwidth)
  • Preset 4: CQP 62 (Minimum quality)
Quality Scale Inversion

IMPORTANT: The video quality scale is inverted between the server CLI and the client UI:

  • Server CLI (-VideoQualityCRFCQP): Lower values (0-18) = better quality, higher values (28-63) = lower quality
  • Client UI (Video Stream Quality slider): Higher values (43-51) = better quality, lower values (0-20) = lower quality

The conversion formula is: server_value = max_quality - client_value

For example, with H.264 FFMPEG VAAPI (max_quality = 51):

  • Client UI value 51 → Server uses CRF 0 (best quality)
  • Client UI value 33 (default) → Server uses CRF 18 (balanced)
  • Client UI value 0 → Server uses CRF 51 (lowest quality)

When setting quality via CLI, remember that lower CLI values = better quality, which is the opposite of what users see in the web UI.

GroupOfPicture​

Sets the GOP (Group of Pictures) size, which determines the interval between keyframes (I-frames).

-GroupOfPicture <0-100>

Default: 24

Guidelines:

  • 12-15 - More responsive, higher bitrate, better for dynamic content
  • 24-30 - Balanced (recommended)
  • 30-60 - Lower bitrate, acceptable for static content

Lower values = more keyframes = more responsive + higher bitrate

FrameRate​

Sets the target framerate for video encoding.

-FrameRate <10-60>

Default: Depends on existing configuration (typically 30)

Guidelines:

  • 60 - Smooth motion, high bandwidth
  • 30 - Standard, balanced
  • 24 - Cinematic, lower bandwidth
  • 15-20 - Low bandwidth scenarios

driNode​

Specifies the DRM (Direct Rendering Manager) device path for hardware acceleration.

-drinode <path>

Default: Auto-detect (tries /dev/dri/renderD128, /dev/dri/card0, etc.)

Example:

Xvnc :1 -drinode /dev/dri/renderD128

Only needed if you have multiple GPUs and want to select a specific one, or if auto-detection fails.

Configuration Examples​

Maximum Quality (High Bandwidth)​

Xvnc :1 \
  -VideoCodec h265_nvenc,h265_vaapi,h264_nvenc,h264 \
  -VideoQualityCRFCQP 15 \
  -GroupOfPicture 12 \
  -FrameRate 60
Xvnc :1 \
  -VideoCodec h264_nvenc,h264_vaapi,h264 \
  -VideoQualityCRFCQP 23 \
  -GroupOfPicture 24 \
  -FrameRate 30

Low Bandwidth​

Xvnc :1 \
  -VideoCodec h265_nvenc,h265_vaapi,h265,h264 \
  -VideoQualityCRFCQP 30 \
  -GroupOfPicture 60 \
  -FrameRate 24

Use case: Remote locations, limited internet, primarily static content

Software Encoding Only​

Xvnc :1 \
  -VideoCodec h264 \
  -VideoQualityCRFCQP 25

Multi-GPU Selection​

Xvnc :1 \
  -VideoCodec h264_nvenc \
  -drinode /dev/dri/renderD129

Hardware Acceleration​

For information about supported GPUs and driver installation, see the GPU Acceleration guide.

info

Note: To use GPU accelerated encoding with video streaming mode, the hw3d option is not necessary. Video streaming mode can use hardware acceleration independently through VAAPI or NVENC without requiring 3D hardware acceleration to be enabled.

VAAPI acceleration is available on AMD and Intel platforms. NVENC acceleration is available on supported NVIDIA GPUs. However, you may need to specify the -drinode path if auto-detection fails or if you want to use a specific GPU on multi-GPU systems.

Prerequisites​

For VAAPI hardware acceleration to work, you need the system packages:

  • libva
  • libdrm
  • vainfo (for testing)
  • mesa-va-drivers (AMD)
  • intel-media-va-driver (Intel)

For NVENC hardware acceleration to work, you need:

  • A supported NVIDIA GPU
  • NVIDIA drivers installed and loaded
  • FFmpeg libraries with NVENC encoder support
  • Access to the NVIDIA DRM device under /dev/dri/

Verifying Hardware Acceleration​

Check if VAAPI is available:

vainfo --display drm

Expected output should show available profiles:

libva info: VA-API version 1.20.0
libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/radeonsi_drv_video.so
libva info: Found init function __vaDriverInit_1_20
libva info: va_openDriver() returns 0
vainfo: VA-API version: 1.20 (libva 2.12.0)
vainfo: Driver version: Mesa Gallium driver 25.0.7-0ubuntu0.24.04.2 for AMD Radeon Graphics (radeonsi, renoir, ACO, DRM 3.57, 6.8.0-90-generic)
vainfo: Supported profile and entrypoints
      VAProfileMPEG2Simple            : VAEntrypointVLD
      VAProfileMPEG2Main              : VAEntrypointVLD
      VAProfileVC1Simple              : VAEntrypointVLD
      VAProfileVC1Main                : VAEntrypointVLD
      VAProfileVC1Advanced            : VAEntrypointVLD
      VAProfileH264ConstrainedBaseline: VAEntrypointVLD
      VAProfileH264ConstrainedBaseline: VAEntrypointEncSlice
      VAProfileH264Main               : VAEntrypointVLD
      VAProfileH264Main               : VAEntrypointEncSlice
      VAProfileH264High               : VAEntrypointVLD
      VAProfileH264High               : VAEntrypointEncSlice
      VAProfileHEVCMain               : VAEntrypointVLD
      VAProfileHEVCMain               : VAEntrypointEncSlice
      VAProfileHEVCMain10             : VAEntrypointVLD
      VAProfileHEVCMain10             : VAEntrypointEncSlice
      VAProfileJPEGBaseline           : VAEntrypointVLD
      VAProfileVP9Profile0            : VAEntrypointVLD
      VAProfileVP9Profile2            : VAEntrypointVLD
      VAProfileNone                   : VAEntrypointVideoProc

Check if NVENC encoders are available in FFmpeg:

ffmpeg -hide_banner -encoders | grep nvenc

Expected output should include one or more hardware encoders:

V....D h264_nvenc           NVIDIA NVENC H.264 encoder
V....D hevc_nvenc           NVIDIA NVENC hevc encoder
V....D av1_nvenc            NVIDIA NVENC av1 encoder

Check DRM device permissions:

ls -l /dev/dri/

Ensure your user has read/write access:

crw-rw---- 1 root video  226,   0 Jan  6 18:23 card0
crw-rw---- 1 root render 226, 128 Jan  6 18:23 renderD128

Add user to video/render group if needed:

sudo usermod -aG render $USER

Then log out and log back in to apply the group change.

Troubleshooting Hardware Acceleration​

Issue: VAAPI initialization fails

FFMPEGVAAPIEncoder: Failed to create VAAPI device context

Solutions:

  1. Verify VAAPI drivers are installed
  2. Check device permissions (/dev/dri/*)
  3. Try specifying device explicitly: -drinode /dev/dri/renderD128
  4. Check if device is already in use by another process
  5. Review system logs: dmesg | grep -i drm

Issue: Encoder not found

EncoderProbe: Could not find h264_vaapi encoder

Solutions:

  1. Verify FFmpeg was compiled with the required encoder support: ffmpeg -encoders | grep -E 'vaapi|nvenc'
  2. Install FFmpeg with the needed encoder support: sudo apt install ffmpeg libavcodec-extra
  3. For NVENC, verify NVIDIA drivers are installed and the GPU supports the selected codec
  4. Fall back to software encoding: -VideoCodec h264

Issue: Poor encoding performance

Solutions:

  1. Verify hardware acceleration is actually being used (check CPU usage)
  2. Reduce quality settings: -VideoQualityCRFCQP 28
  3. Reduce framerate: -FrameRate 24
  4. Increase GOP size: -GroupOfPicture 60

Codec Negotiation​

Clients advertise codec support via pseudo-encodings:

H.264:

  • -1029 - H.264 NVENC
  • -1028 - H.264 VAAPI
  • -1027 - H.264 Software
  • -1026 - H.264 (generic)

H.265:

  • -1034 - H.265 NVENC
  • -1033 - H.265 VAAPI
  • -1032 - H.265 Software
  • -1031 - H.265 (generic)

AV1:

  • -1039 - AV1 NVENC
  • -1038 - AV1 VAAPI
  • -1037 - AV1 Software
  • -1036 - AV1 (generic)

Skip Frames​

When encoding fails or is unavailable, a skip frame is sent. Clients should maintain the previous frame content.

Monitoring and Statistics​

Enable Debug Logging​

Xvnc :1 -Log *:stderr:100

Browser Support​

WebCodecs API (recommended):

  • Chrome/Edge 94+
  • Opera 80+
  • Safari 16.4+ (partial)
  • Firefox: 130

Limitations​

Current Limitations​

  1. Dimensions: Width and height must be even numbers (YUV420P requirement)
  2. Color subsampling: YUV420P reduces chroma resolution (may affect color accuracy)
  3. Hardware acceleration: Platform and driver dependent
  4. GOP size: Maximum 100 frames

Known Issues​

  1. Odd dimensions: Automatically rounded down to even numbers, may cause 1-pixel offset
  2. VAAPI stability: Some driver versions may have stability issues
  3. Multi-GPU: Auto-detection may not select optimal GPU on multi-GPU systems