hyperframes/docs/schema/hyperframes.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hyperframes.heygen.com/schema/hyperframes.json",
  "title": "Hyperframes Project Config",
  "description": "Per-project configuration for a Hyperframes project (hyperframes.json). Tells `hyperframes add` which registry to pull items from and where to drop them in the project tree. Created by `hyperframes init`; users may edit it to point at custom registries or reshape their project layout.",
  "type": "object",
  "required": ["registry", "paths"],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "description": "JSON Schema URL — https://hyperframes.heygen.com/schema/hyperframes.json."
    },
    "registry": {
      "type": "string",
      "format": "uri",
      "minLength": 1,
      "description": "Base URL of the registry to pull items from. Point at the official Hyperframes registry or a custom one."
    },
    "paths": {
      "type": "object",
      "description": "Target paths for each item type, relative to the project root.",
      "required": ["blocks", "components", "assets"],
      "additionalProperties": false,
      "properties": {
        "blocks": {
          "type": "string",
          "minLength": 1,
          "description": "Where `hyperframes:block` items land. Defaults to `compositions`."
        },
        "components": {
          "type": "string",
          "minLength": 1,
          "description": "Where `hyperframes:component` items land. Defaults to `compositions/components`."
        },
        "assets": {
          "type": "string",
          "minLength": 1,
          "description": "Where asset files (images, fonts, videos) land. Defaults to `assets`."
        }
      }
    },
    "media": {
      "type": "object",
      "description": "Media handling options.",
      "additionalProperties": false,
      "properties": {
        "autoProxy": {
          "type": "boolean",
          "description": "Automatically create H.264 proxies for browser-hostile video codecs on supported preview surfaces. Defaults to true."
        }
      }
    },
    "render": {
      "type": "object",
      "description": "Default `hyperframes render` options for this project. An explicit CLI flag always wins.",
      "additionalProperties": false,
      "properties": {
        "motionBlur": {
          "type": "object",
          "description": "Opt into sub-frame multi-sample motion blur for every render of this project. Absent means off and the capture path is unchanged. The exporter writes this from the comp's own After Effects shutter settings. Forces PNG frame capture and screenshot capture; rejected on the HDR layered capture route.",
          "additionalProperties": false,
          "properties": {
            "samplesPerFrame": {
              "type": "integer",
              "minimum": 1,
              "maximum": 64,
              "description": "Sub-frame captures averaged into one output frame. Default 16, adaptive per frame when omitted."
            },
            "shutterAngle": {
              "type": "number",
              "description": "Shutter window width in degrees of one frame. Default 180, After Effects' own default."
            },
            "shutterPhase": {
              "type": "number",
              "description": "Window offset in degrees. Default -90, which centres the window on the frame time."
            },
            "blend": {
              "type": "string",
              "enum": ["srgb", "linear"],
              "description": "Working space for the average. Default \"srgb\", matching After Effects' non-linearised work space."
            }
          }
        }
      }
    },
    "authoringSkill": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
      "description": "Owning authoring-workflow skill slug (e.g. product-launch-video). Set by `hyperframes init --skill` or seeded from the first `hyperframes render --skill`; every render of this project is then attributed to it on anonymous telemetry, without re-passing the flag."
    },
    "registryItems": {
      "type": "array",
      "description": "Catalog items installed by `hyperframes add`, in install order. Installed files are plain composition HTML with no provenance marker, so this is the only record that a file came from the registry; a render reads it back to report which catalog items the finished video actually used. Append-only, deduped by name.",
      "items": {
        "type": "object",
        "required": ["name", "type", "target"],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "Registry item name, e.g. data-chart."
          },
          "type": {
            "type": "string",
            "description": "Registry item type, e.g. hyperframes:block."
          },
          "target": {
            "type": "string",
            "description": "Primary installed file, relative to the project root."
          }
        }
      }
    }
  }
}