🌱 Lawn Lapse

Automated time-lapse generator for UniFi Protect cameras

Captures daily snapshots at your chosen time and creates beautiful time-lapse videos showing changes over days, months, or years.

🎬 Demo

Watch your lawn, garden, construction project, or any outdoor space transform over time with automatically generated time-lapse videos.

▶️ Watch the demo on YouTube - 109 days of lawn evolution captured with 24fps motion interpolation

✨ Features

• 📸 Smart Setup - Auto-detects configuration and guides through setup on first run
• 🎥 Multi-Camera Support - Track multiple cameras with isolated snapshots and timelapses
• 🎬 Motion Interpolation - Cinematic 24fps with smooth frame blending for professional results
• 🔄 Smart Historical Backfill - Automatically fetches historical footage until recordings run out
• 💾 Permanent Archive - Stores snapshots locally forever (beyond NVR retention limits)
• 🔐 Simple Authentication - Uses username/password for easy setup
• ⏰ Advanced Scheduling - Fixed times, intervals, or sunrise/sunset based captures
• 📊 Progress Tracking - Shows detailed progress during snapshot fetching
• 🎯 Smart Defaults - Optimized settings out of the box (24fps with interpolation, best quality)

📋 Prerequisites

• Node.js 18+ (required for modern JavaScript features)
• ffmpeg installed (brew install ffmpeg on macOS, apt install ffmpeg on Linux)
• UniFi Protect system with at least one camera
• Admin access to UniFi Protect

🚀 Quick Start

No installation needed! Just run:

npx lawn-lapse

That's it! The first time you run it, you'll be guided through an interactive setup that will:

1. Connect to your UniFi Protect system
2. Select your camera(s)
3. Fetch historical snapshots (as far back as your NVR has them!)
4. Generate your first time-lapse video

Want to install it? You can optionally install globally:

npm install -g lawn-lapse
lawn  # Now you can just type "lawn"!

For developers: Clone the repo and run npm install && npm start

🎯 Usage

Main Command

lawn [command]

When run without arguments:

• First run: Automatically starts interactive setup
• Subsequent runs: Captures snapshots and updates time-lapse

Commands

| Command | Description | | -------------- | ----------------------------------------- | | lawn | Run capture (auto-setup if first time) | | lawn status | Show configuration and statistics | | lawn cron | Set up or update automated daily captures | | lawn version | Show version number | | lawn help | Display help information |

Verbose Mode

Add -v or --verbose flag for detailed output:

lawn -v  # Shows ffmpeg output and detailed logging

🔧 Configuration

Interactive Setup

On first run, lawn will guide you through:

1. UniFi Protect Connection

   • Host/IP address (defaults to 192.168.1.1)
   • Username (defaults to admin)
   • Password

2. Camera Selection

   • Shows all available cameras with model info
   • Indicates offline cameras
   • Displays resolution capabilities
   • Multi-camera support: Select multiple cameras for parallel tracking
   • Each camera gets its own snapshot and timelapse directories

3. Snapshot Settings

   • Capture time (24-hour format, defaults to 12:00)
   • Output directories auto-generated per camera (e.g., ./snapshots/front-yard/)

4. Automation Setup

   • Optional cron job installation
   • Automatic daily captures at specified time for all cameras

Configuration File

Settings are stored in lawn.config.json:

{
  "version": 2,
  "unifi": {
    "host": "192.168.1.1",
    "username": "admin",
    "password": "your-password"
  },
  "schedule": {
    "timezone": "America/Los_Angeles",
    "mode": "fixed-time",
    "fixedTimes": ["12:00"]
  },
  "cameras": [
    {
      "id": "abc123",
      "name": "Front Yard",
      "snapshotDir": "./snapshots/front-yard",
      "timelapseDir": "./timelapses/front-yard",
      "video": { "fps": 24, "quality": 1, "interpolate": true }
    },
    {
      "id": "def456",
      "name": "Back Yard",
      "snapshotDir": "./snapshots/back-yard",
      "timelapseDir": "./timelapses/back-yard",
      "video": { "fps": 24, "quality": 1, "interpolate": true }
    }
  ]
}

⚠️ Security Note: Keep lawn.config.json secure and never commit it to version control

📸 How It Works

Snapshot Collection

1. Daily Capture: At your specified time, captures a frame from the camera
2. Historical Backfill: On first run, walks backward through available UniFi recordings until no footage remains
3. Smart Fetching: Only downloads missing snapshots, skips existing ones
4. Progress Display: Shows [n/total] progress for each snapshot

Time-lapse Generation

1. Auto-detection: Finds the highest resolution from your snapshots
2. Smart Scaling: Maintains aspect ratio while maximizing quality
3. Optimized Encoding: Uses H.264 with slow preset for best compression
4. Configurable FPS: Default 24fps with motion interpolation for cinematic smooth playback

File Organization

lawn-lapse/
├── snapshots/              # Per-camera snapshot directories
│   ├── front-yard/
│   │   ├── 2024-01-01_1200.jpg
│   │   ├── 2024-01-02_1200.jpg
│   │   └── ...
│   └── back-yard/
│       ├── 2024-01-01_1200.jpg
│       └── ...
├── timelapses/             # Per-camera timelapse directories
│   ├── front-yard/
│   │   └── timelapse_12h00_2024-01-01_to_2024-03-15.mp4
│   └── back-yard/
│       └── timelapse_12h00_2024-01-01_to_2024-03-15.mp4
├── lawn.config.json        # Project configuration
└── logs/lawn-lapse.log     # Cron job logs

🔍 Monitoring

Check Status

lawn status

Shows:

• Total snapshots collected
• Date range of footage
• Gap detection in sequence
• Time-lapse videos generated
• Cron job status
• Last capture time

Example Output

🎥 Lawn Lapse Status Report
============================================================

📷 Cameras (2 configured):
============================================================

📹 Front Yard (abc123)
------------------------------------------------------------
  Snapshots: ./snapshots/front-yard
  Timelapses: ./timelapses/front-yard

  📸 Snapshots: 45 at 12:00
     Range: 2024-01-01 to 2024-02-14
     ✓ No gaps

  🎬 Time-lapses: 1 video(s)
     Latest: timelapse_12h00_2024-01-01_to_2024-02-14.mp4 (8.3MB)
     Covers: 45 days (2024-01-01 to 2024-02-14)

📹 Back Yard (def456)
------------------------------------------------------------
  Snapshots: ./snapshots/back-yard
  Timelapses: ./timelapses/back-yard

  📸 Snapshots: 42 at 12:00
     Range: 2024-01-04 to 2024-02-14
     ✓ No gaps

  🎬 Time-lapses: 1 video(s)
     Latest: timelapse_12h00_2024-01-04_to_2024-02-14.mp4 (7.1MB)
     Covers: 42 days (2024-01-04 to 2024-02-14)

⏰ Cron Job:
  ✓ Active: Daily at 12:00

🔐 Authentication:
  ✓ Credentials configured
  Username: admin

============================================================
📊 Summary:
  ✓ System operational: 2 camera(s), 87 total snapshot(s), 2 time-lapse(s)

🛠 Troubleshooting

Common Issues

| Problem | Solution | | ----------------------- | -------------------------------------------------------------------------------------------------------- | | "No cameras found" | Ensure UniFi Protect is accessible and user has admin privileges | | "Authentication failed" | Check username/password, ensure 2FA is disabled for API access | | Timeout errors | Reduce video duration or check network connectivity | | Missing snapshots | Verify camera was online and recording at capture time | | Cron not running | Check cron service is enabled: sudo launchctl load -w /System/Library/LaunchDaemons/com.vix.cron.plist |

Debug Mode

Run with verbose flag for detailed debugging:

lawn -v

Manual Capture

Force an immediate capture regardless of schedule:

npm exec lawn

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/dweekly/lawn-lapse.git
cd lawn-lapse

# Install dependencies
npm install

# Run in development
node lawn-lapse.js -v

# Format code
npm run format

# Lint code
npm run lint

📝 API Documentation

Main Functions

The project exports several key functions for programmatic use:

import { runSetup, runCapture } from "./lawn-lapse.js";

// Run interactive setup
await runSetup();

// Capture snapshots and generate time-lapse
await runCapture();

See API.md for detailed documentation.

🔒 Security

• Credentials are stored locally in lawn.config.json
• Never commit lawn.config.json to version control
• Uses UniFi Protect's official API library
• No external services or telemetry
• All data stays on your local machine

📜 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with unifi-protect library
• Inspired by traditional time-lapse photography techniques
• Thanks to the UniFi Protect community

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for the UniFi Protect community