Andrew Beresford

User Guide

Getting Started

Requirements

  • macOS 14.0 (Sonoma) or later
  • UniFi Protect controller (Cloud Key Gen2+, Dream Machine, or dedicated NVR)
  • Network access to your UniFi Protect controller
  • RTSP streaming enabled on your cameras

First Launch

When you first launch Chuiko, you'll need to configure your UniFi Protect connection:

  1. Click the camera icon in the menu bar
  2. Click the gear icon to open Settings
  3. Enter your connection details:
    • Server: Your UniFi Protect controller's IP address or hostname
    • Username: Your UniFi account username
    • Password: Your UniFi account password
  4. Click Save & Connect

Enabling RTSP on Cameras

For video streaming to work, RTSP must be enabled on your cameras:

  1. Open the UniFi Protect web interface
  2. Go to Devices and select a camera
  3. Under Settings, find RTSP
  4. Enable RTSP for at least one quality level (High, Medium, or Low)
  5. Repeat for each camera you want to stream

Menu Bar Interface

Connection Status

The top of the menu shows your connection status:

  • Connected (green) — successfully connected to UniFi Protect
  • Connecting... (yellow) — attempting to connect
  • Reconnecting... (yellow) — connection lost, attempting to reconnect
  • Disconnected (red) — not connected

Camera List

Each camera is shown with:

  • Status indicator — green dot (online), orange pulsing dot (motion detected), or grey dot (offline)
  • Camera name
  • Status text — "Online", "Offline", or "Motion detected"
  • Play button — click to open a video popup
  • Toggle switch — enable or disable motion monitoring for this camera

Footer Buttons

At the bottom of the menu:

  • Active events counter — shows number of cameras with active motion
  • Settings — open settings window
  • Refresh — manually refresh camera list
  • Quit — close Chuiko

Video Popups

Opening Video

Click the play button next to any camera to open a live video popup. You can have up to four video popups open simultaneously.

Popup Features

  • Drag anywhere on the video to move the window
  • Resize by dragging the corner (maintains 16:9 aspect ratio)
  • Close by clicking the X button (more visible on hover)
  • Camera name and motion status shown in top-left corner

Right-Click Menu

Right-click on any video popup to access:

  • Copy Snapshot — copy the current frame to your clipboard
  • Save Snapshot... — save the current frame as a JPEG file

Popup Positioning

Popups automatically stack based on your configured position (Settings → Popup Position):

  • Top Right
  • Top Left
  • Bottom Right
  • Bottom Left

When a popup closes, remaining popups animate to fill the gap.

Motion Detection

How It Works

Chuiko receives real-time motion events from your UniFi Protect controller via WebSocket. When motion is detected:

  1. The camera's status indicator turns orange and pulses
  2. If Auto-show popup is enabled, a video popup opens automatically
  3. A macOS notification is sent (if enabled)

Auto-Dismiss

Motion-triggered popups automatically close 10 seconds after motion ends. Popups you opened manually (via the play button) stay open until you close them.

Per-Camera Monitoring

Use the toggle switch next to each camera to enable or disable motion monitoring. Disabled cameras won't trigger popups or notifications.

Settings

Access settings by clicking the gear icon in the menu.

Connection

  • Server — UniFi Protect controller address (IP or hostname)
  • Username — your UniFi account username
  • Password — your UniFi account password

Popup Settings

  • Auto-show popup on motion — automatically open video when motion is detected
  • Popup position — screen corner for popup windows
  • Stream quality — video quality (High, Medium, Low). Higher quality uses more bandwidth and CPU; lower quality is more responsive on slower networks

Notifications

  • Show notifications — enable or disable macOS notifications for motion events

Keyboard Shortcuts

Action Shortcut
Open menu Click menu bar icon
Close popup Click X or press Escape (when focused)

Troubleshooting

"Connection Failed" Error

  • Verify your server address is correct
  • Ensure your Mac can reach the UniFi Protect controller (try pinging it)
  • Check that your username and password are correct
  • Make sure you're using a local UniFi account, not a UI.com cloud account

Video Not Loading

  • Verify RTSP is enabled on the camera in UniFi Protect settings
  • Check that the camera is online in the UniFi Protect app
  • Try a lower stream quality setting
  • Ensure your Mac has network access to the camera's RTSP port (7441)

"Camera Offline" Message

This appears when the camera is disconnected from UniFi Protect. Check:

  • Camera power connection
  • Network connection to the camera
  • Camera status in the UniFi Protect app

Cameras Not Appearing After Reconnection

If cameras don't appear after a network disruption:

  1. Click the Refresh button in the menu footer
  2. If that doesn't work, try disconnecting and reconnecting in Settings

Video Stuttering or Freezing

  • Try a lower stream quality setting
  • Check your network connection
  • Ensure your Mac isn't under heavy CPU load
  • The stream will automatically reconnect if it stalls for more than 5 seconds

Menu Bar Icon Missing

  • Check System Settings → Control Centre → Menu Bar Only
  • Ensure Chuiko is running (check Activity Monitor)
  • Try quitting and relaunching Chuiko

Privacy & Security

  • Credentials are stored securely in the macOS Keychain
  • All connections to UniFi Protect use HTTPS/TLS
  • Video streams use encrypted RTSPS (RTSP over TLS)
  • Chuiko runs entirely locally — no data is sent to external servers