Instant Warm Standby screen recorder, minimalist preview trimmer, and lossless FFmpeg clip exporter for Windows.
QuickClip splits capture, UI preview/trimming, lossless export, and orchestration behind clean inter-module contracts in src/quickclip/contracts.py:
+-------------------------------------------------------------------+
| QuickClipController (src/quickclip/app.py) |
| - Marshals background signals -> Qt main thread (QueuedConnection)|
| - Serializes heavy capture/export/cleanup on ThreadPoolExecutor |
+----+-----------------------+-----------------------+--------------+
| | |
v v v
+-----------------+ +------------------+ +------------------------+
| capture/ | | ui/ | | exporter/ |
| - CaptureEngine | | - StandbyWindow | | - ExporterService |
| - HotkeyListener| | - TrimmerWindow | | ffmpeg -c copy |
| - audio helpers | | - RangeSlider | | -movflags +faststart |
+-----------------+ +------------------+ +------------------------+
-
Warm Standby (
CaptureEngine):warm_up()probes and caches the fastest available H.264 encoder once (h264_amf->h264_nvenc->h264_qsv->libx264), initializes the screen grabber (dxcamDXGI Desktop Duplication primary with automaticmssfallback), and pre-spawns a standbyffmpegsubprocess readingrawvideo(bgra) overstdinintotemp_raw.mkv.start_recording()immediately begins feeding grabbed frames into the already-open pipe (no process spawn delay on hotkey press), writing fixed-interval keyframes (keyframe_interval_sec=0.5,-bf 0) so downstream stream-copy trimming seeks accurately.stop_recording()closesstdin, waits forffmpegto finalizetemp_raw.mkv, probes duration/metadata viaffprobe, and returns aCaptureResult.
-
Minimalist Preview & Trimming (
TrimmerWindow&RangeSlider):- Opens automatically when a valid
CaptureResultarrives, displaying aQMediaPlayerpreview and dual-handle timeline (RangeSlider) with Spacebar play/pause and optional loop playback. - Calls
release_media()(stop()+setSource(QUrl())) before emittingexportRequestedordiscardRequestedso Windows releases file locks ontemp_raw.mkv.
- Opens automatically when a valid
-
Lossless Stream-Copy Export (
ExporterService):- Trim export places both
-ssand-tobefore-iwith-c copy -movflags +faststart(ffmpeg -y -ss <start> -to <end> -i <source> -c copy -movflags +faststart <output>) for instant zero-re-encode clipping. - Direct save remuxes directly via
-c copy -movflags +faststart. - Safely removes
temp_raw.mkvwith Windows lock retry only after output validation succeeds, thenQuickClipControllerre-armsCaptureEngineback toSTANDBY.
- Trim export places both
-
Inter-Module Contracts (
src/quickclip/contracts.py):CaptureState(str, Enum):COLD,WARMING,STANDBY,RECORDING,STOPPING,ERRORMonitorInfo,CaptureConfig,CaptureResult(with.is_valid),TrimRequest(with.validate()),TrimResult,AppConfig- Runtime-checkable protocols:
ICaptureEngine,IExporterService,IHotkeyListener
-
Multi-Monitor, Region Selection & Settings (
StandbyWindow,RegionSelectorOverlay,settings.py):- Enumerates connected displays (
Ekran 1,Ekran 2, ...) and matches physical coordinates acrossdxcamandmss. - Switch between Tam Ekran (instant Warm Standby) and Bölge Seç (drag-select any area on screen after clicking Start Recording / hotkey, with DPI-aware coordinate scaling).
- Change the global hotkey (Değiştir) and export output folder (Klasör Seç) directly from the standby bar; preferences persist automatically in
%LOCALAPPDATA%\QuickClip\settings.json.
- Enumerates connected displays (
- OS: Windows 10/11
- Python: 3.12+
- External tools on
PATH:ffmpegandffprobe(verified with FFmpeg 9.0.2)
Create and populate the virtual environment (already configured in .venv/):
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev,dxgi]".\.venv\Scripts\python.exe main.pyUseful CLI flags:
.\.venv\Scripts\python.exe main.py --help
.\.venv\Scripts\python.exe main.py --hotkey F9 --fps 60 --output-dir "$env:USERPROFILE\Videos\QuickClip"
.\.venv\Scripts\python.exe main.py --auto-stop 5.0
.\.venv\Scripts\python.exe main.py --cpu-only --audio
.\.venv\Scripts\python.exe main.py --headless-checkBuild the --onedir --windowed standalone bundle (bundling ffmpeg.exe, ffprobe.exe, assets/quickclip.ico, assets/quickclip.png, PySide6 QtMultimedia plugins, dxcam, mss, and keyboard) into dist\QuickClip\QuickClip.exe:
powershell -ExecutionPolicy Bypass -File scripts/build_exe.ps1Create Desktop and Start Menu shortcuts pointing to dist\QuickClip\QuickClip.exe:
powershell -ExecutionPolicy Bypass -File scripts/create_shortcuts.ps1Note:
QuickClip.exeruns single-instance (QLocalServer) — launching a second time restores and focuses the running QuickClip window. Toggle "Windows ile Başlat" on the standby bar to register/unregisterHKCU\Software\Microsoft\Windows\CurrentVersion\Run.
Run the full test suite (contracts, capture, UI, exporter, and end-to-end integration):
.\.venv\Scripts\python.exe -m pytest -vRun in headless/offscreen Qt mode:
$env:QT_QPA_PLATFORM="offscreen"
.\.venv\Scripts\python.exe -m pytest -v