Cinema Designer design file format

What a design file is

A design file holds one Cinema Designer room: the room, the screen, the seats, the speakers, the amplifiers, the projector, the door and the treatment. It is one JSON object in UTF-8, named <name>.ohav.json. The design inside it is exactly the object the designer holds, so a file, a saved room and a share link carry the same thing.

In the designer, open the room menu and use Download design file to keep a copy, or Open design file… to load one. You can also drop a file anywhere on the designer. A file opens as a new unsaved design; saved rooms are never changed by opening a file.

The format is described by a JSON Schema (2020-12): https://openhomeav.com/schema/design/v1.0.json. Any JSON Schema validator can check a file against it.

The envelope

The top level of the file, in this order. Only format, version and design are required.

The designer never writes a room id, an access link or a save revision into a file. created is ignored when two designs are compared.

Units and coordinates

• SI units only: lengths in metres, angles in degrees, power in watts, impedance in ohms, levels in dB, delay in milliseconds, light in lumens.
• design.units is the display preference (metric or imperial). It never changes the unit of a stored number.
• The origin is the front-left floor corner. x runs across the room, left to right facing the screen; y runs into the room from the screen wall; z runs up from the floor.
• Numbers keep full double precision in files. Share links round to 6 decimals.

Design fields

units, room, screen and rows are required. Every other field is optional, and leaving it out means what the description says. Bands such as “2 to 15” are what the designer holds: a value outside the band still opens, clamped, and the import report says so. A value of the wrong type (text where a number belongs) or a missing required field stops the file from opening.

Catalogue ids (speaker models, amplifiers, projectors, screen materials, panel types, layouts) are plain text, so a new product in the catalogue never needs a new format version. An id the designer does not know is reported when the file opens.

Versions

• version is "MAJOR.MINOR". This page describes 1.0.
• A minor version only adds optional fields or new allowed values. Every older file stays valid and means the same.
• A major version changes a meaning, a unit or a required field, or removes something. The designer converts files of an older major when it opens them.
• Each version has its own schema file that never changes once released, and /schema/design/v1.json is always the latest 1.x.
• A file from a newer minor opens; fields this designer does not know are listed as not used. A file from a newer major does not open: reload to get the latest designer.
• One major number is shared by design files, saved rooms and share links, so everything saved today is design format 1.0.

What the designer accepts

• A design file, as above.
• A bare design object (the contents of design on its own).
• An object with the design under config.

The last two open as format 1.0, with the note “Opened without a format header”. Files over 1 MB are not read.

How opening a file reports changes

When the designer cannot hold a file exactly as written, it shows every change before opening and asks Open with these changes or Cancel. Nothing a file carries is dropped without being listed.

A file that cannot be opened at all (not JSON, not a design, a wrong type, too many rows or speakers) is refused with the reason and the path of each problem, and nothing on screen changes.

Examples

The smallest useful file: one row with one seat, no speakers.

{
  "$schema": "https://openhomeav.com/schema/design/v1.0.json",
  "format": "openhomeav-design",
  "version": "1.0",
  "name": "Small room",
  "design": {
    "units": "metric",
    "room": {
      "width": 4,
      "length": 5.5,
      "height": 2.5
    },
    "screen": {
      "width": 2.2,
      "aspect": 1.7777777777777777,
      "bottom_z": 0.6,
      "center_x": 2
    },
    "rows": [
      {
        "y": 3.2,
        "eye_z": 1.05,
        "head_z": 1.25,
        "seat_x": [
          2
        ]
      }
    ]
  }
}

The designer’s default design, as its Download writes it (without created).

{
  "$schema": "https://openhomeav.com/schema/design/v1.0.json",
  "format": "openhomeav-design",
  "version": "1.0",
  "name": "Cinema design",
  "generator": {
    "name": "OpenHomeAV Cinema Designer",
    "url": "https://openhomeav.com/designer/"
  },
  "design": {
    "units": "metric",
    "room": {
      "width": 5.5,
      "length": 7.5,
      "height": 2.8
    },
    "screen": {
      "width": 3,
      "aspect": 1.7777777777777777,
      "bottom_z": 0.7,
      "center_x": 2.75
    },
    "rows": [
      {
        "y": 3.6,
        "eye_z": 1.1,
        "head_z": 1.3,
        "seat_x": [
          1.85,
          2.75,
          3.65
        ]
      },
      {
        "y": 4.9,
        "eye_z": 1.55,
        "head_z": 1.75,
        "seat_x": [
          2.3,
          3.2
        ]
      }
    ],
    "seat_centering": "mlp",
    "layout": "5.1",
    "speakers": [
      {
        "channel": "L",
        "x": 1.15,
        "y": 0.1,
        "z": 1.1,
        "archetype": "horn_loaded_cd",
        "aim": {
          "mode": "mlp"
        },
        "follow": true
      },
      {
        "channel": "C",
        "x": 2.75,
        "y": 0.1,
        "z": 1.1,
        "archetype": "horn_loaded_cd",
        "aim": {
          "mode": "mlp"
        },
        "follow": true
      },
      {
        "channel": "R",
        "x": 4.35,
        "y": 0.1,
        "z": 1.1,
        "archetype": "horn_loaded_cd",
        "aim": {
          "mode": "mlp"
        },
        "follow": true
      },
      {
        "channel": "Ls",
        "x": 0.1,
        "y": 4,
        "z": 1.1,
        "archetype": "dipole_surround",
        "aim": {
          "mode": "mlp"
        },
        "follow": true
      },
      {
        "channel": "Rs",
        "x": 5.4,
        "y": 4,
        "z": 1.1,
        "archetype": "dipole_surround",
        "aim": {
          "mode": "mlp"
        },
        "follow": true
      },
      {
        "channel": "LFE",
        "x": 0.25,
        "y": 0.25,
        "z": 0,
        "archetype": "horn_loaded_cd"
      }
    ],
    "amp": {
      "power": 150,
      "rated_ohms": 8,
      "room_gain": 0
    },
    "door": {
      "wall": "back",
      "offset": 0.3,
      "width": 0.8,
      "hinge": "left",
      "swing": "in"
    }
  }
}

Write it from OpenSCAD

// SPDX-License-Identifier: MIT
// ============================================================================
// simple_room.scad: a 5.1.2 room declared with openhomeav_design.scad (R34b).
// ============================================================================
// Write its design file:
//   node tools/scad-to-design.mjs openscad/examples/simple_room.scad -o simple_room.ohav.json
// The committed openscad/examples/simple_room.ohav.json is that output.
//
// Lengths in millimetres; the model's X runs across the room (the default
// frame), so points pass through as [across, into the room, up].
// ============================================================================

use <../openhomeav_design.scad>

// The model's own named variables, as any CAD model has them.
room_w = 4200;
room_l = 6000;
room_h = 2600;
screen_w = 2600;
screen_bottom = 500;
screen_depth = 100;            // screen surface forward of the front wall
row_y = 3600;
ear_z = 1100;
seats = [1500, 2100, 2700];
mlp = [2100, 3600, 1100];      // the middle seat
wedge_angle = 30;

// A front left speaker toed in by eye, not aimed at the seat: its driver
// axis becomes an aim offset from the MLP direction in the file.
front_left = [900, 150, 1000];
front_left_axis = [0.25, 1, -0.02];

ohav_design(
    name     = "Simple room",
    unit     = "mm",
    room     = ohav_room(width = room_w, length = room_l, height = room_h),
    screen   = ohav_screen(width = screen_w, aspect = 16 / 9, bottom_z = screen_bottom,
                           center_x = room_w / 2, y_offset = screen_depth),
    rows     = [ohav_row(y = row_y, eye_z = ear_z, head_z = ear_z + 200, seat_x = seats,
                         seat = ohav_sofa(width = 2200, depth = 950, back_height = 800))],
    mlp      = [0, 1],
    layout   = "5.1.2",
    speakers = [
        ohav_speaker("L", pos = front_left, model = "ascendo-the6-passive-on-wall",
                     archetype = "waveguide_dome", aim = ohav_aim_axis(front_left_axis), amp = "a1",
                     body = ohav_body(260, 440, 94)),
        ohav_speaker("C", pos = [room_w / 2, 150, 1000], model = "ascendo-the6-passive-on-wall",
                     archetype = "waveguide_dome", aim = ohav_aim_mlp(), amp = "a1"),
        ohav_speaker("R", pos = [room_w - 900, 150, 1000], model = "ascendo-the6-passive-on-wall",
                     archetype = "waveguide_dome", aim = ohav_aim_mlp(az = -2.5), amp = "a1"),
        ohav_speaker("Ls", pos = [60, 3900, 1300], aim = ohav_aim_normal(), amp = "a1"),
        ohav_speaker("Rs", pos = [room_w - 60, 3900, 1300], aim = ohav_aim_normal(), amp = "a1"),
        ohav_speaker("Ltm", pos = [1300, 3300, room_h - 100], model = "ascendo-the6-passive-wedge30",
                     archetype = "waveguide_dome", aim = ohav_aim_mount("ceiling", cabinet = wedge_angle), amp = "a1"),
        ohav_speaker("Rtm", pos = [room_w - 1300, 3300, room_h - 100], model = "ascendo-the6-passive-wedge30",
                     archetype = "waveguide_dome", aim = ohav_aim_mount("ceiling", cabinet = wedge_angle), amp = "a1"),
        ohav_sub("LFE", pos = [400, 400, 0])
    ],
    amps     = [ohav_amp("a1", product = "denon-avr-x3800h")],
    door     = ohav_door("right", offset = 4600, width = 900, hinge = "left", swing = "in"),
    panels   = [ohav_panel("left", "absorber_broadband", u0 = 3000, u1 = 4200, v0 = 800, v1 = 1800, thickness = 100)],
    source   = [["room", "simple_room.scad room_w, room_l, room_h"],
                ["speakers", "front_left_axis is a driver axis; the rest aim at the MLP or the wall normal"]]
);

Licence

The format, its JSON Schema and this page are dedicated to the public domain under CC0 1.0. Write the file from any tool.