screenCapture

screenCapture is a low-latency Windows desktop capture and RTMP streaming tool.

It captures the desktop with the Windows Magnification API, encodes video with FFmpeg + libx264, and publishes via RTMP/FLV.

The project also includes a sample WebSocket control server in server/ (plus a sample mediamtx config) to demonstrate rule delivery and integration. In real production usage, developers are expected to implement their own backend/service.

---

Features

• Real-time desktop capture on Windows
• H.264 encoding (libx264)
• RTMP output (FLV muxing)
• Dynamic window exclusion rules via WebSocket
• One-shot BMP snapshot mode for capture validation
• Low-latency queueing behavior (drop old frame when encoder lags)
• Periodic runtime stats logging

Note: the current capture/encode pipeline is effectively fixed at 30 FPS. The --fps argument is parsed and logged, but does not change the internal pipeline rate at this time.

---

Project Layout

.
├── src/
│   ├── main.cpp
│   ├── magnifier_capture.*   # desktop capture
│   ├── h264_encoder.*        # H.264 encoding
│   ├── rtmp_streamer.*       # RTMP output
│   ├── ws_client.*           # WebSocket client
│   ├── window_filter.*       # exclusion rule engine
│   └── snapshot_writer.*     # BMP snapshot writer
├── server/
│   ├── server.py             # sample WebSocket rule server
│   └── mediamtx.yml          # sample mediamtx configuration
├── scripts/
│   └── build_ffmpeg_minimal.sh
├── toolchain-mingw64.cmake
└── CMakeLists.txt

---

Requirements

Runtime

• Windows x64 desktop session (Magnification API required)

Build (recommended workflow)

• Linux + mingw-w64 cross-compilation toolchain
• CMake >= 3.14
• Python 3 (only needed for the sample server)

---

Dependencies

C++ side

• FFmpeg (avcodec, avformat, avutil, swscale)
• x264 (through FFmpeg libx264 encoder)
• IXWebSocket (via CMake FetchContent)
• nlohmann/json (via CMake FetchContent)

Sample server side

• Python package: websockets

pip install websockets

---

Build

1) Build minimal FFmpeg (optional but recommended)

This project provides a helper script that installs to:

• third_party/ffmpeg/install

./scripts/build_ffmpeg_minimal.sh --shared

It enables only the components needed by this project (including RTMP + FLV + libx264).

2) Configure and compile

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=toolchain-mingw64.cmake \
  -DSCREENCAPTURE_USE_LOCAL_FFMPEG=ON

cmake --build build

Expected output:

• build/output/screenCapture.exe
• Required FFmpeg runtime DLLs copied into the same output directory

---

Running

RTMP mode (default mode)

screenCapture.exe \
  --rtmp rtmp://127.0.0.1:1935/stream \
  --ws ws://127.0.0.1:8765 \
  --bitrate 5000 \
  --enable-stats

Snapshot mode

screenCapture.exe --snapshot test_capture.bmp

---

CLI Arguments

--rtmp <url>        RTMP publish URL (mutually exclusive with --snapshot)
--snapshot <path>   Capture one frame to BMP and exit
--ws <url>          WebSocket server URL for rule updates
--fps <n>           Requested FPS (pipeline currently fixed at 30)
--bitrate <kbps>    Target bitrate in kbps (default: 5000)
--width <n>         Output width  (0 = virtual screen width)
--height <n>        Output height (0 = virtual screen height)
--enable-stats      Enable periodic stats logs (every 3s)
--verbose           Verbose logs
--help              Show help

---

WebSocket Control Protocol (Summary)

screenCapture acts as a WebSocket client and handles basic JSON message types.

Server -> Client

• Set exclusion rules:

{"type":"set_rules","rules":[{"type":"image_name","name":"msedge.exe"}]}

• Request top-level window list:

{"type":"get_hwnd_list"}

• Request runtime status:

{"type":"get_status"}

Client -> Server

• Status response:

{"type":"status","running":true,"rules":2}

• Window list response:

{"type":"hwnd_list","windows":[{"hwnd":"0x12345","title":"Notepad","pid":1234,"image_name":"notepad.exe"}]}

Supported rule types

• title_contains
• title_regex
• image_name
• hwnd_list
• pid_hwnd
• pid_tree

---

About server/ (Sample Only)

The server/ directory is provided as an integration example:

• server.py demonstrates a simple interactive WebSocket rule server
• mediamtx.yml demonstrates a minimal RTMP server config

This is not intended as a production backend. For real deployments, implement your own service (auth, persistence, multi-client policy, monitoring, etc.) based on your environment and requirements.

---

License

Licensed under GPL-3.0-or-later. See LICENSE.