Editing the HypnoSpec document¶

Every session is stored as a HypnoSpec document: an open JSON format for hypnosis session content and settings, currently at draft 2025-07. The editor’s form tabs are views onto that document. The Script tab shows the whole thing.

The Script tab¶

The tab shows the document as YAML in a code editor with schema-aware completion, hover help and live diagnostics. To use it:

Edit the YAML.
Press Validate & Apply. The editor checks the YAML, checks that every known feature still has all of its required keys, and copies the result back into the other tabs. Problems are reported as messages such as Missing key X in configuration for feature Y.
Press Save in the header.

While the script has unapplied edits, the other tabs and the Save button are disabled so the two cannot drift apart.

Unknown feature ids are kept as-is, so documents from other HypnoSpec tools survive a round trip.

Document shape¶

$schema: https://hypna.space/hypnospec/draft/2025-07/schema/
version: "2025-07"
content:
  version: "2025-07"
  type: mst
  features:
    - id: space.hypna.feature.content.lines
      configuration:
        lines: ["first line", "second line"]
settings:
  version: "2025-07"
  features:
    - id: space.hypna.feature.settings.mst
      configuration:
        line_duration: "3500"
    - id: space.hypna.feature.settings.customCSS
      configuration:
        data: ".focus-line { color: pink; }"
spiral:
  id: space.hypna.feature.spirals.webgl
  configuration:
    opacity: "0.6"
    spiral_color: "#FFFFFF"
    bg_color: "#000000"
    spin_speed: 1
    throb_speed: 2
    throb_strength: 1
    zoom: 1
images:
  id: space.hypna.feature.images.basic
  configuration:
    images: []
    switch_frequency: "950"
    images_handled_by_outside_source: true

content.features holds what the session says: lines, text, iteration count, distractor lines.
settings.features holds how it behaves: the type-specific settings and the optional features.
spiral and images each hold exactly one feature.

Every feature object has an id, a configuration and optionally version, required and dependencies.

Settings only reachable here¶

A few keys have no form control:

Feature	Key	Purpose
`content.distractors`	`duration`, `base_frequency`, `base_random_offset`	classic distractor timing
`images.basic` / `images.scatter`	`images_handled_by_outside_source`	leave `true` on Hypna; media is managed by the uploader

Reference¶

The full key-by-key reference for every feature is in HypnoSpec features. The generated JSON Schema documentation is published on the site at https://hypna.space/hypnospec/, and each feature box in the editor links to its own schema page.