Video & Codec Troubleshooting

This page covers video codec issues that affect live streaming, recorded playback, and event clip delivery in Meridian VMS. Most issues stem from browser codec limitations and camera firmware quirks.

H.265 (HEVC) Support

MediaMTX Version Requirement

H.265 cameras require MediaMTX v1.17.1 or later for WebRTC live streaming. Earlier versions do not support H.265 in their WebRTC implementation.

Verify the installed version:

mediamtx --version

If the version is below 1.17.1, update MediaMTX by downloading the latest release from the MediaMTX GitHub releases page and replacing the binary at /usr/local/bin/mediamtx.

Chrome SDP and H.265

Chrome’s WebRTC implementation does not include H.265 in its default SDP (Session Description Protocol) offer. When Chrome connects to a MediaMTX WebRTC endpoint for an H.265 camera, the codec negotiation fails silently and the stream does not play.

How Meridian VMS handles this:

The management API intercepts the WebRTC WHEP signalling and injects the H.265 codec into the SDP before forwarding it to MediaMTX. This ensures Chrome negotiates H.265 support even though it does not advertise it by default.

This injection is automatic and requires no user configuration. It is applied to all WebRTC streams where the source camera uses H.265.

Browser support

H.265 WebRTC playback with the SDP injection works in Chrome 107+ and Edge 107+ on Windows and macOS. Firefox does not support H.265 via WebRTC at this time.

Uniview SPS/PPS Issue

The Problem

Uniview cameras periodically change their SPS (Sequence Parameter Set) and PPS (Picture Parameter Set) parameters during streaming. This is a firmware-level behaviour that does not affect direct RTSP playback but causes failures in browser-based players.

When Chrome’s Media Source Extensions (MSE) encounters a mid-stream SPS/PPS change, it throws a bufferAppendError and stops playback. This manifests as:

• Live view freezing or going black after a period of normal playback
• Console errors: Uncaught DOMException: Failed to execute 'appendBuffer' on 'SourceBuffer'
• The HLS player reporting fragParsingError or bufferAppendError

Solution for Live View

Use WebRTC instead of HLS for live streaming. WebRTC handles SPS/PPS changes natively because the decoding is managed by the browser’s WebRTC stack rather than MSE.

Meridian VMS defaults to WebRTC for all live views. If you see this issue, verify that the live view is using WebRTC and not falling back to HLS:

1. Open the browser developer tools (F12)
2. Check the Network tab for WebRTC WHEP requests (POST to /whep)
3. If you see HLS requests (.m3u8, .ts) instead, the WebRTC connection may be failing — check the console for errors

Solution for Event Clips

Event clips are short recordings (typically 30 seconds) extracted from the continuous recording stream. Because these clips are served as MP4 files for download and in-browser playback, they must be compatible with MSE.

Meridian VMS normalises event clips to ensure universal browser compatibility:

This processing:

• Produces consistent SPS/PPS parameters throughout the clip
• Converts H.265 sources to H.264 for universal browser compatibility
• Uses a fast processing mode to minimise encoding time (quality loss is minimal for 30-second clips)
• Optimises for progressive download without buffering the entire file

Re-encoding exception

This is the only place in Meridian VMS where video is re-encoded. All other recording and streaming operations preserve the original camera stream with no re-encoding, maintaining full quality and minimising CPU usage.

Sub-Stream Fallback

Many IP cameras offer two RTSP streams:

Main stream : Full resolution, high bitrate. Used for recording.

Sub-stream : Lower resolution, reduced bitrate. Used for AI detection (to reduce GPU memory) and optionally for live view thumbnails.

When Sub-Stream Is Unavailable

Some cameras do not enable the sub-stream by default, or the sub-stream URL format differs from what is configured. When Meridian VMS cannot connect to the configured sub-stream:

1. The system logs a warning indicating the sub-stream is unreachable
2. AI detection falls back to using the main stream (which uses more GPU memory per camera)
3. Recording continues normally on the main stream

Configuring Sub-Stream

Sub-stream URLs are configured per camera in Settings > Cameras & Sites > Cameras. When editing a camera, the Sub-Stream URL field accepts the full RTSP URL for the secondary stream.

Finding the sub-stream URL

Use ONVIF discovery to automatically detect both main and sub-stream URLs. If ONVIF is not available, consult your camera manufacturer’s documentation. Common sub-stream path patterns include /stream2, /ch0_1, and /Streaming/Channels/102.

FFmpeg Codec Detection Failures

Exit Code 234

FFmpeg exit code 234 indicates that codec parameters could not be determined from the input stream. This typically means FFmpeg could not find a keyframe within the analysis window.

Diagnostic steps:

1. Test the stream manually using ffprobe against the camera’s RTSP URL to verify codec compatibility.

2. If ffprobe succeeds with extended analysis parameters but the segmenter fails, the camera’s keyframe interval may be too long. Configure the camera to use a 1-2 second keyframe interval (GOP size).

3. If ffprobe fails entirely, the issue is likely network connectivity or an invalid RTSP URL.

Unsupported Codec

If a camera outputs a codec other than H.264 or H.265 (e.g., MJPEG, MPEG-4), FFmpeg will still record the stream but:

• WebRTC live view will not work (WebRTC requires H.264 or H.265)
• Browser playback of recordings may fail depending on the codec

MJPEG cameras

MJPEG-only cameras are not recommended for use with Meridian VMS. While recording will work, live view and playback features depend on H.264 or H.265 streams. Most modern IP cameras support H.264 at minimum.