Repository navigation
Engineering Standards and Validation
Fast is a feature. Correct is the admission price.
SyLC qualifies changes at the byte, frame, clock and final-container levels because video bugs are excellent actors.
The project spans a decoder, demuxers, GPU shaders, asynchronous presentation, neural inference, disc I/O and multiview export. No single test style can cover all of that. The validation strategy therefore uses layered contracts: small deterministic tests near the algorithm, bit-exact reference gates at decode/render boundaries, live measurements for scheduling, and dogfood reads of produced media.
| Contract | What must remain true |
|---|---|
| Decode identity | Optimization must not change decoded planes |
| Stereo pairing | Left and right views represent the same presentation instant |
| Colour identity | Metadata-selected conversion reaches the intended SDR/HDR output path |
| Temporal behaviour | Depth and presentation advance in media time, independent of compute rate |
| Graceful fallback | Optional failure never masquerades as valid stereo or kills unrelated playback |
| Artifact hygiene | Release packages contain required redistributables and exclude weights/caches with incompatible or unverified licences |
| Export truthfulness | A completed file contains two decodable views, complete duration and the metadata it claims |
These are product requirements, not merely developer preferences. A user can see every one of their failures, although not always under its real name.
tools_dev/bench_decode.py preloads access units and times only the native MVC decode region. Each run also computes CRCs for every decoded frame, both views and all planes.
.venv\Scripts\python.exe tools_dev\bench_decode.py <media.mkv> --sweep 0,2,3,4,6,8,12
.venv\Scripts\python.exe tools_dev\bench_decode.py <media.mkv> --dll .perf_backup\edge264.dll.bakThe worker sweep answers two questions at once:
- Which thread count helps this CPU/source?
- Does every candidate return the same decoded bytes?
Keep --no-verify consistent across comparisons. The CRC pass affects cache state between timed segments and can move timings by roughly ten percent. A frame-count tail difference is reported separately from a pixel difference; ok (599f) and DIFF @n do not belong in the same category simply because both contain digits.
tools_dev/bench_frame_python.py measures Python work per displayed frame. In the current measured path, actual Python cost is tiny relative to a 41.7 ms film frame. That result is a decision: do not schedule a heroic JIT rewrite for a layer consuming hundredths of a millisecond.
Depth work has separate timing domains:
- inference on the GPU/provider;
- flow and temporal work on the CPU;
- render-pass cadence;
- readback-to-mailbox latency;
- waiting for input or result handoff;
- source PTS spacing.
This separation caught a real scheduling defect where 1080p conversion delivered fewer maps than 4K. Inference was faster at 1080p; the service was waiting for a readback command that the lighter render path had not flushed. Profiling only infer_ms would have optimized the innocent component.
tools_dev/bench_stabilizer.cpp exercises temporal stabilization outside the application and model runtime. It checks:
- selection against
std::nth_elementon adversarial inputs; - bit-exact results across serial and parallel selection paths;
- per-grid final-map hashes that can compare separate builds;
- worker scaling at square and rectangular inference grids.
Some reductions remain serial because floating-point association order is part of the output contract. Other operations, such as exact order statistics, may be parallelized when every correct algorithm returns the same selected value.
“Mathematically similar” is not always bit-exact. The project decides explicitly which guarantee each stage needs.
The 2D→3D pipeline is judged on more than average depth error.
A useful refinement must improve the intended surface error while preserving real discontinuities. Regression scenes check both directions:
- error against reference should decrease by the required margin;
- left-to-right depth volume must survive;
- a real surface break must not be blurred away;
- thin/diagonal structures must participate in the upsampler.
Tests cover calm regions, moving regions, occlusion invalidation, cuts, flashes, seeks and repeated/paused timestamps. The filter must resist model jitter without dragging old geometry behind motion.
A cut requires both an absolute depth residual and a gain over the ambient residual baseline. Busy footage can have high normal residuals; a fixed threshold alone produced false resets and visible pumping. The adaptive gate changes behaviour only when the measured background justifies it.
Rectangular graphs are benchmarked as complete service cycles, not by pixel count alone. Detection must reject dark scenes and asymmetric mattes, choose only compatible fixed shapes, keep bars at convergence and preserve square processing for genuine 16:9 content.
Native rendering tests bind real D3D11 resources where practical and compare output against locked references.
Important cases include:
- exact v5.2.1c image-forming shader resources;
- high-contrast silhouette corrections that must not manufacture intermediate grey;
- luma/chroma ownership consistency at 4:2:0 boundaries;
- disparity comfort projection that remains monotonic and sign-preserving;
- HDR path selection and P010 scaling;
- identical pixels outside sparse contour-repair regions.
A shader can compile, run and produce an image while violating all of those. “No device removed error” is a runtime smoke test, not a visual proof.
TensorRT engines depend on GPU architecture, runtime version, model graph and optimization shape. SyLC therefore treats an engine as a derived artifact with a specific identity.
Qualification includes:
- matching the local GPU/runtime family;
- building or downloading the graph-specific engine;
- verifying hashes/manifest data;
- running inference;
- comparing numerical output against the accepted model path;
- recording trust only after the value gate succeeds.
An attested square engine cannot authorize an adaptive rectangular graph. Rebuilding per graph is inconvenient in precisely the way seatbelts are inconvenient.
The MV-HEVC exporter does not trust a successful child-process exit code. It reopens the completed file and checks:
-
hvc1sample entry; -
hvcCandlhvCconfiguration boxes; - parseable
vexuspatial metadata; - two views reported by ffprobe;
- complete-enough frame count/duration;
- dependent-view NAL survival on remux paths;
- successful decode with SyLC's own MV-HEVC reader.
Only then is staged output atomically installed at the destination. This “dogfood gate” catches the particularly dangerous failure where every tool in the pipeline reports success and the final player sees one eye.
Before sharing a portable folder, inspect both presence and absence.
- native
.pydand its ebml/matroska dependencies; -
edge264.dll; - mpv and FFmpeg runtime closure;
- ONNX Runtime and DirectML when 2D→3D is supported;
- model manifest;
- deferred Python modules Nuitka cannot discover statically;
- export tools promised by the UI.
- ONNX model weights intended for on-demand download;
- TensorRT engine caches tied to one machine;
- model checkpoints and backups;
- non-commercial or licence-uncertain experimental models;
- temporary export/build directories;
- developer media and logs.
A whitelist is preferred to a glob for shipping model metadata. Automation should make the safe set easier to express than the dangerous set.
- State the user-visible bottleneck.
- Choose the timing that directly measures it.
- Hold source, verification mode, provider, grid and output surfaces constant.
- Warm caches consistently.
- Report medians and relevant tails, not the most photogenic run.
- Run correctness gates before accepting the speed result.
- Test the low-power target as well as the fastest development GPU.
- Leave a rollback switch for high-risk scheduling or visual changes until field evidence is mature.
The final question is not “did this function get faster?” It is “did the player deliver more correct frames, maps or output bytes under the same conditions?” Systems are full of components that became faster while the product became slower. SyLC has met several personally.
For build commands, see Building from source. For runtime symptoms and log collection, see Troubleshooting and diagnostics.
Start
Watch & preserve
Under the hood