Important

This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.

czcamera

czcamera is a camera application for the M5Stack CardputerZero that replaces the stock Camera app. It adds true cropped zoom, a separate focus loupe, nine live photo filters, video recording with microphone audio, foreground timelapse capture, and an on-device gallery with video playback.

What it adds over the stock camera

Feature Stock Camera czcamera
Photos Unfiltered stills only 8MP / 2MP stills, EV (-2.0 to +2.0), 3s/10s self-timer, grid overlay
Zoom and framing Preview magnification only (saved photos stay uncropped) Cropped zoom (1.0x to 4.0x) in Photo, Video, and Timelapse, plus a 2x viewfinder-only Loupe (Z)
Filters None 9 live-previewed filters baked into JPEGs (None, B&W, Hi-Con, Sepia, Cool, Vivid, Invert, Retro, GameBoy)
Video None 480p, 720p, or 1080p .mp4 at 30fps with mic audio (M mute toggle, muted fallback), live viewfinder, and live zoom/loupe
Timelapse None Custom intervals (1-3600s), 1-30 FPS, manual/shot/duration stop limits, raw JPEG folder or compiled .mp4, auto-dim with safe wake, crash recovery
Gallery and playback Basic still viewing Full-screen browser for photos, timelapse folders, and on-device .mp4 playback with speaker audio, -5s/+5s seek, and [Y/N] delete confirmation
Interface and storage Fixed layout and defaults Dark/Light themes, left/right control rail swap, camera orientation options, configurable output directory (~/Pictures/czcamera default), and hidden staging files for external sync tools

Features and usage

The interface splits the screen between a live viewfinder and a control rail with tabs for Photo (1), Video (2), and Timelapse (3). Navigate rail cards and menus with the arrow keys or h/j/k/l, swap the rail between the left and right edges with W, switch between Dark and Light themes with T, and toggle the rule-of-thirds grid with G.

Photo (1)

Photo mode saves 8MP (default) or 2MP (R) JPEGs with EV adjustment (-2.0 to +2.0), an Off/3s/10s self-timer (C), 1.0x to 4.0x cropped zoom (5/7), and a 2x viewfinder-only Loupe (Z) to check focus without cropping the final image. Pressing F cycles all nine filters on the live preview; None saves the sensor JPEG directly without re-encoding.

Video (2)

In Video (2), pressing Enter, Space, or 6 records 720p30 (default), 1080p30, or 480p30 .mp4 clips (R cycles resolution while idle). The microphone is on by default (M toggles mute while idle), and if audio capture is unavailable the app falls back to recording a silent .mp4. Zoom (5/7) and Loupe (Z) stay active during recording, which stops automatically if free space drops below 100 MB.

Timelapse (3)

Timelapse shoots 2MP (default), 1080p, or 8MP (R) sequences using preset or custom intervals (1-3600s via C or P), 1-30 playback FPS, and manual, shot-count, or duration stop limits. Sessions save as a TL_<timestamp>/ JPEG folder or compile into TL_<timestamp>.mp4. During a run, the screen dims automatically, any keypress wakes the display first without cancelling capture, and unfinished sessions trigger a recovery prompt on the next launch.

Press 8 to pause the camera and open the full-screen gallery, sorted newest first. From there you can open TL_* folders, play .mp4 files with speaker audio, seek -5s or +5s, and delete items after a [Y/N] confirmation. Settings (S) covers the output directory (folder tree picker or manual path entry via T), rail side, theme, grid overlay, timelapse auto-dim timeout, and camera orientation (auto, 0, 180, hflip, vflip).

Installation

Build the ARM64 .deb package on macOS or Linux with Docker (linux/arm64 enabled), or pass --local to build directly on the CardputerZero:

./packaging/build-deb.sh
scp packaging/dist/czcamera_1.0.0_m5stack1_arm64.deb pi@<cardputerzero-host>:/tmp/

Install the package on the device:

sudo dpkg -i /tmp/czcamera_1.0.0_m5stack1_arm64.deb
sudo apt-get install -f

Launch czcamera from APPLaunch or run /usr/bin/czcamera. Remove it with sudo apt-get remove czcamera.

For the desktop SDL2 simulator, native device builds, and unit tests, see Building, installation, and desktop simulator.

Keyboard shortcuts

Key Context Action
1, 2, 3 Main view / Gallery Switch to Photo, Video, or Timelapse
Enter, Space, 6 Main view Take photo, start/stop video, or start timelapse / open stop prompt
Up/Down or k/j Rail / Lists / Modals Move cursor up or down
Left/Right or h/l Rail / Settings / Video playback Cycle selected setting, or seek -5s/+5s during video playback
5 / 7 Photo / Video / Timelapse Step cropped digital zoom (1.0x to 4.0x, works during video and timelapse)
Z Photo / Video / Timelapse Toggle 2x viewfinder-only Loupe (idle or active capture)
F Photo Cycle 9 photo filters (None through GameBoy)
R Main view / Offline Cycle resolution preset, or retry camera startup when Offline
C (or P in TL) Photo / Timelapse Cycle self-timer (Off/3s/10s) in Photo; open custom setup in Timelapse
M Video (idle) / Gallery video Toggle microphone recording / Toggle playback mute
G Main view Toggle rule-of-thirds grid
W Main view Flip control rail between right and left
T Main view / Gallery / DirPicker Toggle Dark / Light theme (or enter path manually in DirPicker)
8 Main view Pause camera and open Gallery
S Main view Open Settings
D / Delete Gallery Prompt [Y/N] to delete selected item
Esc / Q Dimmed TL / Modals / Main Wake dimmed screen safely (first press), close/cancel modal, or exit

Troubleshooting

Symptom Check or fix
Camera Offline [R] on launch Press R to retry startup. If it stays offline, check grep imx219 /boot/firmware/config.txt and rpicam-hello --list-cameras.
Video records without audio (audio_unavailable) When audio capture fails, czcamera records a silent .mp4 instead of dropping the clip. Check ALSA inputs with arecord -l and alsamixer.
Upside-down or mirrored preview Open Settings (S) and cycle Camera Orient (auto, 0, 180, hflip, vflip).
Recovery prompt appears on startup An earlier timelapse ended before finishing. Press C to compile frames to .mp4, K to keep the raw JPEGs, D to discard them, or Esc to defer.
Capture refuses to start or stops early czcamera checks for at least 100 MB free on the target mount before starting and during video or timelapse runs.

Documentation

License

Licensed under the Apache License, Version 2.0. See LICENSE.md for the full text.

Description
No description provided
Readme 224 KiB
Languages
C++ 81%
Python 17.2%
Shell 0.9%
CMake 0.9%