Introduction to Crisp

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• idea.md
• apps/desktop/Resources/engine/NOTES.md
• research/NOTES.md
• apps/desktop/build.sh
• apps/desktop/Package.swift

Crisp is a native macOS application designed to automate the post-production of screen recordings and talking-head videos. Its primary function is to eliminate long pauses, silence, and filler words (such as "um", "uh", "hmm") from both audio and video streams simultaneously, resulting in tight, professional jump-cuts without degrading source quality.

The project is architected as a native SwiftUI frontend (apps/desktop) that drives a Python-based processing engine (apps/desktop/Resources/engine) as a subprocess. This separation ensures a responsive native UI while leveraging the extensive multimedia capabilities of Python, FFmpeg, and specialized Machine Learning models.

Sources: CLAUDE.md:3-8, README.md:3-10

Core Product Philosophy

The development of Crisp is guided by five foundational principles:

1. System Integration: The app must mirror macOS native design (SF Symbols, native materials, system fonts).
2. Data Safety: It never overwrites or deletes source files; it creates a _cleaned.mp4 and provides an automated backup system.
3. High Fidelity: Cuts require re-encoding but maintain original resolution, frame rate, and high-quality H.264/HEVC settings.
4. Decoupled Layers: The Python engine is agnostic of the UI, communicating via NDJSON on stdout.
5. Component Reuse: A single shared component system is used across the application to prevent duplication.

Sources: CLAUDE.md:10-25

System Architecture

Crisp utilizes a layered architecture where the Swift application manages user interaction, lifecycle, and progress reporting, while the Python engine handles heavy-lift multimedia processing.

Desktop App Structure

The macOS application is organized into specific layers:

• App/Views: SwiftUI-based display layer that owns the CleanModel and Updater.
• Services: Logic layer including CleanModel (spawns the engine), ModelStore (ML model lifecycle), and Updater.
• CrispCore: Shared logic for engine driving, configuration, and model management used by the main app and background agents.

Sources: CLAUDE.md:103-118, apps/desktop/Package.swift:15-22

The Processing Engine

The engine is a self-contained Python package located in Resources/engine/. It relies on a "stdlib-only" philosophy for Python to avoid external pip dependencies, instead shelling out to bundled binaries.

Processing Pipeline

When a video is processed, it follows a structured pipeline to ensure accuracy and quality:

1. Backup: The original file is copied to a _originals/ folder or a dated data home directory.
2. Silence Detection: ffmpeg silencedetect analyzes the audio energy to find pauses.
3. Filler Detection: This is handled by two possible backends:
   • Whisper: Uses whisper.cpp and the ggml-base.en.bin model for full transcription and word-level timestamps.
   • Wren/Raven: Specialized, tiny on-device ML models for fast filler classification.
4. Re-render: FFmpeg joins the segments using jump-cuts with optional audio micro-fades (default 10ms) to prevent audible clicks.

Sources: README.md:41-52, apps/desktop/Resources/engine/NOTES.md:15-25, research/NOTES.md:11-20

Feature Summary

Component	Description	Sources
Silence Removal	Automatically trims "dead air" based on audio energy levels.	README.md:44-46
Filler Removal	Eliminates "um", "uh", and "hmm" using ML transcription.	CLAUDE.md:4-5
Cut Smoothing	Applies 10ms micro-fades and zero-crossing snapping to prevent audio pops.	apps/desktop/Resources/engine/NOTES.md:15-33
Model Catalog	Downloads and manages ML models like ggml-base.en.bin (Whisper) or Wren.	CLAUDE.md:195-202
Watch Folder	Background agent (CrispWatcher) that cleans videos dropped in specific folders.	apps/desktop/build.sh:65-72

Release Channels

Crisp is distributed through three distinct channels to facilitate safe testing and deployment:

Channel	Bundle ID	Purpose
Stable	com.syntaxlabtechnology.crisp	The default, numeric-versioned release for end-users.
Nightly	...crisp.nightly	Experimental features; auto-updates from GitHub.
Dev	...crisp.dev	Local builds for developers; no auto-updates; distinct icon.

Sources: CLAUDE.md:73-85, apps/desktop/build.sh:8-25

Installation and Development

Development requires macOS 14+, Xcode, and Homebrew. The project uses a monorepo structure managed by Turborepo.

Building from Source

# Setup the environment (installs ffmpeg, whisper.cpp, and models)
./setup.sh

# Build and launch the developer version
cd apps/desktop && ./dev.sh

Sources: README.md:20-25, package.json:1-15

Summary

Crisp serves as a specialized tool for creators, reducing the manual labor of video editing by identifying and removing non-content audio/video segments. By combining native macOS performance with a portable Python engine and efficient ML models, it provides a high-fidelity, private-by-default cleaning solution.