Unifi Protect Time Lapse

High-Quality Surveillance Recordings Made Simple

Introducing Our Solution

Unifi Protect Time Lapse is a Docker-based application designed to create beautiful, high-quality time-lapse videos from your Unifi Protect cameras. This lightweight, easy-to-deploy solution automatically captures images from your cameras at configurable intervals. It compiles them into daily time-lapse videos that provide a condensed view of activity around your property.

Originally developed to provide advanced time-lapse functionality missing from the Unifi Protect interface, our solution offers flexible scheduling, customizable quality settings, and a simple Docker deployment that works on virtually any system – from dedicated servers to Raspberry Pi devices.

Key features include:

  • Multiple capture intervals for different cameras (15s, 60s, or custom)
  • Individual camera scheduling for targeted recording
  • High-quality PNG image capture for maximum detail
  • Configurable video quality presets for the resulting time-lapses
  • Multi-architecture support (AMD64, ARM64, and ARMv7)
  • Automatic daily time-lapse compilation with flexible scheduling

Why We Switched to FFMPEG for Unifi Protect Time Lapse

The snap.jpeg Problem

In early 2024, Ubiquiti significantly changed how Unifi Protect cameras handle direct snapshot requests. As documented in this community forum thread, the quality of images from the /snap.jpeg endpoint was dramatically reduced.

Users reported that what was once a high-resolution, clear image suitable for documentation and time-lapse creation had been downgraded to a low-resolution, heavily compressed image that many described as “unusable.”

This change was particularly problematic for our Unifi Protect Time Lapse tool, which relied on these direct snapshot requests to build high-quality time-lapse videos. The reduced image quality meant that time-lapse videos lost much of their detail and clarity, defeating the tool’s purpose.

Our FFMPEG Solution

To address this issue, we completely rebuilt our snapshot capture system to use FFMPEG to extract frames directly from the RTSP streams provided by Unifi Protect cameras. This approach bypasses the degraded /snap.jpeg endpoint entirely and allows us to capture full-resolution images with proper quality settings.

However, implementing this solution revealed two additional challenges:

Challenge 1: Motion Blur in Frame Captures

Unlike direct snapshots, extracting frames from video streams can result in motion blur, especially for cameras mounted on poles or flexible surfaces that move in the wind. This happens because video streams use compression techniques that are not optimized for single-frame extraction.

To solve this, we implemented specialized frame selection techniques:

  • I-frame Selection: Our system can be configured to wait for and capture only I-frames (keyframes), which contain complete image data and generally show less compression artifacts.
  • Frame Blending: For cameras with severe motion issues, we implemented an option to blend multiple consecutive frames, which can reduce visible motion blur.

Challenge 2: Unifi’s “Enhanced” Encoding

During our development, we discovered that Unifi Protect’s newer “Enhanced” encoding option (described as “improves video quality while reducing storage size”) created additional challenges for frame extraction.

This encoding mode uses more aggressive compression with fewer complete frames in the stream. When capturing single frames from streams using this encoding, users might occasionally get completely corrupted or unusable images – not just blurry ones, but actual broken files.

To counter this, our system includes specific handling for streams with Enhanced encoding, allowing it to examine more frames before selecting one to save. This significantly reduces the chances of capturing a corrupted frame.

The Results

After implementing these changes, our Unifi Protect Time Lapse tool now produces higher quality images than were previously available even before the /snap.jpeg quality reduction. Users have reported sharper, clearer time-lapse videos with better color reproduction and detail retention.

For those experiencing issues with motion blur or occasional corrupted images, our configurable capture techniques provide options to fine-tune the system for your specific environment and camera placement.

Getting Started

Deploying Unifi Protect Time Lapse is simple with Docker. Just create a basic compose file:

services:
  unifi_protect_time_lapse:
    container_name: unifi_protect_time_lapse
    image: lux4rd0/unifi_protect_time_lapse:latest
    restart: always
    volumes:
      - ./output:/app/unifi_protect_time_lapse/output:rw
    environment:
      UNIFI_PROTECT_TIME_LAPSE_PROTECT_HOST: your-protect-host.example.com
      UNIFI_PROTECT_TIME_LAPSE_CAMERAS_CONFIG: '[{"name":"cam-frontdoor","stream_id":"YOUR_STREAM_ID","intervals":[15,60]}]'
      UNIFI_PROTECT_TIME_LAPSE_CAPTURE_TECHNIQUE: 'iframe'

For complete documentation including all configuration options, visit our GitHub repository.

By adapting to Ubiquiti’s changes rather than fighting against them, we’ve created a solution that works around the quality reduction and improves on the original implementation, providing you with beautiful time-lapse videos from your Unifi Protect system.