Desktop App Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Crisp is a native macOS application designed to automate the cleaning of screen recordings and talking-head videos by removing long pauses and filler words. The architecture is built on a "layers that don't leak" philosophy, separating the Swift/SwiftUI user interface from a high-performance Python-based cleaning engine. The application is Apple-Silicon only (arm64) and prioritizes native system behaviors, local data processing, and non-destructive editing.
Sources: CLAUDE.md:1-20, apps/desktop/build.sh:44-46
Core Architectural Layers
The project is structured into distinct layers to ensure modularity and maintainability. Swift manages the UI, lifecycle, and service orchestration, while a Python engine performs the heavy lifting of media processing.
Layer Hierarchy
- UI Layer (SwiftUI): Displays state, handles user input, and publishes progress.
- Service Layer (Swift): Orchestrates the cleaning process, manages the speech model lifecycle, and handles application updates.
- Engine Layer (Python/C++): A standalone CLI that executes the cleaning pipeline (detection, transcription, and rendering).
Sources: CLAUDE.md:113-132, CLAUDE.md:144-149
Multi-Channel Distribution
Crisp uses a single codebase to support three distinct distribution channels: Stable, Nightly, and Dev. These channels can be installed side-by-side because they use unique bundle identifiers, application names, and data directories.
| Feature | Stable | Nightly | Dev |
|---|---|---|---|
| Bundle ID | com.syntaxlabtechnology.crisp | ...crisp.nightly | ...crisp.dev |
| App Name | Crisp | Crisp Nightly | Crisp Dev |
| Icon Color | Blue | Amber | Purple |
| Auto-Updates | GitHub Releases | GitHub (Rolling) | Disabled |
| Data Directory | ~/.crisp/ | ~/.crisp_nightly/ | ~/.crisp_dev/ |
Sources: CLAUDE.md:83-100, apps/desktop/build.sh:8-30
The Cleaning Engine
The engine is a pure Python (stdlib-only) package located in apps/desktop/Resources/engine/. It is driven by the Swift application as a subprocess, communicating via --ndjson on stdout.
Processing Pipeline
- Backup: The original file is copied to an originals folder (e.g.,
~/.crisp*/Originals/). - Pause Detection: Uses
ffmpeg silencedetectto find dead air based on audio energy. - Filler Transcription: Uses
whisper-cli(whisper.cpp) with aggml-base.en.binmodel to find timestamps for filler words like "um" or "uh". - Rendering: Trims and joins valid segments using
ffmpeg. It employs "Cut Smoothing" (micro-fades, crossfades, and zero-crossing snaps) to prevent audio clicks at jump-cut boundaries.
Sources: CLAUDE.md:144-156, apps/desktop/Resources/engine/NOTES.md:1-25
System Integration Components
Crisp integrates deeply with macOS through several auxiliary executables and services:
- CrispWatcher: A separate background agent that monitors specific folders and automatically cleans new recordings. It runs as a login-item
LaunchAgent. - CrispClean: A headless CLI invoked by the Finder "Clean with Crisp" Quick Action.
- QuickActionInstaller: Automatically installs an Automator workflow into
~/Library/Services/to provide right-click functionality in Finder. - App Intents: Metadata is generated during build to support macOS Shortcuts and Spotlight.
Sources: apps/desktop/Package.swift:34-55, apps/desktop/Sources/Crisp/Services/QuickAction/QuickActionInstaller.swift:10-25, apps/desktop/build.sh:110-125
Build and Resource Management
The application is built using a custom build.sh script and the Swift Package Manager.
Binary Packaging
Crisp bundles its own dependencies to be self-contained within the .app bundle:
- Python Runtime:
python-build-standalone. - Media Tools:
ffmpegandffprobe. - ML Runtime:
whisper-cli(built from source via cmake). - Core ML Helpers:
crisp-filler(on-device filler detection) andcrisp-embed(semantic similarity for retakes).
The speech model (ggml-base.en.bin, ~148MB) is not bundled. It is downloaded on first run via ModelStore to reduce update payload sizes.
Sources: CLAUDE.md:175-188, apps/desktop/build.sh:54-75, apps/desktop/Package.swift:57-78
Conclusion
The Crisp desktop architecture effectively combines the rapid UI development of SwiftUI with the flexibility of a Python-driven media engine. By abstracting complexity into CrispCore and using a subprocess-based engine, the application maintains high performance and system stability while offering a native, "Apple-like" user experience. This structure also facilitates experimental research, such as the on-device "Wren" ML models, without destabilizing the production cleaning pipeline.
Sources: CLAUDE.md:113-132, apps/desktop/Package.swift:20-30