Epiphan Align Tool

A tool for aligning and calibrating Epiphan analog capture cards (the DVI2PCIe family and similar local Epiphan VGA/DVI grabbers) that digitize a legacy computer's analog VGA output.

Digitizing an analog VGA signal well requires tuning several capture-card parameters against the actual signal: horizontal/vertical position, pixel clock (PLL), sample phase, and per-channel black level (offset) and gain. Get any of these wrong and the picture is shifted, torn, blurry, or has a color tint. This tool automates that tuning against a gradient/stripe test pattern and gives you manual control when you need it.

Features

• Live preview of the capture card's signal.
• AUTO alignment — automatically finds horizontal/vertical sync position, per-channel black level (offset) and white level (gain), and sample phase, driven by a gradient-bar test pattern.
• TUNE PLL — automatically locks the pixel-clock PLL using an equivalent-time-sampling technique (deliberately detuning to measure drift, then finding the "dead zone" and its flattest point).
• Manual controls for every capture parameter (h/v position, PLL, phase, per-channel offset/gain), with -/+ step buttons and type-then-commit fields that only apply on Enter or focus loss.
• Scope / gradient diagnostic panel — visualizes the gradient and stripe traces, reconstructs a pixel-clock-period rise/fall curve, and estimates rise time and bandwidth (with optional capture-card-bandwidth de-embedding to estimate the source's own bandwidth).
• Source color depth detection — estimates whether the source is running 24-bit truecolor, 16-bit RGB565, or 15-bit RGB555 by analyzing DAC quantization steps in the gradient bar.
• Multi-device support — --list-devices, --device-index, and --serial command-line options to pick a specific capture card when more than one is connected.
• Resolution-change handling — detects when the source switches to a genuinely different video mode mid-session and re-adapts instead of getting stuck rolling back to the old mode.

Requirements

• Windows (the tool loads frmgrab.dll via ctypes and talks to the Epiphan kernel driver; it will not run on other platforms as-is).
• An Epiphan local capture device (e.g. DVI2PCIe, VGA2PCIe, VGA2USB, DVI2USB) with its Epiphan device driver installed. frmgrab.dll itself is already bundled in lib/.
• Python 3.11 or newer.
• A signal source showing a gradient/stripe test pattern (gray gradient bar, alternating black/white stripes, solid black band, color bars) for the AUTO/TUNE PLL/color-depth features to work against. Manual controls and the live preview work with any signal.

Installation

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py

For development (running black, mypy, flake8), also install the dev dependencies:

pip install -r requirements-dev.txt

Both requirements.txt and requirements-dev.txt are pinned to exact versions with sha256 hashes. For hash-verified installs, add --require-hashes:

pip install --require-hashes -r requirements.txt

Command-line options

python main.py --list-devices           # list local Epiphan devices and exit
python main.py --device-index 1         # open a specific device by index
python main.py --serial D2P85331        # open a specific device by serial number

License

MIT. See LICENSE.