Skip to content

cowton0627/CameraHuman

BranchesTags

Repository files navigation

CameraHuman

影人（CameraHuman）是一個以 UIKit + AVFoundation 為主的 iOS 拍攝工具原型。主軸不是單純相機 demo，而是把拍攝、音訊監看、素材管理、拍攝規劃整成同一個工作流。

Bundle / scheme / target / repo 名稱維持 CameraHuman；「影人」是 iOS home screen 圖示下方的顯示名稱（CFBundleDisplayName）。

Current App Structure

底部自製 dock（不是 UITabBar 預設樣式）分成四頁：

  • Camera 拍攝頁。整合相機預覽、錄影、鏡頭切換、音訊電平監看、格式資訊與技術 HUD。
  • Media 已錄製素材列表，支援播放、滑動刪除、素材註記，以及把某支素材 link 到 planner。
  • Assistant 拍攝助理頁。清楚標示為本地 rule-based engine，整合 shot checklist、備忘與 action items；ChatEngine 可替換成真正 AI provider。
  • Settings 拍攝偏好：錄影畫質、比例、啟動鏡頭、格線。

Implemented Features

Camera

  • 服務層拆分：
    • CameraSession 管 AVCaptureSession、鏡頭枚舉、前後鏡頭切換、權限請求
    • CameraRecorder 管錄影狀態機（idle / starting / recording / stopping）+ AVCaptureFileOutputRecordingDelegate + 計時器
    • AudioLevelMonitor 從 PCM sample buffer 計算 RMS / dB
  • 後鏡頭依硬體實際支援列出 0.5x / 1x / 3x，不做假鏡頭
  • 前鏡頭只暴露單一 front mode，不硬做多焦段假象
  • 上方拍攝 HUD
    • 第一排：FORMAT / FRAME / TIME（錄影中變 REC）
    • 第二排：LENS / FPS / SHUTTER / IRIS / ISO / WB
  • 手動控制（點 HUD chip 調整，需真機）
    • FPS 點擊循環 24→30→60
    • ISO / SHUTTER 開曝光面板：AUTO（EV 補償滑桿）/ MANUAL（ISO + 快門滑桿）
    • WB 開白平衡面板：AUTO / 色溫滑桿
    • service API 在 CameraSession，純換算在 CameraManualControls，面板 UI 為 ManualControlSheetView
  • 錄影鍵 + 狀態機，過渡期間自動禁用避免重複點擊
  • 即時音量監看（綠 / 黃 / 紅三段顏色 + dB 數值）
  • i 診斷資訊（5 行精簡狀態 + 可複製）
  • 16:9 / 4:3 構圖框與遮罩
  • 錄影完成 toast
  • 最近一次錄影刪除捷徑

Media

  • 錄影檔儲存到 Documents/Recordings
  • 列表顯示縮圖 + 檔名 + 建立時間 + 片長 + 檔案大小 + 註記（縮圖與片長由 MediaThumbnailProvider 背景產生並 cache）
  • 點開可播放 .mov
  • 滑動 row 露出 Delete / Note / Link
  • 長按 row 開 context menu：Note / Link / Share / Save to Photos / Delete
  • 分享（UIActivityViewController）與匯出到照片 App（PHPhotoLibrary）
  • 4:3 模式錄影在儲存時做輸出裁切（MediaLibrary 內）

Assistant

  • 三顆 quick action button：目前設定 / 最近素材 / 下一步建議
  • Planner 卡片：shot checklist（44pt 觸控區）/ 備忘 / 儲存 / linked clip / action items
  • 對話引擎走 ChatEngine 協定，目前 UI 明確標示為本地 rule-based engine；未來換 AI 只要替換實作
  • 鍵盤避讓：點空白 / 拖列表 / Return key 都會收下鍵盤

Settings

  • HD / FHD
  • 16:9 / 4:3
  • 預設前鏡頭 / 後鏡頭
  • 顯示格線
  • 是否錄音 / 是否顯示 Audio Meter
  • Technical HUD / Camera 頁保持螢幕常亮
  • 顯示目前音訊 route 與 channel 數
  • 3 分鐘展示流程、工程亮點與 build 資訊

Tech Stack

純 UIKit + AVFoundation，沒用 SwiftUI / Combine / async-await。

  • UIKit — 所有 UI
  • AVFoundation — capture session、錄影、音訊
  • AVKit — 素材播放（AVPlayerViewController）
  • Foundation — UserDefaults、NotificationCenter、FileManager
  • CoreGraphics — App icon 生成 script

Persistence 走 UserDefaults + Documents/Recordings/ + JSON metadata，不用 CoreData。 最低部署 iOS 13.0。

Architecture at a Glance

  • Service layer：CameraSession / CameraRecorder / AudioLevelMonitor 包住所有 AVCapture* 物件，VC 不直接接觸 AVFoundation
  • Closure-based callback：service 不暴露 protocol delegate，用 onConfigured / onStateChange 等 closure 通知 VC
  • Singleton + NotificationCenter pub/sub：CameraSettingsStore / MediaLibrary / ShotPlannerStore 三個全域 store
  • Strategy（ChatEngine 協定）：KeywordChatEngine 為預設實作，未來換 AI 不改 VC
  • State machine：CameraRecorder.State（idle → starting → recording → stopping → idle）
  • Custom view encapsulation：AspectMaskView / AudioMeterCardView / ToastView / PlannerCardView

每個選擇的「為什麼」見 DECISIONS.md。

Project Structure

project.pbxproj 採用 Xcode 16 同步資料夾（PBXFileSystemSynchronizedRootGroup），加新檔到對應資料夾就會自動納入 build，不必手動編輯 pbxproj。

CameraHuman/
├── App/                                   入口
│   ├── AppDelegate.swift
│   ├── SceneDelegate.swift
│   └── RootTabBarController.swift         自製 dock + 自動切換 portrait/landscape
├── Camera/
│   ├── CameraViewController.swift         view 組裝 + service callback wiring
│   ├── CameraSession.swift                AVCaptureSession + 鏡頭管理
│   ├── CameraRecorder.swift               錄影狀態機 + delegate
│   ├── AudioLevelMonitor.swift            音量輪詢
│   ├── CameraDiagnostics.swift            i 診斷報告
│   ├── CameraManualControls.swift         手動控制純換算（FPS/clamp/滑桿映射）可測
│   ├── HUDFormatters.swift                AVCaptureDevice → 顯示文字
│   ├── AVCaptureVideoOrientation+Init.swift
│   └── Views/
│       ├── AspectMaskView.swift           預覽外殼 + 構圖框 + 三分線
│       ├── AudioMeterCardView.swift       音量計卡片
│       ├── ManualControlSheetView.swift   底部手動控制面板（滑桿 + AUTO/MANUAL）
│       └── ToastView.swift                提示泡泡
├── Chat/
│   ├── ChatViewController.swift           UI 組裝 + 訊息列表
│   ├── ChatEngine.swift                   協定 + `KeywordChatEngine`
│   └── Views/PlannerCardView.swift        checklist / notes / action items 卡片
├── Media/
│   ├── MediaViewController.swift
│   ├── MediaLibrary.swift                 儲存 + metadata + 4:3 裁切
│   └── MediaThumbnailProvider.swift       縮圖 + 片長（背景產生 + NSCache）
├── Settings/
│   ├── SettingsViewController.swift
│   └── CameraSettingsStore.swift          UserDefaults persist + 變更通知
├── Planner/
│   └── ShotPlannerStore.swift             checklist / notes / action items / linked clip
├── Shared/
│   └── KeyboardObserver.swift             鍵盤升降監聽，可重用
└── Resources/                             Assets.xcassets / Info.plist / Base.lproj / .xcdatamodeld
scripts/
└── generate_app_icon.swift                用 CoreGraphics 產 1024×1024 AppIcon

Documentation

每份檔案各自只做一件事，避免內容散落：

檔案 用途
README.md 你正在看的這份。產品 / 架構速覽
roadmap.md Done + 還沒做的事（Short / Mid / Long Term + Technical Debt）
DECISIONS.md 架構決策的「為什麼」與放棄了什麼
bugs.md 踩過的坑（症狀 / 根因 / 解法）
runbook.md Build、模擬器、icon 生成、清快取等實際指令
docs/camera-architecture.md 相機頁 service 層、capture session、HUD 與資料流設計
docs/development-workflow.md 開發流程、build 驗證、真機測試、git 流程

Build

模擬器：

xcodebuild -project CameraHuman.xcodeproj -scheme CameraHuman \
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
  -configuration Debug build

最低支援 iOS 13.0。Info.plist 內含 NSCameraUsageDescription / NSMicrophoneUsageDescription / UILaunchStoryboardName，啟動畫面已修，App 不再被 letterbox 在螢幕中央。

Interview Demo (3 minutes)

  1. Camera：指出鏡頭清單與手動控制都來自實機 capability；切換 FORMAT / FRAME，確認 MIC meter 後錄一段。
  2. Media：播放剛錄的素材，加 Note，並 Link 到 Planner。
  3. Assistant：點「目前設定」「最近素材」「下一步建議」，展示跨 store context 與 action item 寫回；同時說明目前是本地 rule-based engine，不假裝已接 LLM。
  4. Settings：展示可持久化偏好、真實 audio route/channel，以及 app 內的 Engineering Highlights。

展示前先確認：Camera / Microphone 權限、至少 200 MB 可用空間、直向與橫向各開一次、錄製檔確實有畫面與聲音。

Current Limitations

  • 4:3 目前是錄後裁切，仍需真機驗證不同方向與不同鏡頭的結果一致。
  • 音訊監看會讀取真實 PCM level，但仍不是多軌 mixer；內建輸入可能只提供單一 capture channel。
  • Assistant 還是本地 rule-based engine；架構已用 ChatEngine 協定預留 swap 點，但未接外部 AI。
  • Media 是單層素材列表，沒有專案、資料夾或標籤系統。

About

iOS video shooting companion — lens HUD, media library with notes, shot checklist, and an assistant chat.

Topics

avfoundationcameraiosswiftuikitvideography

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages