OGRAF HTML 动画OGRAF HTML 动画

ograf.json specification

The HTML animation package contract used by ograf.app and OGRAF Creator Skill: upload files, editable parameters, playback messages and exported manifests. Other OGRAF hosts may have different requirements.

Back to the development guide

Package layout

Place project.json and index.html at the ZIP root and reference assets with relative paths. The upload API also accepts one containing directory. Skill packages usually use .ograf; website downloads use .og.zip. Both are ZIP archives. A .ograf.json file alone cannot replace the two required upload entries.

title.ograf / title-a1b2c3d4.og.zip
├── project.json
├── index.html
├── zh.ograf.json
├── en.ograf.json
└── assets/  (optional)

project.json fields

format / formatVersionSkill baseline: "ograf" / 1.
name / description / versionName, description and version, such as 1.0.0. The Skill requires name.
resolution / fps / durationDesign resolution (1920x1080), frames per second and duration in seconds. Use positive values matching the animation.
supportsLandscape / supportsPortraitDeclare supported orientations and verify their visuals and controls.
dataCurrent parameter values, required by the Skill. Keys match schema.properties.
schemaA JSON Schema with root type object, required by the Skill. properties describes editable parameters.
renderRequirementsRecommended design dimensions, frame rate and accessToPublicInternet: false. Website resources must be self-contained.

This is the portable Skill baseline. The upload API currently requires a valid JSON object and scans package files; passing upload validation does not prove all metadata, playback or visuals are correct.

project.json for a simple title animation

{
  "format": "ograf",
  "formatVersion": 1,
  "name": "标题淡入",
  "description": "透明背景的标题淡入动画",
  "version": "1.0.0",
  "resolution": "1920x1080",
  "fps": 30,
  "duration": 3,
  "supportsLandscape": true,
  "supportsPortrait": false,
  "data": {
    "title": "你好,OGRAF",
    "color": "#ffffff",
    "fontSize": 96,
    "font": "sans-serif",
    "data": [],
    "x": 0,
    "y": 0,
    "scale": 1,
    "useOutro": true,
    "useIntro": true,
    "animationSpeed": 1
  },
  "schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "title": "标题",
        "default": "你好,OGRAF"
      },
      "color": {
        "type": "string",
        "title": "颜色",
        "format": "color",
        "default": "#ffffff"
      },
      "fontSize": {
        "type": "number",
        "title": "字号",
        "minimum": 24,
        "maximum": 200,
        "default": 96
      },
      "font": {
        "type": "string",
        "title": "字体",
        "gddType": "font",
        "default": "sans-serif"
      },
      "data": {
        "type": "array",
        "title": "数据",
        "items": {
          "type": "object"
        },
        "default": []
      },
      "x": {
        "type": "number",
        "title": "X",
        "default": 0
      },
      "y": {
        "type": "number",
        "title": "Y",
        "default": 0
      },
      "scale": {
        "type": "number",
        "title": "缩放",
        "minimum": 0.1,
        "maximum": 3,
        "multipleOf": 0.01,
        "default": 1
      },
      "useOutro": {
        "type": "boolean",
        "title": "是否使用出场动画",
        "default": true
      },
      "useIntro": {
        "type": "boolean",
        "title": "是否使用入场动画",
        "default": true
      },
      "animationSpeed": {
        "type": "number",
        "title": "动画速度",
        "minimum": 0.1,
        "default": 1
      }
    },
    "required": [
      "x",
      "y",
      "scale",
      "useOutro",
      "useIntro",
      "animationSpeed"
    ]
  },
  "renderRequirements": {
    "resolution": {
      "width": 1920,
      "height": 1080
    },
    "frameRate": 30,
    "accessToPublicInternet": false
  }
}

Editable parameter schema

Describe parameters with type, title and default; description is optional. Use minimum / maximum for numbers and enum for choices. data values must match their types and initially agree with defaults.

stringText input
string + format: colorColor input
string + gddType: multi-lineMultiline text
enumSelect
number / integerNumeric input with optional bounds
booleanToggle
array / objectJSON input in the Skill debugger; verify support in other hosts

Every animation must include these six controls in schema.properties and schema.required. Keep data, schema.default and field defaults aligned. The implementation must apply each control; disabling intro or outro immediately shows the corresponding state.

x / yX / Y; number, default 0, control position.
scaleScale; number, default 1 (original size), shown as a slider. minimum, maximum and multipleOf define bounds and step.
useOutroUse outro animation; boolean, default true.
useIntroUse intro animation; boolean, default true.
animationSpeedAnimation speed; number, default 1, strictly positive. Apply the multiplier to intro and outro playback.
Font: fontstring with gddType: font for font selection; hosts also recognize fontFamily. Store a font family name and let the host discover fonts on the current computer. Do not hardcode local font file paths.
Data: dataschema.properties.data is an editable array / object of structured JSON. It is distinct from top-level project.json data, which holds all parameter values. Store this field in data.data or schema.default.data.
Scale: scalenumber, with 1 representing original size. Use a numeric multiplier rather than a percentage string; transform stage content together with X and Y.

.ograf.json export manifest

HTML downloads preserve project.json, index.html and assets while saving current parameters. Provide Chinese and English manifests as zh.ograf.json and en.ograf.json. Both share parameter keys, types and behavior, with localized titles and copy. schema.properties describes controls, schema.default stores downloaded values and field defaults are synchronized. Its filename includes a random eight-character hexadecimal ID, such as title-a1b2c3d4.zh.ograf.json and title-a1b2c3d4.en.ograf.json, to reduce stale DaVinci cache reuse. Downloads keep the selected-language manifest; existing manifests without a language suffix remain a compatibility fallback.

{
  "name": "Title fade",
  "schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "title": "Title",
        "default": "Hello, OGRAF"
      },
      "color": {
        "type": "string",
        "title": "Color",
        "format": "color",
        "default": "#ffffff"
      },
      "fontSize": {
        "type": "number",
        "title": "Font size",
        "minimum": 24,
        "maximum": 200,
        "default": 96
      },
      "font": {
        "type": "string",
        "title": "Font",
        "gddType": "font",
        "default": "sans-serif"
      },
      "data": {
        "type": "array",
        "title": "Data",
        "items": {
          "type": "object"
        },
        "default": []
      },
      "x": {
        "type": "number",
        "title": "X",
        "default": 0
      },
      "y": {
        "type": "number",
        "title": "Y",
        "default": 0
      },
      "scale": {
        "type": "number",
        "title": "Scale",
        "minimum": 0.1,
        "maximum": 3,
        "multipleOf": 0.01,
        "default": 1
      },
      "useOutro": {
        "type": "boolean",
        "title": "Use outro animation",
        "default": true
      },
      "useIntro": {
        "type": "boolean",
        "title": "Use intro animation",
        "default": true
      },
      "animationSpeed": {
        "type": "number",
        "title": "Animation speed",
        "minimum": 0.1,
        "default": 1
      }
    },
    "required": [
      "x",
      "y",
      "scale",
      "useOutro",
      "useIntro",
      "animationSpeed"
    ],
    "default": {
      "title": "Hello, OGRAF",
      "color": "#ffffff",
      "fontSize": 96,
      "font": "sans-serif",
      "data": [],
      "x": 0,
      "y": 0,
      "scale": 1,
      "useOutro": true,
      "useIntro": true,
      "animationSpeed": 1
    }
  }
}

This example is the website HTML configuration manifest, not a complete entry specification for every desktop OGRAF host. Existing desktop archives may require main and other fields; preserve their original entry points.

HTML playback protocol

For DaVinci, main.js exports an HTMLElement subclass and the native .ograf.json points main to it. Mount the visible stage directly on document.body. Canvas dimensions come first from load({renderCharacteristics}).resolution.width/height, ahead of host-box or viewport dimensions. A requested 1080×1920 portrait canvas must not fit into a stale 1920×1080 host box. Scale previews only when host and canvas aspect ratios match. Clean up the stage, listeners and animation work on disposal. Website index.html reuses that implementation inside sandbox="allow-scripts" with window.postMessage, without parent.document or allow-same-origin.

Host → graphicograf:updatedata contains parameters. Update without reloading or automatically replaying.
Host → graphicograf:startStart from a known initial frame; repeated starts replay.
Host → graphicograf:stopCancel timers and animation work; return to a consistent resting state.
Graphic → hostograf:readyNotify after the DOM, assets and listeners are ready.
Graphic → hostograf:endedNotify when a non-looping animation reaches its final frame.
Graphic → hostograf:errorProvide a readable diagnostic in error.
// Host → graphic
{ type: 'ograf:update', data: { title: 'Hello, OGRAF' } }
{ type: 'ograf:start' }
{ type: 'ograf:stop' }

// Graphic → host
parent.postMessage({ type: 'ograf:ready' }, '*');
parent.postMessage({ type: 'ograf:ended' }, '*');
parent.postMessage({ type: 'ograf:error', error: 'Playback failed' }, '*');

Use parent.postMessage(message, "*") for opaque-origin frames. The graphic validates event.source === parent; the host validates the target iframe.contentWindow. Updates are idempotent; stopping or replaying clears old work. Render user text with textContent.

Resources and upload limits

Compressed ZIP≤ 500 KiB
Individual JS / MJS≤ 500 KiB; inline HTML scripts are also scanned
Individual image≤ 1 MiB
File count≤ 200
Total uncompressed size≤ 2 MiB
VideoForbidden, including files disguised with another extension

Allowed: HTML, JS/MJS, CSS, JSON, PNG/JPEG/GIF/WebP/SVG/AVIF, WOFF/WOFF2/TTF/OTF and TXT/MD. Scripts, styles, fonts and images use local relative paths. External resources, network requests, dynamic code execution and sensitive APIs such as cookies or storage are rejected. No traversal, absolute paths, duplicate entries, symlinks or corrupt ZIP files. The server scans actual decompressed contents; static scanning is not a complete security guarantee. 1 KiB = 1024 bytes.

Before publication

  1. Validate locally and include both entries with complete relative assets.
  2. Inspect real previews and immediate title, color and font-size updates.
  3. Check playback, stop, consecutive replay and completion messages without stale work.
  4. Verify transparency, design resolution and declared orientations.
  5. Upload a draft through the Skill, publish it, then verify the public preview and downloaded package.