Product Philosophy
Relevant source files
The following files were used as context for generating this wiki page:
The Product Philosophy of Crisp serves as the foundational decision-making framework for the project's development. It emphasizes a native macOS aesthetic, uncompromising data safety, technical transparency, and a strict separation of concerns between the user interface and the processing engine.
Crisp is designed to be a high-performance utility that feels like a native part of the Apple ecosystem while ensuring that user footage is handled with maximum care. Every architectural choice, from the local-only processing to the communication protocol between layers, is driven by these core tenets.
Core Philosophical Tenets
The project adheres to five primary rules that drive every engineering and design decision.
1. Don't Stick Out
The application must appear as if it were designed by Apple. This involves the use of system fonts, SF Symbols, native materials (like .regularMaterial), and standard macOS controls. The goal is to provide a seamless user experience that integrates perfectly with the operating system environment.
Sources: CLAUDE.md:12-13, CLAUDE.md:195-197
2. Never Lose the User's Footage
Data safety is paramount. Crisp follows a non-destructive workflow:
- The app never overwrites or deletes a source file.
- It always writes output to a new file named
<name>_cleaned.mp4. - By default, it backs up original footage into a dated folder (e.g.,
~/.crisp*/Originals/<yyyy-MM-dd>/).
Sources: CLAUDE.md:14-19, README.md:11-13
3. Honest About Quality
The application prioritizes technical integrity over hidden optimizations. While cutting requires re-encoding for frame accuracy, Crisp ensures:
- No downscaling: resolution and frame rate are maintained.
- High-quality H.264 (CRF 20) encoding.
- Automatic fallback to software encoding if hardware media engines are unavailable.
Sources: CLAUDE.md:20-22, CLAUDE.md:139-144
4. Layers That Don't Leak
Crisp maintains a strict architectural boundary between the UI and the processing engine. The Python engine is completely agnostic of the Swift UI; it communicates exclusively through --ndjson on stdout. Swift services drive the process and publish progress to the views.
Sources: CLAUDE.md:23-25
5. One System, Not Two
Code and component reuse are prioritized. Shared components are used across different surfaces rather than creating duplicates. Generalization is preferred over forking logic.
Sources: CLAUDE.md:26-27
Privacy and Data Sovereignty
A cornerstone of the Crisp philosophy is the "Private by Default" approach. All video and audio processing occurs 100% locally on the user's Mac.
The diagram above illustrates the local processing loop where no external servers are involved in the core cleaning workflow.
Sources: apps/web/src/content/legal.tsx:37-45, README.md:37-37
Connectivity Exceptions
To remain transparent, the application defines the only three scenarios where it connects to the internet:
- Model Download: A one-time download of the speech model (~148 MB) from Hugging Face.
- Update Checks: Querying the GitHub API for newer versions (Stable and Nightly channels).
- Homebrew Installation: Managed via the Homebrew package manager.
Sources: apps/web/src/content/legal.tsx:55-75
Technical Integrity and Cut Smoothing
The philosophy of being "Honest about Quality" extends to the engineering of the cuts themselves. To avoid janky jump-cuts or audible artifacts, Crisp implements specific "smoothing" phases.
| Feature | Philosophy | Implementation |
|---|---|---|
| Audio Micro-fade | Avoid audible clicks/pops | 10ms afade in/out on every segment. |
| Zero-crossing Snap | Precise splices | Nudge cut boundaries to nearest audio zero-crossing (±12ms). |
| Crossfade | Soften visual jumps | Optional matched A/V crossfade (xfade/acrossfade). |
| Frame Accuracy | Professional output | Sub-microsecond precision in filtergraphs using %.6f. |
Sources: apps/desktop/Resources/engine/NOTES.md:5-52
Human-in-the-Loop AI
In research-driven features like "Retake Detection," Crisp adopts a philosophy of "Honest Ceilings." The app acknowledges that fully-trusted silent auto-cuts for natural speech are not achievable with current technology. Instead, it focuses on:
- Raising candidate recall.
- Aggressively filtering false positives via signal agreement.
- Surfacing high-confidence suggestions rather than forced cuts.
Sources: retake-research.md:8-13
The diagram shows the communication flow where the Engine provides data to the UI via NDJSON, but the philosophy allows for user intervention in complex scenarios like retakes.
Sources: CLAUDE.md:23-25, retake-research.md:92-98
Summary
The Product Philosophy of Crisp ensures that it remains a professional-grade, private-by-design utility. By strictly adhering to native macOS standards and non-destructive data handling, the project builds trust with users while maintaining a high bar for technical excellence and architectural cleanliness. Significance of this philosophy is reflected in the local-first processing, transparent update mechanisms, and the high-quality output generated by the underlying engine.