dioramic

dioramic for Hermes

Describe a scene in chat, and Hermes renders a vertical 3D clip in Blender.

I make 3D Blender-style videos for TikTok. Blocking out each scene by hand is the slow part. With dioramic, you describe the scene in a Hermes chat, the agent fills in a structured spec, and headless Blender renders a 9:16 clip ready for TikTok, Reels or Shorts. Then you say "make the cube blue" and it renders a new version. The model never writes Blender code.

Install · Quick start · Tools · Scene spec · How it works · Safety · Tests

Install

Needs Hermes Agent 0.23 or newer, and Blender 4.2 or newer (tested with 4.2.3 LTS, CPU only, no GPU).

hermes plugins install faze39/dioramic --enable
hermes config set plugins.entries.dioramic.settings.blender_path /path/to/blender

If blender is already on your PATH, or you have BLENDER_BIN set, you can skip the config line. The GitHub URL also works: hermes plugins install https://github.com/faze39/dioramic --enable.

Quick start

In any Hermes chat (CLI, Telegram, Discord, Slack), type:

make a 4 second clip of a coral cube bouncing on a cream plinth, slow orbit

You do not write any JSON. Hermes turns that sentence into a scene spec and calls dioramic_render. When the render finishes, the reply includes the video and a still preview, delivered as MEDIA: tags so the gateway shows them in the chat.

Then iterate:

make the cube blue

Hermes calls dioramic_tweak with only the changes. The first version is kept. The new one is saved as a new scene id ending in -v2.

To check layout before waiting on a full clip, ask for a still first ("just a preview of that scene"). Hermes will set preview_only to true, which takes a few seconds once shaders are warm instead of several minutes.

What you get back

The tool returns JSON to the agent, and the media to you:

If the spec is invalid, the tool does not render. It returns {"error": "scene spec has problems", "problems": [...]} so the agent can fix the fields and try again.

Where the files land

Everything is written under your Hermes home, which is $HERMES_HOME if set, otherwise ~/.hermes:

~/.hermes/plugin-data/dioramic/scenes/<scene_id>/
  spec.json      the validated spec used for this render
  clip.mp4       the vertical H.264 clip (skipped when preview_only)
  preview.png    a still frame
  render.log     Blender's stdout

Scene ids are generated by the plugin from the title and a timestamp, for example coral-bounce-1111-1927. A tweak of that scene becomes coral-bounce-1111-1927-v2, then -v3, and so on. The agent cannot choose the path.

The two tools

dioramic_render

dioramic_tweak

How changes is applied:

• Top-level fields (background, lighting, duration, and so on) overwrite the previous values.
• camera is merged field by field, so {"camera": {"speed": 0.5}} keeps the old move and distance.
• objects are matched by id. A known id is updated in place. An unknown id is added.
• remove_objects is a list of ids to drop.

Example: make the cube blue and the camera slower:

{"scene_id": "coral-bounce-1111-1927", "changes": {"objects": [{"id": "hero", "color": "blue"}], "camera": {"speed": 0.5}}}

Scene spec

The model never sends Blender Python. It sends JSON. Coordinates are in metres, Z is up, the floor is at z=0, and a range of about -4 to 4 fits a vertical frame. Base shapes are 2 m across, then scaled.

Scene fields

Shapes

Object fields

Finishes

Colours

Use a name from this palette, or any #rrggbb hex:

Lighting

Three-light area rigs:

Camera

Animations

Every animation has type, plus optional start and end in seconds (default: the whole clip). Extra fields depend on the type:

Limits

Out-of-range numbers are clamped and listed in warnings. Unknown shapes, colours, finishes, moves or animation types come back as problems and the render is not started.

JSON example

A 4 second clip that matches the prompt above. Fuller scenes, including the desk and the neon title card, are in examples/.

{
  "title": "coral bounce",
  "duration": 4,
  "background": "peach",
  "lighting": "soft",
  "camera": {"move": "orbit", "speed": 0.7, "distance": 14, "height": 4, "target": [0, 0, 1.1]},
  "objects": [
    {
      "id": "plinth",
      "shape": "cylinder",
      "color": "cream",
      "finish": "matte",
      "position": [0, 0, 0.25],
      "scale": [3.2, 3.2, 0.25]
    },
    {
      "id": "hero",
      "shape": "cube",
      "color": "coral",
      "position": [0, 0, 1.4],
      "scale": 0.9,
      "animate": [{"type": "bounce", "height": 1.2, "count": 2}]
    }
  ]
}

Sample scenes

Config

Set these with hermes config set plugins.entries.dioramic.settings.<name> <value>.

How it works

flowchart LR
  A[Agent] --> B[JSON spec]
  B --> C[Validator]
  C --> D[Fixed build script]
  D --> E[Headless Blender]
  E --> F[MP4 and PNG]
  F --> G[MEDIA tags]

1. You describe the scene in chat. Hermes writes a JSON spec and calls dioramic_render or dioramic_tweak. It does not write Blender Python.
2. The validator (spec.py) checks every field against fixed enums and numeric limits, and returns a normalised copy. Bad values are listed as problems. Out-of-range numbers are clamped with a warning.
3. A fixed build script (blender_build.py, part of this repo) is the only Python Blender runs. The plugin writes the validated spec to spec.json in a plugin-owned folder and starts Blender headless. The script reads that JSON as data. Strings from the spec are used only as object names and as the body of 3D text.
4. Headless Blender (EEVEE Next, AgX colour) builds a studio sweep, the lights, the objects and the camera, then writes preview.png and, unless this is a preview-only run, clip.mp4.
5. The tool result includes MEDIA: tags for those files, so the Hermes gateway shows the still and the clip in the chat.

The same pipeline is what dioramic_tweak runs, after spec.merge has applied the changes to the previous spec.json.

Safety

• No code path from the model to Blender. blender_build.py is a fixed script that reads the validated spec as JSON data. Text is only ever a 3D text body.
• Every field is checked against enums and numeric limits in spec.py. Bad values come back as a list of problems. Out-of-range numbers are clamped with a warning.
• No model-chosen paths. Output goes to <hermes home>/plugin-data/dioramic/scenes/<scene_id>/. Scene ids are generated by the plugin and checked against a strict pattern before use.
• Clean subprocess environment. Blender gets only PATH, locale and display variables, with HOME set to the scene folder. API keys in the agent's environment are not passed on.
• Bounded renders. Duration, samples and resolution are capped by settings you control, and the render is killed after render_timeout.
• No network. The plugin makes no network calls. It uses only public plugin seams: register_tool, get_config, plugin_data_dir.

Performance

Renders use EEVEE, but they are still slow without a graphics card. On an 8-core CPU box with no GPU, a frame at 540x960 takes about 2 to 4 seconds, so a 3.5 second clip at 24 fps takes about 3 to 5 minutes. A still preview takes a few seconds once shaders are warm. A GPU machine is much faster. 1080x1920 (when allow_hd is on) is slower still. If a render hits render_timeout, shorten the duration or lower the sample count.

Tests

pip install pytest
BLENDER_BIN=/path/to/blender pytest -q tests
# unit tests, plus a real Blender still render when Blender is available

DIORAMIC_E2E=1 BLENDER_BIN=/path/to/blender pytest -q tests/test_hermes_e2e.py
# a real Hermes chat loop: render a scene, then tweak it, writing two clips

Demo note

The end-to-end test and the hackathon demo video use demo/scripted_model.py, a small local OpenAI-compatible endpoint that plays a fixed script, because the build machine has no model API key. The tool calls, the Hermes loop and the Blender renders are all real. Only the model's choice of what to call is scripted. The demo video says this on screen.

License

MIT. See LICENSE.

README from the reviewed commit 7265dd1; it updates when the author re-pins.