11 KiB
Important
This project was developed with AI coding assistance and has not yet undergone a full hardware soak test on physical CM0 hardware. It is provided under the Apache 2.0 license and may require adjustment for other environments.
Usage, Controls & Configuration Guide
czcamera is operated entirely with the 46-key CardputerZero keyboard (cp0-keys) or an attached keyboard in the SDL2 desktop simulator.
1. Screen Layout (Option A Split View)
The 320×170 canvas splits into two regions whose horizontal side swaps dynamically with W (or via Settings → Control Rail):
- Viewfinder (
226×170):16:9modes (720p,1080pVideo,1080pTimelapse) letterbox cleanly into226×127centered on a#050507surround;4:3modes (8MP,2MP,480p) fill226×170. Minimal corner badges show active filter, crop zoom /2xLoupe state, timer countdown,● REC MM:SS, or Timelapse shot counter/next-shot countdown. - Control Rail (
94×170): Displays1P · 2V · 3Tmode tabs at the top, 4 setting cards tailored to the active mode, and a compact 2-line<kbd>keybind hint footer.
2. Capture Modes
Photo Mode (1)
- Resolutions (
Ror card 0):8MP(3280×2464JPEG) default,2MP(1640×1232JPEG). - Digital Crop Zoom vs. Viewfinder Loupe:
5/7: Steps ISPScalerCrop(1.0x,1.5x,2.0x,3.0x,4.0x). Both the live preview and captured JPEG are cropped cleanly to that region.L(orlon Photo idle view): Toggles a2xViewfinder-Only Loupe for checking framing/focus without cropping the saved full-resolution photo.
- Exposure Value (card 1,
Left/Right):-2.0to+2.0in0.5EV steps. - Photo Filters (
For card 2): Cycles all 9 filters live on the preview and applies them on JPEG save (Nonewrites the sensor JPEG directly with zero re-encode):None(none),B&W(bw),Hi-Con(hicon),Sepia(sepia),Cool(cool),Vivid(vivid),Invert(invert),Retro(retro),GameBoy(gameboy, scaled integer blocks with 4-shade Bayer DMG palette). - Self-Timer (
Cor card 3): CyclesOff(0s),3s,10s. PressEscduring countdown to cancel without quitting. - Shutter (
Enter,Space,6): Stages to.IMG_<ts>.jpg.tmp, applies filter if active,fsyncs, and commits atomically toIMG_<ts>.jpg(adding_01,_02, ... on same-second collisions).
Video Mode (2)
- Resolutions (
Ror card 0, while idle):720p(1280×720@ 30fps, default),1080p(1920×1080@ 30fps),480p(640×480@ 30fps). - Audio (
Mor card 1, while idle): ES8389 MEMS microphone ON by default (audio=true). If ALSA capture is unavailable or busy at recording start,czcamera-camemitsaudio_unavailable, shows a warning toast, and falls back to muted.mp4recording instead of aborting. - Live Zoom (
5/7or card 2): Active both before and during recording (1.0x–4.0x). - Storage Indicator (card 3): Displays read-only
FREEspace remaining on the target mount (100 MBminimum enforced every 2 seconds while recording; auto-stops safely if space drops below100 MB). - Recording Lock: While
● RECis active, mode switches (1/2/3),[8]Gallery,[S]Settings,[W]rail flip,[T]theme toggle,[M]/[R], andQare locked out. PressEnter,Space,6, orEscto stop recording cleanly.
Timelapse Mode (3)
- Defaults & Presets:
- Resolution (
Ror card 2):2MP(1640×1232default for tighter intervals),1080p(1920×1080),8MP(3280×2464). - Interval (card 0): Cycles
2s,5s(default),10s,30s,60s,300s(or any custom1..3600svia[C]/[P]). - Output Mode (card 1):
video(TL_<ts>.mp4, default) orphotos(TL_<ts>/frame_0001.jpg...). - Stop Condition (card 3):
Manual(default),60 shots,120 shots,300 shots,15 min,30 min,60 min(or custom via[C]/[P]).
- Resolution (
- Custom Input Modal (
CorPwhile idle): Adjusts exact Interval (1..3600s), FPS (15,24,30), Stop Mode (manual/shots/duration), and Stop Value (1..9999shots or1..1440min) with numeric digits orLeft/Right.Entersaves and closes;Escdiscards. - MP4 Compilation & VideoCore IV Compliance:
- Frames stage inside
.tl_work_<ts>/with amanifest.jsonheartbeat. - On stop/completion in
videomode,ffmpegprefers hardwareh264_v4l2m2m(6M,yuv420p) and automatically falls back tolibx264 -preset veryfast -crf 22 -pix_fmt yuv420pif hardware encoding fails. - Because Raspberry Pi VideoCore IV's hardware H.264 encoder caps dimensions at
2048px,8MP(3280×2464) frames automatically scale to1440×1080(lanczos) during MP4 compile (while individualPhotos-mode frames remain full8MP). - Press
EscduringTimelapseCompilingto cancel compilation cleanly and preserve the raw frames in a non-hiddenTL_<ts>/folder.
- Frames stage inside
- Auto-Dim & Safe Wake:
- When capturing, the screen dims after
timelapse_dim_secidle seconds (15sdefault; configurable15s/30s/60s/Offin Settings) via/sys/class/backlight/*/brightness(or a software black frame fallback on desktop/headless). - Safe-Wake Rule: Pressing any key while dimmed (including
Enter,6,Esc,Q) only wakes the display and resets the idle timer — and on Linuxevdev, held auto-repeats (ev.value == 2) for that wake key are suppressed until key release (ev.value == 0). PressEsc,Enter,6, orQwhile awake to openTimelapseStopConfirm([Y]stop & finish/compile,[N]/[Esc]keep capturing).
- When capturing, the screen dims after
- Crash Recovery on Launch: On startup,
czcamerascansoutput_dirfor incomplete.tl_work_*directories containing valid JPEGs and promptsTimelapseRecovery:[C]Compile to MP4,[K]Keep Photos,[D]Discard, or[Esc]Defer.
3. Gallery & Media Playback (8)
Pressing 8 pauses the camera backend (pause IPC, releasing the sensor) and opens the full-screen 320×170 Gallery showing items from output_dir (newest first, ignoring all .-prefixed hidden files/directories):
| Key | Gallery Context | Action |
|---|---|---|
Up/Down/Left/Right or k/j/h/l |
Photo / Video (stopped) / TL Folder | Navigate items |
Space / Enter |
TL_* Timelapse Folder |
Drill into folder (Backspace or Esc returns to root) |
Space / Enter |
Video (.mp4) |
Play / Pause |
Left / Right or h / l |
Video (playing) | Seek -5s / +5s |
M |
Video selected | Toggle playback mute (works cleanly even on silent .mp4 files with no audio stream) |
D / Delete |
Any item | Open [Y] Confirm / [N]/Esc Cancel delete prompt |
T |
Gallery | Toggle Zinc Dark / Light theme |
1, 2, 3 |
Gallery | Close Gallery, resume camera, and jump directly to mode |
Esc / Q |
Gallery root | Close Gallery and resume camera live preview |
4. Settings Modal & Directory Tree Picker (S)
| Row | Setting | Values / Action |
|---|---|---|
| 0 | Output Dir |
Opens DirPicker (Enter drill down, Backspace parent, Space select highlighted dir, . select current dir, / root, ~ home, [T] manual TextInput with printable ASCII + spaces, Esc back) |
| 1 | Control Rail |
right (default) / left |
| 2 | Theme |
dark (Zinc Dark) / light (Zinc Light) |
| 3 | Grid Overlay |
on (true) / off (false) |
| 4 | Timelapse Dim |
15s / 30s / 60s / Off (0) |
| 5 | Camera Orient |
auto / 0 / 180 / hflip / vflip (live backend reconfigure) |
5. Configuration Reference (config.json)
Persisted atomically to ~/.config/czcamera/config.json (override path with CZCAMERA_CONFIG). Malformed or missing configs fall back safely to defaults; out-of-range fields are sanitized on load.
| Field | Default | Valid Values / Range |
|---|---|---|
output_dir |
"~/Pictures/czcamera" |
Target media folder (~/ expanded via $HOME) |
theme |
"dark" |
"dark", "light" |
rail_side |
"right" |
"right", "left" |
photo_resolution |
"8mp" |
"8mp" (3280×2464), "2mp" (1640×1232) |
photo_filter |
"none" |
"none", "bw", "hicon", "sepia", "cool", "vivid", "invert", "retro", "gameboy" |
photo_timer_sec |
0 |
0, 3, 10 |
grid_enabled |
true |
true, false |
video_resolution |
"720p" |
"480p", "720p", "1080p" |
video_audio |
true |
true, false |
timelapse_resolution |
"2mp" |
"2mp", "1080p", "8mp" |
timelapse_interval_sec |
5 |
1..3600 (seconds) |
timelapse_output_mode |
"video" |
"video", "photos" |
timelapse_fps |
24 |
15, 24, 30 |
timelapse_stop_mode |
"manual" |
"manual", "shots", "duration" |
timelapse_stop_value |
0 |
>= 0 (shot count or seconds when "duration") |
timelapse_dim_sec |
15 |
0..3600 (0 = never auto-dim) |
ev |
0.0 |
-2.0..2.0 |
camera_transform |
"auto" |
"auto", "0", "180", "hflip", "vflip" |
6. CLI Options & Environment Variables
czcamera [options]
--sim Run desktop 320x170 SDL2 simulator (uses mock camera)
--scale <1..4> Integer SDL2 window scale factor (default: 2)
--mock-cam Force procedural SimCameraBackend (desktop or device)
--output-dir <path> Override media output directory for this session (non-destructive to config.json)
--render-test <path.ppm> Render 320x170 P6 PPM snapshot headlessly and exit
--theme <dark|light> Initial theme override
--mode <photo|video|timelapse|gallery|settings>
Initial mode or modal
--rail <right|left> Control rail side override
--help Print usage help
Environment variables:
CZCAMERA_CONFIG: Override path toconfig.json.CZCAMERA_CAM_BIN: Override path toczcamera-camexecutable (default/usr/bin/czcamera-cam, with./cam-helper/bin/czcamera-camdevelopment fallback).
7. Sync-Safe Storage & Disk Floor
- All in-progress files inside
output_diruse leading dots so filesystem watchers/sync tools ignore partial writes:- Photos:
.IMG_<ts>.jpg.tmp→ atomicrename()→IMG_<ts>.jpg - Videos:
.VID_<ts>.mp4.part→ atomicrename()→VID_<ts>.mp4 - Timelapses:
.tl_work_<ts>/frame_0001.jpg+manifest.json,.TL_<ts>.mp4.part→TL_<ts>.mp4orTL_<ts>/
- Photos:
- Minimum free storage floor:
100 MB(104857600bytes) checked viastatvfs()before any capture, every 2s during Video recording, and before each Timelapse shot.
8. Troubleshooting
- "Camera Offline [R]" shown on device:
- Check
grep imx219 /boot/firmware/config.txt(dtoverlay=imx219) andrpicam-hello --list-cameras. - Verify
/usr/bin/czcamera-cam --mock-driver --frame-fd 3manually, or pressRinsideczcamerato respawn the backend.
- Check
- Video records muted (
audio_unavailabletoast): Check ALSA capture device visibility (arecord -landalsamixer);czcameraautomatically records muted video rather than dropping the shot. - Upside-down or mirrored preview on custom lens mount: Open Settings (
S) →Camera Orientand cycleauto,0,180,hflip, orvflip.