Cut Smoothing
Relevant source files
The following files were used as context for generating this wiki page:
Cut Smoothing is a specific subsystem within the Crisp engine designed to eliminate audible clicks, pops, and jarring visual transitions that occur during automated video editing. In jump-cut editing, hard splices often land at arbitrary millisecond positions where audio waveforms may have non-zero amplitudes, causing a step discontinuity.
The system addresses these issues through a three-phase approach: audio micro-fades, matched A/V crossfades, and zero-crossing snapping. These techniques ensure that the final cleaned video feels professional and seamless, reducing the need for manual post-processing in external video editors.
Sources: apps/desktop/Resources/engine/NOTES.md:1-12
Architecture and Logic
The Cut Smoothing system is integrated into the crisp/edit.py module and driven by configurations defined in crisp/config.py. The logic is executed during the rendering phase of the video cleaning pipeline.
The diagram above shows the high-level data flow where smoothing operations are applied to segments before the final rendering process.
Sources: apps/desktop/Resources/engine/NOTES.md:14-18, apps/desktop/Resources/engine/crisp/pipeline.py:380-385
Phase 1: Audio Micro-fades
Micro-fades apply a very short afade (in/out) to every kept audio segment. This ensures the waveform meets zero at each splice point, effectively killing the "click" sound without being audible as a fade to the user. This phase preserves exact segment length, keeping audio and video in perfect sync.
- Implementation: Controlled by
--fade-ms. - Logic: Capped at half a segment length to prevent errors on very brief audio slivers.
Sources: apps/desktop/Resources/engine/NOTES.md:20-24, apps/desktop/Resources/engine/crisp/config.py:53
Phase 2: Matched A/V Crossfades
Crossfades allow consecutive segments to dissolve into one another rather than hard-cutting. This applies a video xfade and an audio acrossfade of equal duration.
- Implementation: Controlled by
--crossfade-ms. - Logic: Both streams are shortened equally to maintain synchronization. If a segment is too short to support the requested dissolve duration, the system falls back to a hard concat.
Sources: apps/desktop/Resources/engine/NOTES.md:25-30, apps/desktop/Resources/engine/crisp/config.py:54
Phase 3: Zero-Crossing Snap
This phase nudges interior cut boundaries to the nearest audio zero-crossing within a specified window. By splicing where the signal is already at or near zero, the workload for Phase 1 fades is reduced, and mid-syllable cuts are avoided.
- Implementation: Controlled by
--snap-ms. - Logic: Operates on the 16-bit mono analysis WAV. It is best-effort; if a read error occurs, the original boundaries are maintained. It is skipped when using a reviewed keep-file.
Sources: apps/desktop/Resources/engine/NOTES.md:31-38, apps/desktop/Resources/engine/crisp/config.py:55
Configuration and Implementation
The behavior of the smoothing system is dictated by four primary variables defined in the Python engine and exposed through the macOS desktop application settings.
Engine Configuration Constants
| Variable | Default Value | Description |
|---|---|---|
DEFAULT_FADE_MS | 10 ms | Audio fade-in/out on each kept segment to prevent clicks. |
DEFAULT_CROSSFADE_MS | 0 ms | Duration for dissolves between segments (0 = off). |
DEFAULT_SNAP_MS | 12 ms | Window size for snapping cuts to audio zero-crossings. |
Sources: apps/desktop/Resources/engine/crisp/config.py:53-55
Desktop App Integration
The Cut Smoothing knobs are exposed in the Settings > Cutting section of the Crisp desktop app. These settings are forward-compatible and persist in ~/.crisp*/config/settings.json.
The sequence diagram illustrates how user adjustments in the macOS UI are passed down to the Python engine as CLI arguments.
Sources: apps/desktop/Resources/engine/NOTES.md:43-51, apps/desktop/Sources/Crisp/Views/SettingsView.swift:133-145, CLAUDE.md: "The engine"
Technical Constraints and Future Work
- Precision: The system uses microsecond precision (
%.6f) in filtergraphs to prevent cut positions from drifting due to millisecond rounding. - Sample Rate Limitations: Snapping currently occurs against a 16 kHz analysis WAV. While inaudible due to micro-fades, future iterations may snap against the source's native sample rate (e.g., 48 kHz) for exact precision.
- A/V Sync: Phase 1 and Phase 2 are specifically designed to shorten or maintain stream lengths equally, ensuring no lip-sync errors are introduced.
Sources: apps/desktop/Resources/engine/NOTES.md:54-65
Summary
Cut Smoothing is a critical quality-of-life feature in Crisp that automates the "polishing" of jump-cuts. By combining waveform analysis (zero-crossing) with standard signal processing techniques (fades and crossfades), it transforms raw, janky edits into professional-grade video output automatically.