FrameWitness

日本語

FrameWitness is an open-source Windows tool for local game-performance and system-latency benchmarking. It uses repeatable A/B measurements, bootstrap confidence intervals, minimum detectable effect (MDE), environment fingerprints, and validity gates to test whether a change improved the measured experience.

Status: pre-release source preview. No official binary or stable-support promise is available. Any GitHub Release is source-only.

English Game benchmark setup rendered directly from the real form without a desktop capture or focus activation. It contains no benchmark result or personal environment data.

Features

• Game benchmark: FPS, 1% low, 0.1% low, and p99/p99.9 frametime.
• Optional per-frame data and a detailed, portable single-file HTML report.
• Timeline presets, range selection, wheel zoom, and drag pan in HTML graphs.
• System diagnostics for DPC/ISR activity, driver busy time, spikes, and hard pagefaults.
• A/B comparison with confidence intervals, MDE, validity gates, and environment-difference checks.
• Native Windows UI and human-facing reports in English and Japanese.
• Game-benchmark durations from 60 through 900 seconds.

FrameWitness is a measurement decision gate, not a complete replacement for Windows-internals tools such as WPA or xperf.

Safety Boundary And System Changes

• FrameWitness does not inject code, read or write game memory, debug games, or request process-manipulation rights.
• It may briefly use PROCESS_QUERY_LIMITED_INFORMATION handles to measure background load and read executable metadata.
• The normal measurement data plane reads OS telemetry such as ETW and writes result files. It does not interpret an optimization.
• Explicit ab hooks (--pre-a, --pre-b, --verify-a, and --verify-b) and an approved screen run can execute opaque commands defined by an external caller. The caller remains responsible for command safety, backup, verification, and rollback.
• Only the explicit --auto-resume option may create a resume command file, register or remove a logon scheduled task, and request a reboot with a 15-second cancellation window.
• ETW measurements require administrator privileges.
• The design avoids invasive techniques, but it is not a guarantee of compatibility with every game or anti-cheat product. Follow each game's terms and support guidance.

Build From Source

Requirements: Windows 10/11, CMake, a C++20 compiler, and either Ninja or Visual Studio. Node.js is required for Playwright HTML UI tests.

npm ci
npm run install:browsers
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++
cmake --build build
ctest --test-dir build --output-on-failure -E "^package_smoke$"

MSVC is also supported:

npm ci
npm run install:browsers
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure -E "^package_smoke$"

Fetch optional standard probes from their official upstream releases:

powershell -File scripts\fetch-presentmon.ps1
powershell -File scripts\fetch-liblava.ps1

This public repository does not contain third-party executables.

UI And CLI

After building, start the English/Japanese UI with:

.\FrameWitness.bat

CLI examples:

.\build\benchcli.exe doctor
.\build\benchcli.exe run --process Game-Win64-Shipping.exe --scenario manual --duration 900 --lang en
.\build\benchcli.exe ab --probe present --session sample --runs 3 --duration 60 --lang en
.\build\benchcli.exe report --session sample --lang en

When per-frame capture is enabled, the detailed HTML can show frametime, FPS, and available latency data over time. The report embeds its CSS, JavaScript, and measurement data so it can be opened as a local file in a supported browser.

Compatibility

The product is named FrameWitness, but stable identifiers such as gamebench.run.v1 and gamebench.frames.v1 remain unchanged for existing data compatibility. Independent programs can integrate through the JSON/JSONL file contracts without linking FrameWitness code.

Public Documentation

• Vision
• Design overview
• Measurement specification
• A/B protocol
• Integration contracts
• Roadmap
• Visualization
• Workload suite
• Source availability
• Third-party notices

License, Contributions, And Security

The public source is GPL-3.0-only. Commercial use is permitted under the GPL's terms. A separate written license may be available from the copyright holder for copying or linking when GPL distribution is unsuitable. Merely using the independent file contract does not require that separate license.

Issues and design discussions are welcome. Pull requests containing code, documentation, images, or other copyrightable material are not accepted until the contribution-licensing process is ready. See CONTRIBUTING.md.

Do not put sensitive vulnerability details in a public issue. Use GitHub Private vulnerability reporting and read SECURITY.md.

This repository publishes source only. The local package helper does not create an official distribution. Anyone redistributing binaries must independently satisfy GPL corresponding-source requirements and all applicable third-party license and notice obligations.