chapterscript

Open format · Open runtime

Spatial stories, as a readable file.

ChapterScript is an open JSON format for immersive, interactive spatial experiences. ChapterPlayer is the Swift runtime that plays them on Apple Vision Pro.

Read the format Get the player

One bundle. Everything the story needs.

A .chapterscript document is a directory bundle: a single chapter.json next to an assets/ folder. Every asset is manifested with its byte size and SHA-256, so a player knows exactly what it has and exactly what changed.

chapter.json 
{
  "formatVersion": 3,                    // migrated forward on open
  "id": "the-lighthouse",
  "displayName": "The Lighthouse",
  "defaultSequenceId": "arrival",        // where playback begins
  "sequences": [
    {
      "id": "arrival",
      "presentation": "immersive",       // full surround
      "immersiveBackdrop": {
        "kind": "video",
        "file": "shore_360.mov",          // from assets/, by manifest
        "field": "equirect360",
        "loop": true
      },
      "steps": [
        {
          "duration": 8,                  // seconds, then advance…
          "gate": { "type": "tap" },      // …but hold for a tap first
          "actions": [
            { "kind": "revealEntity",
              "reveal": { "entity": "lantern", "fadeIn": 1.5 } }
          ]
        }
      ],
      "animationTracks": [
        {
          "entity": "lantern",             // bézier-eased keyframes,
          "rotateOrder": "xyz",            // continuous Euler degrees
          "channels": {
            "ty": [
              { "t": 0.0, "v": 0.0, "interp": "bezier",
                "outTangent": { "dt": 0.4, "dv": 0.0 } },
              { "t": 4.0, "v": 1.2, "interp": "bezier" }
            ]
          }
        }
      ]
    }
  ]
}

The document model

Four nouns, one hierarchy. If you can read the JSON above, you already know all of them.

chapter

The whole document. One chapter.json, one story, one bundle.

sequences

Timed scenes. Each has a presentation mode and an optional backdrop.

steps

Timed beats. Optionally held by gates: tap, gaze, approach, grab, with an optional timeout and prompt.

actions

Reveals, moves, video, audio, particles and more, fired as a step plays.

Format guarantees

The format is designed to be operated on by tools, tracked by version control, and trusted by players.

Clean diffs

Saves are deterministic: sorted keys, pretty-printed. The same document always serializes the same way, so version control shows you what actually changed.

SHA-256 asset manifest

Every asset ships with its byte size and content hash. Players cache aggressively and never show a stale frame.

Forward-compatible

Older documents migrate on open. Decoding is tolerant: fields a reader does not recognize are carried, not crashed on.

Readable and generatable

It is JSON you can actually read. Write chapters from scripts, pipelines, or by hand.

ChapterPlayer

The open source visionOS runtime for .chapterscript bundles, published as a Swift package you can embed in your own visionOS app.

  • Plays .chapterscript bundles end to end
  • Drives the step loop, gates and action executors
  • Immersive and panel video playback
  • Spatial audio
  • USDZ assets as placeable entities and full backdrop scenes
  • Bézier motion evaluation identical to the authoring tools
  • Embeddable in your own visionOS app

The format is tool-agnostic: any document that decodes as valid ChapterScript, ChapterPlayer can play.

The full reference

Everything you need to read, write, or play the format, documented here.

Format reference →

The chapter.json schema: sequences, steps, gates, the action catalog, animation tracks and the asset manifest.

Embedding ChapterPlayer →

Install the runtime, load content, wire your scenes, and go live against an authoring tool.

Born on a real production.

ChapterScript wasn't designed on a whiteboard. It was built out of necessity for Shared Visions, an immersive documentary for Apple Vision Pro, actively in development on this exact stack.

Shared Visions is a full-length film, not a demo: dozens of scenes, hundreds of timed beats, narration, 360° footage, spatial video, immersive video, spatial audio, and moments that might wait for the audience to look, reach, or step closer. The team making it looks like a film crew, because it is one: a director, editors, producers, or even just experimenters. Not a room full of Swift developers.

Building that as a hand-coded Xcode project was never going to survive contact with production. Every timing note ("hold that shot a beat longer", "bring the narration in after the lantern appears") became a code change, a build, and a deploy before anyone could feel it in the headset. And Reality Composer Pro is not a tool for directing a long-form gated narrative.

So the story itself moved out of the code and into data. The documentary became a .chapterscript bundle a director can shape and version; the app became ChapterPlayer, a runtime that performs whatever the document says.

Editors notes stopped being
engineering tickets.

That split is the whole idea, and it is why both halves are open source: the next production with more storytellers than developers shouldn't have to build this from scratch.

Two repositories

The spec and the runtime, developed in the open.

mike-bundy/ChapterScript

The format specification and JSON schema, plus example bundles. Start here if you are writing a tool that reads or emits ChapterScript.

View on GitHub

mike-bundy/ChapterPlayer

The Swift package: the visionOS runtime that plays bundles, with the step loop, gates, executors, video, audio and motion evaluation.

View on GitHub

Early days, on purpose.

ChapterScript is pre-1.0, in production use, and still moving.

The format you see today will likely change shape before it settles. Names, fields, and even structure are still earning their place on a real production, and we would rather fix a wrong idea now than carry it forever. Migrators already walk older documents forward on open, so nothing you author is throwaway, but we won't pretend the schema is frozen.

The official 1.0 lands in late 2026. From that point the wire format is locked, backward compatibility becomes a promise instead of a courtesy, and we'll do our best to support everything ever written in the format from that day on.