.s3gray Format

.s3gray is the runtime interchange format between the s3g-mc Ray Sketch browser utility, s3g Ambi Encoder Ray, and s3g Ambi Encoder Ray Bilocation. It is UTF-8 JSON with a dedicated extension, separate from the editable Ray Sketch project. It contains resolved directional events rather than audio or a realtime geometry engine.

Version 1

The root object contains:

• format: s3g-ambi-ray-field
• version: 1
• ambisonics: ACN/SN3D metadata
• coordinate_system: world axes, AED orientation, units, and the explicit world-to-AED mapping
• interpolation: sampled-cell and stable-slot interpretation metadata
• atlas: optional bundled-preset name, category, description, seed, and provenance
• space: optional generalized geometry, regions, portals, and display provenance
• room: dimensions, top-view polygon, ceiling profile, navigation bounds, and material summary
• listener_position_m and default_source_position_m: reference listener and default source XYZ positions in metres
• grid: authoring-grid dimensions, source-sampling metadata, and the optional global stable-slot key list
• cells: one to 256 sampled source positions

The canonical horizontal mapping is azimuth_deg=atan2(-x_right,y_front): world +X is right/-90 degrees, world -X is left/+90 degrees, and world +Y is front/0 degrees. Ray Sketch stores this value in coordinate_system.world_to_aed.

Each cell has a position_m, up to 32 early_reflections, and one late profile. Every early reflection carries a stable slot, delay in milliseconds, gain, azimuth, elevation, and normalized damping. It may also carry bounce_position_m, an optional XYZ wall, floor, ceiling, portal, or echo-path point used to re-resolve path timing and arrival direction when the listener moves. A slot may be absent from a cell when that path is not active there; readers treat its gain as zero. The late profile carries start time, decay time, level, diffusion, and damping.

Runtime Interpretation

The source and listener XYZ parameters map to the field's navigation bounds. Ambi Encoder Ray computes source-to-listener distance, delay, attenuation, and direction continuously for the direct sound. Source position selects stable reflection slots and late profiles from the four nearest cells using inverse-distance weights. For reflections with a bounce point, the encoder continuously resolves source-to-bounce-to-listener geometry while retaining any non-geometric delay embedded by Ray Sketch. Reflections without a bounce point retain a world-space virtual arrival anchored from listener_position_m. Position and field changes are smoothed by the plugin's MOVEMENT control.

The direct component follows the selected first-through-seventh ambisonic order. Early and late room components are represented through third order. Timing is sample-rate independent in the file and compiled for the current host rate. Imported JSON is embedded in CLAP project state.

Choosing and Updating Files

Load a version 1 s3g-ambi-ray-field runtime file in Ambi Encoder Ray, not an editable s3g-ray-sketch project. To reuse an Imprint Sketch or legacy room-sketch project, import it into Ray Sketch and export a .s3gray file. When a version 1 field omits world_to_aed, the encoder corrects its screen-space horizontal azimuth while loading.

Geometry, materials, path losses, bounce points, and decay values are creative acoustic estimates intended for repeatable spatial composition. Resolved delay, gain, and AED values remain sufficient for a fixed reference listener. bounce_position_m enables moving-listener path resolution without requiring a live geometry simulation; generalized geometry remains display provenance. Version 1 readers may ignore the bounce field.