ContinuityGuard

A local, zero-network CLI that scores your already-generated AI short-drama clips for character-consistency drift and physically implausible motion, before you spend render credits finding out the hard way.

node dist/cli.js scan ./generated-clips/

AI short-drama generation is having a real moment, and every title is a stack of individually generated shots. Generation models still drift: a character's face shifts slightly between cuts, or a motion jumps in a way that reads as physically wrong the moment a human watches it. Catching that after render is expensive. ContinuityGuard scans a folder of already-generated clips or frames from any pipeline and flags the shots worth a second look before you commit to a re-render.

Install

Two independent, equally first-class distributions ship the same scoring logic and the same bundled MobileNetV2 ONNX model. Honest status as of this writing: the Python package is published to PyPI; the TypeScript/ npm package is not yet published to the npm registry (the npm registry itself has no continuityguard-cli entry today).

Python, published today:

pip install continuityguard-cli

See python/README.md for the Python-specific quickstart, CLI reference, and library API.

TypeScript/npm, install from source for now:

git clone https://github.com/RudrenduPaul/ContinuityGuard.git && cd ContinuityGuard && npm install && npm run build

That's a real, freshly-run install: on this machine it took npm install about 2.5 seconds and npm run build about 0.7 seconds, with 0 vulnerabilities reported by npm audit. Once built, run the CLI directly with node dist/cli.js scan <directory>, or npm link it locally to get the continuityguard command on your PATH. This section will drop the "install from source" instructions in favor of a plain npm install the day the npm package is actually published -- tracked in CHANGELOG.md.

Table of Contents

• Features
• What it does
• Quickstart
• CLI reference
• Known limitations
• How it compares
• What is ContinuityGuard, and why does it exist
• Local-only, always
• FAQ
• Contributing
• License

Features

• Two independent scoring passes in one scan. Character-consistency (cosine similarity between MobileNetV2 embeddings of same-named-character crops) and physics-plausibility (frame-to-frame motion-discontinuity heuristic against each shot's own local baseline) both run from a single scan command.
• Zero network calls, checked mechanically on every push. npm run verify:zero-network monkey-patches every network entry point Node exposes and runs a real scan against this repo's own fixtures in CI; it fails loudly if any code path ever tries to reach the network.
• Structured output for both humans and pipelines. The same scan writes a human-readable terminal summary and a full machine-readable JSON report (--json), so a QA reviewer and a CI script can consume the same result.
• Fast on ordinary hardware. The 8-clip fixture scan (decode, both scoring passes, and report write) completed in 0.53 to 0.63 seconds across repeated runs on a laptop CPU during this audit. No GPU required; scoring runs on CPU via onnxruntime-node and a 14MB bundled model.
• Every flag comes with a reason you can check yourself. Each flagged shot carries the clip name, the numeric score, the threshold it crossed, and a plain-language explanation, sourced directly from the JSON report's reason field.

What it does

Real output, from this repo's own committed synthetic fixtures (src/score/testdata/clips/, generated by src/score/testdata/generate-fixtures.sh; no real short-drama footage was available for this build, so every number below is reproducible, not illustrative):

$ node dist/cli.js scan src/score/testdata/clips

ContinuityGuard v0.1 -- Local Character-Consistency & Physics-QA Scoring

Scanning: src/score/testdata/clips (8 clips, ffmpeg decode)

[SCORED] CG01 Clip Ingestion
  8 clips decoded, 51 frames extracted

[SCORED] CG02 Character-Consistency Scoring
  3 named characters tracked across 8 clips
  1 shot(s) flagged: low cross-shot similarity (below 0.88 cosine threshold)
    kenji_shot02.mp4 -- "kenji" similarity 0.77 vs. reference (kenji_shot01.mp4)
  NOTE: consistency scoring is best-validated on photorealistic content.
  Accuracy on stylized/anime-adjacent character designs is unverified --
  treat flags on stylized content as a prompt for human review, not a
  confirmed defect. See "Known limitations" below.

[SCORED] CG03 Physics-Plausibility Heuristic
  2 shot(s) flagged: frame-to-frame motion discontinuity above threshold
    action-discontinuity.mp4 @ frame 4-5 -- discontinuity 8.25x local baseline
    action-discontinuity.mp4 @ frame 5-6 -- discontinuity 8.32x local baseline
  This is a heuristic proxy, not a physics simulator. It flags shots for
  human review. It does not "detect" a physics violation.

Report written to ./continuityguard-report.json
Human-readable summary above. Use --json for the full structured report.
Scan time: 0.6s. Nothing left this machine. No network calls were made.

That full scan, decode plus both scoring passes plus report write, took between 0.6 and 1.4 seconds wall time across several runs on this machine. The two consistent-character pairs in the same fixture set score high and correctly go unflagged: mei_shot01.mp4 vs mei_shot02.mp4 at 0.9975 similarity, and aiko_shot01.mp4 vs aiko_shot02.mp4 at 0.9906. The deliberately inconsistent pair, kenji_shot01.mp4 vs kenji_shot02.mp4, scores 0.7709 and correctly gets flagged against the 0.88 threshold. On the physics side, calm-baseline.mp4 (smooth motion throughout) tops out at roughly 1.14x its own local baseline and stays unflagged, while action-discontinuity.mp4 (one deliberate abrupt jump) hits 8.25x and 8.32x and gets flagged against the 3x multiplier. Every one of these numbers came from the command above; the full raw diff values live in CHANGELOG.md.

Every flag carries a clip name, a numeric score, and a plain-language reason, so you or your QA reviewer can see exactly why a shot got flagged.

Quickstart

git clone https://github.com/RudrenduPaul/ContinuityGuard.git
cd ContinuityGuard
npm install
npm run build

# scan the fixture clips bundled with this repo
node dist/cli.js scan src/score/testdata/clips

# or point it at your own generated-clips folder
node dist/cli.js scan ./generated-clips/ --json > report.json

scan walks a target directory of video clips, decodes them locally via ffmpeg, computes per-shot character-consistency embeddings and a physics-plausibility heuristic, and writes a structured report in both human-readable and JSON form. Nothing it reads or computes ever leaves the machine it runs on.

CLI reference

Real, current --help output from the built CLI:

$ node dist/cli.js --help
Usage: continuityguard [options] [command]

Free, local-first CLI that scores already-generated AI short-drama clips/frames
for character-consistency and physics-plausibility problems. Zero network calls.

Options:
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  scan [options] <directory>  scan a directory of generated clips for
                              character-consistency and physics-plausibility
                              flags
  help [command]              display help for command

$ node dist/cli.js scan --help
Usage: continuityguard scan [options] <directory>

scan a directory of generated clips for character-consistency and
physics-plausibility flags

Arguments:
  directory     directory of video clips to scan

Options:
  --json        print the full machine-readable JSON report to stdout instead of
                a terminal summary
  --fps <fps>   frame sample rate for ingestion (default: 2.3)
  --out <path>  path to write the JSON report file to (default:
                "./continuityguard-report.json")
  -h, --help    display help for command

Naming your clips so CG02 can track characters

CG02 infers which character a clip belongs to from its filename, using a <character>_<shot-id>.<ext> convention (for example mei_shot01.mp4, mei_shot02.mp4). Clips sharing a character prefix are compared against that character's first-seen shot. There is no industry-standard character-tagging metadata format across AI short-drama pipelines, so v0.1 reads it from the filename instead of requiring a separate manifest. Clips that don't match the convention are still decoded and scored by CG03, just not compared for character consistency.

Known limitations (read before trusting a flag)

• Character-consistency scoring is best-validated on photorealistic content. v0.1 uses a generic ImageNet-pretrained visual-similarity embedding (MobileNetV2, see src/score/models/NOTICE.md for the reasoning behind that choice). Its accuracy on stylized or anime-adjacent character designs, which describes most short-drama content, is genuinely unverified going into v0.1. Treat a flag on stylized footage as a prompt to look closer before you trust it.
• The consistency embedding measures general visual similarity: color, texture, and coarse shape between crops. That's real signal on photorealistic faces, though weaker than a dedicated face-recognition embedding would give you. On stylized designs it's weaker still, and unvalidated.
• Physics-plausibility scoring is a frame-to-frame diff heuristic. It compares motion between consecutive frames against a shot's own local baseline and flags outliers for human review; it makes no attempt to simulate real-world physics. Expect both false positives (legitimate fast motion, stylized jump-cuts) and false negatives (subtly implausible motion that stays under the threshold).
• Thresholds are calibrated on a small, fully synthetic fixture set (solid-color clips, no real faces or recorded motion). See CHANGELOG.md for the exact numbers and the command that produced them. This is a real, reproducible starting point for v0.1, calibrated from two synthetic pairs rather than a large labeled dataset. Expect the numbers to move as real-world reports come in.
• The <character>_<shot-id> filename convention is a v0.1 simplification, built for a category that has no standard character-tagging metadata format yet. A clip that doesn't follow it still gets scored for physics; its consistency comparison is simply skipped.
• Requires a system ffmpeg install. ContinuityGuard checks for it at startup and prints the exact install command for your OS if it's missing (for example brew install ffmpeg on macOS, apt install ffmpeg on Debian/Ubuntu). It does not bundle a static ffmpeg binary in v0.1. A bundled per-platform build would be materially larger than this project's own dependency footprint and would inherit ffmpeg's own shifting LGPL/GPL licensing terms depending on which codecs are compiled in. Depending on a system install keeps this package small and its licensing surface simple.
• The TypeScript/npm package is not published to npm yet. Install from source (see "Install" above) until a registry release ships. The Python package, covering the same scoring logic and the same bundled model, is published (pip install continuityguard-cli) -- see python/README.md.

How it compares

There is no widely-used, directly comparable tool that combines local character-consistency scoring and a physics-plausibility heuristic in one zero-network CLI built specifically for reviewing already-generated AI short-drama output. The closest real, verified projects sit either one layer up (academic benchmarks for scoring video-generation models) or one layer down (general face-embedding libraries you'd have to wire up yourself):

| Project | Stars | Last activity | License | What it actually is | How it compares | |---|---|---|---|---|---| | Vchitect/VBench | 1,697 | Mar 2026 | Apache-2.0 | CVPR 2024 academic benchmark suite that scores video-generation models across 16 dimensions, including a DINOv2-based "subject consistency" metric and a motion-smoothness metric, aggregated across many generated clips | The closest mechanism match: it also scores subject consistency and motion quality on already-generated video. It's a GPU-dependent research benchmark for evaluating a generation model in aggregate, not a lightweight local CLI built to give one creator a per-clip QA report on their own footage. | | serengil/deepface | 23,113 | Jun 2026 | MIT | Widely used, actively maintained Python library for face verification, embeddings, and facial attribute analysis | A component library for face-embedding similarity, not a video-native or short-drama-specific tool. Useful as a building block, but ships no physics check, no clip decoding, and no packaged report format of its own. | | deepinsight/insightface | 29,263 | May 2026 | No single machine-readable LICENSE in the repo; project docs describe MIT-licensed code with non-commercial restrictions on some pretrained models | State-of-the-art 2D/3D face analysis toolbox (detection, recognition, alignment) | Same category as DeepFace: a component library, not an end-to-end QA CLI. No physics-plausibility check, no report layer. | | evalcrafter/EvalCrafter | 193 | Oct 2024 | None listed | CVPR 2024 research framework benchmarking video-generation models on visual quality, motion quality, and text-video alignment across 700 prompts | Adjacent research tool with no commits in roughly two years. Built to benchmark generation models with a heavy multi-metric research stack, not to give a fast local QA pass on a folder of already-generated clips. |

Star counts and last-activity dates above were pulled live from the GitHub API while writing this table.

What is ContinuityGuard, and why does it exist

ContinuityGuard is a free, open-source, local-first CLI. It ingests a directory of already-generated video clips from any AI short-drama pipeline, decodes them with ffmpeg, and runs two scoring passes: a character-consistency check (cosine similarity between MobileNetV2 embeddings of same-named-character crops across shots, best-validated on photorealistic content and unverified on stylized or anime-adjacent designs) and a physics-plausibility heuristic (frame-to-frame diff ratios against a shot's own local motion baseline, a heuristic that flags shots for human review rather than a physics simulator). It writes both a human-readable terminal report and a machine-readable JSON report, and it never makes a network call while doing any of it.

It exists because AI short-drama generation is shipping hundreds of new titles a day, and every one of those titles is assembled from many separately generated shots. Generation models drift: character faces shift slightly between cuts, and motion sometimes jumps in a way that reads as physically wrong the moment a human watches it. Catching that before a re-render saves the cost of redoing the shot from scratch.

ContinuityGuard is a QA layer, not a generator, and that is the point. It sits on top of whatever pipeline already produced your footage instead of locking you into one, it runs entirely on your own machine so unreleased footage never has to leave it, and it is free with no account or API key required. A generation platform's own built-in QA, if it has one, only ever sees its own output; ContinuityGuard works the same way whether your clips came from an open-source pipeline, a commercial one, or a mix of both on the same project.

Local-only, always

Your unreleased footage never leaves your machine. Every clip is decoded locally via ffmpeg, every embedding is computed locally via a bundled offline ONNX model, and the report is written to a local file. No account, no API key, no upload step, for any frame. npm run verify:zero-network proves this empirically: it monkey-patches every network entry point Node exposes and runs a real scan against this repo's own fixtures, and it would fail loudly if anything tried to reach the network. It runs in CI on every push. See CHANGELOG.md for the exact result.

FAQ

Is this validated for anime or stylized AI-generated characters? No. Character-consistency scoring is best-validated on photorealistic content. Its accuracy on stylized or anime-adjacent designs, which is most short-drama content, has not been independently benchmarked yet. Treat every flag on stylized footage as a prompt to look closer. This is the single most important caveat in this repo; see "Known limitations" above.

Does the physics check actually understand physics? No. It's a frame-to-frame motion-discontinuity heuristic. It compares each shot's frame-to-frame diffs against that shot's own local baseline and flags outliers for human review, with no attempt to model real-world physics. It will produce false positives on legitimate fast motion or stylized jump-cuts, and false negatives on subtle implausible motion that stays under the threshold.

Do I need a GPU? No. Everything runs on CPU via onnxruntime-node, using a small (14MB) MobileNetV2 model. The 8-clip fixture scan above completes in under two seconds on an ordinary laptop.

Does this upload my clips anywhere? No. That's mechanically enforced: npm run verify:zero-network patches every network entry point Node exposes and runs a real scan, and the check fails loudly if anything tries to reach the network. It runs on every CI push.

Why do I need to install ffmpeg separately instead of it being bundled? A bundled static ffmpeg binary would add tens of megabytes per platform to this package and would inherit ffmpeg's own licensing terms, which shift between LGPL and GPL depending on which codecs are compiled in. ffmpeg is close to ubiquitous on developer machines already, so v0.1 depends on a system install and checks for it at startup with a clear, OS-specific error if it's missing.

Is this on npm yet? Not yet. Install from source for now (see "Install" above). A registry release will happen later, once there's a specific date to commit to. The Python package is on PyPI today (pip install continuityguard-cli), using the same scoring logic and the same bundled model -- see python/README.md.

Will a big video-generation platform just build this into their product and make ContinuityGuard pointless? Possibly, and this repo says so plainly rather than hiding it: any well-funded video-generation platform could ship an equivalent check natively, since it already runs the full generation pipeline and has a direct incentive to prevent wasted render costs. ContinuityGuard's value is being free, local, and pipeline-agnostic today. Nothing here promises that stays true tomorrow.

Can I use this in CI? Yes. --json writes a machine-readable report an agent or CI step can parse, and the whole tool runs with zero network access, so it drops into a CI job the same way any other local static-analysis step would.

Contributing

See CONTRIBUTING.md for local setup for both the TypeScript package (repo root) and the Python package (python/), the full pre-PR checklist (lint, typecheck, coverage thresholds, npm audit, the zero-network verification script), and fixture-reproducibility rules. Reports of false positives or false negatives on real (not synthetic) AI short-drama footage, especially stylized or anime-adjacent content, are the single most useful contribution right now, since that's exactly the gap disclosed above.

Documentation

• docs/getting-started.md -- install paths for both packages, your first scan, the library API.
• docs/concepts.md -- what CG01-CG04 each do, and where the 0.88 / 3x thresholds came from.
• docs/integrations/ci.md -- wiring ContinuityGuard into a CI pipeline.
• python/README.md -- the Python package's own README (PyPI quickstart, CLI reference, fidelity notes).

License

Everything in this repo: Apache 2.0. Free forever, no paid tier in v0.1.