I want a review list before deciding what to remake. The hero image may need attention; its vertical crop and the assembled cut may need it too. A separately recorded voice track can remain outside that chain.

A small dependency graph is enough to record this. This example uses local JSON files and Python's standard library.

Record the parents of each asset

Save this as old.json:

{
  "product_ref": {"rev": "r1", "deps": []},
  "hero": {"rev": "r1", "deps": ["product_ref"]},
  "vertical": {"rev": "r1", "deps": ["hero"]},
  "voice": {"rev": "r1", "deps": []},
  "cut": {"rev": "r1", "deps": ["vertical", "voice"]}
}

deps lists inputs, not outputs. The hero uses the product reference; the vertical image uses the hero. Each changed file or meaningful source decision gets a new revision ID.

Save the checker as asset_review.py. It needs Python 3.9 or later:

import argparse
from collections import defaultdict
from graphlib import CycleError, TopologicalSorter
import json
from pathlib import Path


def validate(data):
    if not isinstance(data, dict):
        raise ValueError("manifest must be an object keyed by asset ID")
    graph = {}
    for name, node in data.items():
        if not isinstance(name, str) or not name.strip() or not isinstance(node, dict):
            raise ValueError("each asset needs an ID and an object")
        revision, parents = node.get("rev"), node.get("deps")
        if not isinstance(revision, str) or not revision.strip():
            raise ValueError(f"{name}: rev must be a nonempty string")
        if not isinstance(parents, list) or not all(isinstance(p, str) for p in parents):
            raise ValueError(f"{name}: deps must be a list of IDs")
        if len(set(parents)) != len(parents):
            raise ValueError(f"{name}: duplicate dependency")
        missing = set(parents) - data.keys()
        if missing:
            raise ValueError(f"{name}: missing dependencies {sorted(missing)}")
        graph[name] = {"rev": revision, "deps": sorted(parents)}
    try:
        tuple(TopologicalSorter({n: v["deps"] for n, v in graph.items()}).static_order())
    except CycleError as error:
        raise ValueError(f"dependency cycle: {error.args[1]}") from error
    return graph


def compare(old, new):
    old, new = validate(old), validate(new)
    changed = {name for name in old.keys() | new.keys()
               if old.get(name) != new.get(name)}
    children = defaultdict(set)
    for graph in (old, new):
        for child, node in graph.items():
            for parent in node["deps"]:
                children[parent].add(child)
    affected, pending = set(changed), list(changed)
    while pending:
        for child in children[pending.pop()]:
            if child not in affected:
                affected.add(child)
                pending.append(child)
    return {
        "changed": sorted(changed),
        "review": sorted((affected - changed) & new.keys()),
        "removed": sorted(old.keys() - new.keys()),
    }


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("old")
    parser.add_argument("new")
    args = parser.parse_args()
    try:
        before = json.loads(Path(args.old).read_text(encoding="utf-8"))
        after = json.loads(Path(args.new).read_text(encoding="utf-8"))
        result = compare(before, after)
    except (OSError, ValueError) as error:
        parser.exit(2, f"error: {error}\n")
    print(json.dumps(result, indent=2))

Change one reference

Make a new manifest with only the reference revision changed:

import json
from pathlib import Path

data = json.loads(Path("old.json").read_text())
data["product_ref"]["rev"] = "r2"
Path("new.json").write_text(json.dumps(data, indent=2))

Run:

python asset_review.py old.json new.json

Output:

{
  "changed": ["product_ref"],
  "review": ["cut", "hero", "vertical"],
  "removed": []
}

The voice track is untouched. The cut appears because one of its visual inputs is downstream of the changed reference.

This is the bookkeeping side of reference ownership and asset lineage. Astorie's workflow discussion covers the wider production decisions; the graph gives a local project a way to query its recorded relationships.

Review does not mean regenerate

Suppose the reference update corrects a seam on the back of a product. The hero might show only its front. I still want the hero on the review list, because someone needs to check whether that correction is visible in this asset. Keeping a valid take is a legitimate outcome of the review.

The checker follows edges from both manifests. Removing an old dependency should not erase the history needed to assess that change. A revision change, an added or removed asset, or a changed dependency list counts as a direct change. Sorting dependencies avoids treating a reordered list as a new relationship.

Missing IDs and cycles stop the comparison. Those errors make the review list unreliable. An intentionally cyclic production process needs versioned snapshots or separate iteration records before it can fit this DAG model.

The local checks covered direct and indirect descendants, an unrelated branch, removed edges, deleted nodes, and invalid graphs. The remaining discipline is recording revisions: replacing a file without updating its revision is invisible to this checker. A file hash can serve as the revision when byte-level changes are the right trigger.

Reference: Python graphlib documentation.

I put the expected properties in a small JSON manifest and compare them with ffprobe output.

Write down what the package should contain

Save this as handoff.json at the root of the media package:

[
  {
    "file": "picture/hero.mp4",
    "width": 1280,
    "height": 720,
    "audio": false
  },
  {
    "file": "audio/narration.wav",
    "audio": true
  }
]

Paths are relative to that JSON file. Here, I expect a 1280 x 720 picture file without an audio stream, plus a separate narration file with audio. Omitting a property means it won't be checked.

Astorie's guide to what belongs in an NLE handoff package covers the broader brief, captions, and asset-history decisions. I keep these file checks alongside those editorial notes.

Compare the manifest with the files

This script uses Python's standard library. Install FFmpeg first and confirm that ffprobe -version works in your terminal.

Save the script as check_handoff.py:

import json
import shutil
import subprocess
import sys
from pathlib import Path


def validate(manifest_path):
    entries = json.loads(manifest_path.read_text(encoding="utf-8"))
    errors = []

    for item in entries:
        label = item["file"]
        path = (manifest_path.parent / label).resolve()
        if not path.is_file():
            errors.append(f"{label}: missing")
            continue

        try:
            result = subprocess.run(
                [
                    "ffprobe", "-v", "error",
                    "-show_entries", "stream=codec_type,width,height",
                    "-of", "json", "-i", str(path),
                ],
                check=True, capture_output=True, text=True, timeout=20,
            )
        except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
            errors.append(f"{label}: probe failed")
            continue

        streams = json.loads(result.stdout).get("streams", [])
        video = next(
            (s for s in streams if s.get("codec_type") == "video"), {}
        )
        for key in ("width", "height"):
            if key in item and video.get(key) != item[key]:
                errors.append(
                    f"{label}: {key} expected {item[key]}, got {video.get(key)}"
                )

        has_audio = any(s.get("codec_type") == "audio" for s in streams)
        if "audio" in item and has_audio != item["audio"]:
            errors.append(
                f"{label}: audio expected {item['audio']}, got {has_audio}"
            )

    print("\n".join(errors) if errors else f"PASS: {len(entries)} files match manifest")
    return 1 if errors else 0


if __name__ == "__main__":
    if len(sys.argv) != 2:
        raise SystemExit("Usage: python check_handoff.py handoff.json")
    if shutil.which("ffprobe") is None:
        raise SystemExit("Install FFmpeg and put ffprobe on PATH.")
    raise SystemExit(validate(Path(sys.argv[1]).resolve()))

Run it with the path to the manifest:

python check_handoff.py handoff.json

For a matching package:

PASS: 2 files match manifest

If I change the expected width to 1920 while the file remains 1280 pixels wide, the report becomes:

picture/hero.mp4: width expected 1920, got 1280

A missing narration file produces its own message:

audio/narration.wav: missing

The script continues through the list and exits with status 1 if anything fails. That makes the same check usable in a terminal or a build step.

I resolve file paths against the manifest's location so moving the whole package doesn't require rewriting the list. Width and height refer to the stored video dimensions. The audio check only detects a stream; listening to the narration is still a separate review task.

The filenames alone cannot settle which asset belongs in the cut. Someone has to reconstruct the decision from messages and folders.

A small validator can catch these contradictions before the package leaves the creator's machine. This walkthrough builds one in Python, using an explicit shot manifest and ordinary local files.

The format is an independent handoff example. It does not call an Astorie API or depend on a platform export.

Describe the selected asset, not every generation attempt

Keep one selected asset per shot in the handoff manifest. Put rejected candidates in a separate archive. This makes a repeated shot ID an error instead of an invitation for the editor to choose a take.

The example has three parts:

• schema_version identifies the format the validator understands.
• references records the accepted reference versions for this package.
• shots connects each selected asset to its version, approval, and reference versions.

Save this as package/manifest.json:

{
  "schema_version": 1,
  "references": {
    "PRODUCT": 2
  },
  "shots": [
    {
      "shot_id": "S010",
      "version": 2,
      "asset": "picture/S010_v02.txt",
      "approval": {
        "status": "approved",
        "version": 2
      },
      "references": {
        "PRODUCT": 2
      }
    }
  ]
}

The .txt asset is deliberately a test fixture. It lets you run the path checks without generating or downloading media. In a real handoff, use the path to the reviewed image or video.

Create that fixture from the directory containing your script:

from pathlib import Path

picture = Path("package/picture")
picture.mkdir(parents=True, exist_ok=True)
(picture / "S010_v02.txt").write_text("Path-check fixture only.\n", encoding="utf-8")

Turn approval into a checkable relationship

A status of approved is insufficient when the asset has changed since review. Store the approved version separately and compare it with the selected shot version.

Here, shot version 2 requires an approval for version 2. Changing the shot to version 3 leaves a visible mismatch until the review record is updated.

References need a similar comparison. A shot using PRODUCT: 1 fails when the package catalog specifies PRODUCT: 2. An unknown reference ID also fails. The catalog is maintained by the team; the script cannot independently discover the latest approved reference.

For the wider production context, Astorie's AI video production pipeline discusses how shot selection connects to the editing handoff. The validator below adds a local check for the metadata you send with those assets.

Run the validator

Use Python 3.9 or later. No third-party packages are needed. Save the following as validate_manifest.py:

import argparse
import json
from pathlib import Path, PurePosixPath


def positive_int(value):
    return type(value) is int and value > 0


def validate(data, root):
    errors = []
    root = Path(root).resolve()
    if not isinstance(data, dict):
        return ["manifest must be an object"]
    if type(data.get("schema_version")) is not int or data["schema_version"] != 1:
        errors.append("schema_version must be 1")
    catalog = data.get("references")
    if not isinstance(catalog, dict) or not catalog or any(
        not key.strip() or not positive_int(version)
        for key, version in catalog.items()
    ):
        errors.append("references catalog requires IDs and positive integer versions")
        catalog = {}
    shots = data.get("shots")
    if not isinstance(shots, list) or not shots:
        return errors + ["shots must be a non-empty array"]
    seen = set()
    for index, shot in enumerate(shots):
        label = f"shots[{index}]"
        if not isinstance(shot, dict):
            errors.append(f"{label}: must be an object")
            continue
        shot_id = shot.get("shot_id")
        if not isinstance(shot_id, str) or not shot_id.strip():
            errors.append(f"{label}: shot_id must be a non-empty string")
        elif shot_id in seen:
            errors.append(f"{label}: duplicate shot_id {shot_id}")
        else:
            seen.add(shot_id)
        version = shot.get("version")
        if not positive_int(version):
            errors.append(f"{label}: version must be a positive integer")
        approval = shot.get("approval")
        if not isinstance(approval, dict) or (
            approval.get("status") != "approved"
            or not positive_int(approval.get("version"))
            or approval.get("version") != version
        ):
            errors.append(f"{label}: approval must be approved for version {version}")
        refs = shot.get("references")
        if not isinstance(refs, dict) or not refs:
            errors.append(f"{label}: references must be a non-empty object")
        else:
            for ref_id, ref_version in refs.items():
                if ref_id not in catalog:
                    errors.append(f"{label}: unknown reference {ref_id}")
                elif not positive_int(ref_version) or ref_version != catalog[ref_id]:
                    errors.append(
                        f"{label}: reference {ref_id} must use version {catalog[ref_id]}"
                    )
        asset = shot.get("asset")
        if not isinstance(asset, str) or not asset.strip():
            errors.append(f"{label}: asset must be a non-empty string")
            continue
        if "\\" in asset or ":" in asset or PurePosixPath(asset).is_absolute():
            errors.append(f"{label}: asset must be a relative path using forward slashes")
            continue
        try:
            target = (root / asset).resolve()
            if not target.is_relative_to(root):
                errors.append(f"{label}: asset escapes package root")
            elif not target.is_file():
                errors.append(f"{label}: missing file {asset}")
        except (OSError, RuntimeError, ValueError):
            errors.append(f"{label}: cannot resolve asset path")
    return errors


def main():
    parser = argparse.ArgumentParser(description="Check shot metadata and local paths.")
    parser.add_argument("manifest", type=Path)
    args = parser.parse_args()
    try:
        data = json.loads(args.manifest.read_text(encoding="utf-8"))
        errors = validate(data, args.manifest.parent)
    except (OSError, UnicodeError, ValueError, RuntimeError) as exc:
        print(f"ERROR: {exc}")
        return 2
    if errors:
        for error in errors:
            print(f"ERROR: {error}")
        return 1
    print(f"OK: {len(data['shots'])} shot record(s) passed.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Run it from your project directory:

python validate_manifest.py package/manifest.json

The supplied fixture produces:

OK: 1 shot record(s) passed.

The program returns exit code 0. Validation errors return 1. An unreadable manifest or malformed JSON returns 2, so a packaging script can stop when either occurs.

The validator collects problems across shot entries instead of stopping at the first rejected take. It also checks types before comparing values. In particular, type(value) is int prevents JSON true from passing as version 1 through Python's boolean-integer relationship.

Asset paths are resolved relative to the manifest's directory. Resolving before checking containment lets the script reject a path or symbolic link that points outside the package. Existing files inside the package pass the path check, regardless of their media content.

Break the example before trusting it

Create a failure case with an old reference, a repeated shot ID, a newer unapproved version, a missing reference set, and a missing file:

import copy
import json
from pathlib import Path

path = Path("package/manifest.json")
data = json.loads(path.read_text(encoding="utf-8"))
second = copy.deepcopy(data["shots"][0])
data["shots"][0]["references"]["PRODUCT"] = 1
second.update(version=3, references={}, asset="picture/missing.txt")
data["shots"].append(second)
Path("package/manifest.bad.json").write_text(
    json.dumps(data, indent=2), encoding="utf-8"
)

Then run:

python validate_manifest.py package/manifest.bad.json

Actual output from the supplied failure case:

ERROR: shots[0]: reference PRODUCT must use version 2
ERROR: shots[1]: duplicate shot_id S010
ERROR: shots[1]: approval must be approved for version 3
ERROR: shots[1]: references must be a non-empty object
ERROR: shots[1]: missing file picture/missing.txt

This case returns exit code 1. Fixing the duplicate ID alone still leaves the other problems unresolved.

Do not fix the approval error by copying the new version number into the approval record automatically. That would make the fields agree while skipping the review the fields are meant to record.

Put the check at the packaging boundary

Run the validator after selecting assets and before sending the folder to the editor. Re-run it if someone changes the selected files, references, or approval records.

A passing result means the declared relationships and local paths meet these rules. It does not prove that a person approved the asset, that its bytes have remained unchanged, or that the picture and sound work in sequence. Those require a trusted review record, integrity checks where needed, and media review.

The useful boundary is narrow: the editor gets a package with consistent shot metadata and resolvable asset paths. Creative approval stays with the people responsible for the work.