How kashif-e/camerak works
1. Repository shape
This is a Kotlin Multiplatform/Compose Multiplatform monorepo centered on the cameraK library. The root project builds the core camera library plus several optional plugin modules, a sample app, documentation, and publishing/tooling support.
2. Core library boundary: cameraK
cameraK is the main product module. Its public API lives in src/commonMain and is split into:
- state management (CameraKState, CameraKStateHolder)
- camera control (CameraController)
- Compose-facing UI primitives (CameraPreviewView, rememberCameraKState, CameraKScreen)
- shared configuration and result types (AspectRatio, FlashMode, ImageCaptureResult, VideoConfiguration, CameraKEvent, etc.)
This common layer defines the contract that all platforms and plugins must obey.
3. Reactive runtime flow
The central runtime model is state-driven:
- UI calls rememberCameraKState(...)
- this creates a CameraKStateHolder
- the holder exposes StateFlow<CameraKState>, StateFlow<CameraUIState>, and SharedFlow<CameraKEvent>
- when the camera reaches Ready, the UI receives a platform-specific CameraController
- plugins subscribe to the same holder and activate when the camera becomes ready
This is the main data flow to diagram: UI/configuration → state holder → platform controller → events/results back to UI/plugins.
4. Platform-specific camera backends
cameraK uses expect/actual boundaries for the camera controller, preview UI, permissions, and state helpers. Each platform has its own implementation under:
- androidMain
- appleMain
- desktopMain
The backend technologies materially differ:
- Android: CameraX
- iOS: AVFoundation
- Desktop: JavaCV
These implementations are the hardware-adapter layer beneath the shared API.
5. Android-specific implementation
Android code contains builder/controller classes, Compose preview integration, permission handling, and utility code. The Android manifest lives in the module, so Android has explicit runtime permission and camera lifecycle concerns that are isolated from common code.
6. Apple/iOS-specific implementation
The Apple source set includes controller and preview implementations, permission provisioning, video recording delegation, burst capture management, and Objective-C interop utilities. This indicates iOS is not just a thin wrapper; it has its own capture/session management and platform bridging.
7. Desktop-specific implementation
Desktop has a more imperative capture pipeline with classes like CameraGrabber, FrameConverter, ImageCaptureManager, and ImagePanel. That suggests the desktop backend handles frame acquisition and rendering differently from mobile, while still presenting the same common controller/state API.
8. Plugin architecture
The library is designed around attachable plugins via CameraKPlugin and CameraKStateHolder.attachPlugin(...). Plugins are not separate apps; they are runtime extensions that listen to camera readiness, camera events, and frame/capture data. Their lifecycle is tied to the camera state holder: onAttach / onDetach.
9. Optional plugin modules
Several standalone modules extend the core camera pipeline:
- imageSaverPlugin: persists captures to files/storage
- qrScannerPlugin: scans camera frames for QR codes
- ocrPlugin: performs text recognition; includes desktop trained data
- videoRecorderPlugin: records video from the camera session
- analyzerPlugin: likely a lower-level frame analysis extension
These modules depend on the core API, not the sample app, and plug into the shared event/state flow.
10. Capture and recording data paths
The core library exposes two capture paths:
- still capture via takePictureToFile() or legacy takePicture()
- video recording via controller/state-holder methods and VideoCaptureResult
Plugins can intercept or react to these flows: image saver consumes capture results, QR/OCR consume frame streams, and the video recorder emits its own recording events.
11. Sample application
Sample is a Compose Multiplatform app demonstrating library usage across Android, desktop, iOS, and JS targets. It contains shared UI/theme code, platform entry points, and resource assets. This module is for validation and demonstration rather than being part of the library runtime.
12. Documentation, release, and publishing
The repo includes docs/ with API and guides, mkdocs.yml for site generation, and GitHub Actions for documentation and Maven Central publishing. convention-plugins and Gradle Kotlin DSL scripts indicate the build is standardized around shared publication conventions and multiplatform module setup.
Main entry points: state State holder · compose Compose API · controller Controller API · cameraK Shared API
Components 18
Core library
Shared camera API, state machine, and platform backends.
- Shared API · Public camera contract, enums, result types, permissions, and plugin hooks.
cameraK/src/commonMain/kotlin/com/kashif/cameraK - State holder · Owns CameraKState, exposes state flows, shared events, and plugin attachment lifecycle.
cameraK/src/commonMain/kotlin/com/kashif/cameraK/state - Compose API · rememberCameraKState, CameraPreviewView, and CameraKScreen for UI integration.
cameraK/src/commonMain/kotlin/com/kashif/cameraK/compose - Controller API · Platform-neutral controller contract used to configure capture, preview, and recording.
cameraK/src/commonMain/kotlin/com/kashif/cameraK/controller - Android backend · Android controller, preview, permissions, and builder implementation.
cameraK/src/androidMain/kotlin/com/kashif/cameraK - Apple backend · iOS controller, preview, permissions, burst capture, and recording delegation.
cameraK/src/appleMain/kotlin/com/kashif/cameraK - Desktop backend · Desktop capture pipeline for frame grabbing, conversion, rendering, and capture management.
cameraK/src/desktopMain/kotlin/com/kashif/cameraK - Plugin API · CameraPlugin interface used to attach runtime extensions to the state holder.
cameraK/src/commonMain/kotlin/com/kashif/cameraK/plugins
Plugins
Attachable runtime extensions that consume camera state and frames.
- Image saver · Persists still capture outputs to files or storage targets.
ImageSaverPlugin/src/commonMain/kotlin/com/kashif/imagesaverplugin - QR scanner · Scans camera frames for QR codes across supported platforms.
qrScannerPlugin/src/commonMain/kotlin/com/kashif/qrscannerplugin - OCR plugin · Performs text recognition, including desktop trained-data support.
ocrPlugin/src/commonMain/kotlin/com/kashif/ocrPlugin - Video recorder · Adds video recording behavior on top of the shared camera session.
videoRecorderPlugin/src/commonMain/kotlin/com/kashif/videorecorderplugin - Analyzer plugin · Lower-level frame analysis extension point for camera streams.
analyzerPlugin/src/commonMain/kotlin/com.kashif.analyzerPlugin
Sample app
Multiplatform demo application and platform entry points.
- Sample UI · Shared sample app UI, theme, utilities, and resources.
Sample/src/commonMain/kotlin/org/company/app - Entry points · Android, desktop, iOS, and JS app entry points and theme wiring.
Sample/src
Docs and tooling
Documentation, publishing conventions, and repo-wide build support.
- Docs site · Guides, API pages, examples, and site assets for users of the library.
docs - Build conventions · Convention plugins and shared Gradle configuration for publication and multiplatform setup.
convention-plugins - Repo build · Root Gradle settings, version catalog, and shared build orchestration.
Connections 21
- Compose API → State holder: creates state · UI entry points initialize and observe the shared state holder.
- State holder → Controller API: exposes controller · When ready, the state holder publishes the active controller to consumers.
- State holder → Plugin API: attaches plugins · Plugins register with the holder and follow onAttach/onDetach lifecycle.
- Shared API → State holder: defines state · Shared types define the camera state machine and events.
- Shared API → Controller API: defines contract · Common API defines the controller surface used by all platforms.
- Shared API → Compose API: exposes compose · Compose-facing helpers live in the common API layer.
- Controller API → Android backend: actualized by · Android provides the CameraX-backed controller implementation.
- Controller API → Apple backend: actualized by · Apple provides the AVFoundation-backed controller implementation.
- Controller API → Desktop backend: actualized by · Desktop provides the JavaCV-backed controller implementation.
- Compose API → Android backend: renders on · Android supplies the platform preview and permission flow.
- Compose API → Apple backend: renders on · Apple supplies the platform preview and permission flow.
- Compose API → Desktop backend: renders on · Desktop supplies the platform preview and permission flow.
- Image saver → State holder: listens to capture · Consumes capture results from the shared state/event flow.
- QR scanner → State holder: listens to frames · Consumes camera frames and readiness events.
- OCR plugin → State holder: listens to frames · Consumes camera frames for text recognition.
- Video recorder → State holder: records from state · Integrates with the active session and recording events.
- Analyzer plugin → State holder: analyzes stream · Hooks into the camera stream for analysis and processing.
- Sample UI → Compose API: uses API · The sample app consumes the shared Compose camera surface.
- Entry points → Sample UI: launches app · Platform entry points bootstrap the shared sample UI.
- Docs site → Shared API: documents · Docs describe the public API and usage patterns.
- Build conventions → Repo build: supports build · Convention plugins are applied through the repository build setup.