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 Selection (
list_monitors&StandbyWindow):- Enumerates connected displays (
Ekran 1,Ekran 2, ...) and matches physical coordinates acrossdxcamandmss. Changing the selected screen on the Warm Standby bar cleanly re-arms the capture engine for that display's exact resolution.
- 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