Saving Loading and JSON Sidecars

Saving, Loading, and JSON Sidecars

A FWG export can give you two different things worth keeping:

• WAV — the rendered audio;
• JSON sidecar — the reconstruction record.

If a result may be edited, rerendered for another target, traced back to a random batch, or investigated later, keep its JSON sidecar. Current exports normally use .json.gz: ordinary UTF-8 JSON wrapped in gzip. Plain .json remains importable.

First hands-on reload

🎹 Try one complete round trip. Export a small Morph result, then immediately reload its .json.gz:

1. In Morph, make a short result and export it with its JSON sidecar.
2. Press Load JSON… and choose the matching sidecar. The button opens FWG's general import router; its physical position beside an endpoint does not force that endpoint to be the destination.
3. To reconstruct the exported result, choose Load The Whole Thing. FWG restores START, END, Morph settings, render settings, and the exported direction, then leaves playback stopped. The status tells you whether to press Forward or Reverse to audition the saved result.
4. Repeat the import and choose a single endpoint destination. Endpoint imports switch to the relevant workspace and auto-audition that destination.

This makes the distinction clear:

• Load The Whole Thing restores a complete result and waits for you to audition it;
• Load START + END restores both endpoints and leaves playback stopped;
• single-endpoint loads auto-audition the destination;
• settings-only loads change settings without starting playback.

What a result sidecar contains

🔧 An ordinary Morph, Bulk Random, or Explorer result sidecar can preserve:

• START and END endpoint patches;
• Morph settings;
• render/export settings;
• Drawn waveform state, including custom Drawn that is currently dormant;
• custom Scanning recipes needed by the patch;
• random/generation context where relevant;
• export identity and creation/runtime information;
• safety/render reports;
• optional diagnostics when enabled.

The matching WAV carries identifiers that link it back to the sidecar/export pair.

The JSON is the reconstruction record; the WAV is the rendered audio.

What to keep

🎹 For ordinary creative work:

• keep the WAVs you actually want to use;
• keep the matching sidecars for keepers and promising near-misses;
• keep useful Explorer recipes as reusable search presets;
• keep standalone Drawn/Scanning documents only when you intentionally use those interchange workflows.

You do not need every sidecar from every rejected bulk batch unless you want a complete archive.

Loading a complete result

🎹 To reconstruct an exported Morph/Bulk/Explorer result, choose Load The Whole Thing.

FWG restores the canonical START and END design roles and separately restores/selects the exported direction. This is important for asymmetric modes such as Fixed START-mod-END: a Reverse result is not necessarily equivalent to swapping endpoints and playing Forward.

Import does not automatically start playback. Audition the restored direction using the indicated Morph transport.

Loading only part of a result

🎹 Import choices depend on the document, but ordinary result sidecars can offer combinations such as:

• Load START → Playground;
• Load END → Playground;
• Load START → START;
• Load END → END;
• Load START + END;
• cross-load START→END or END→START;
• Load The Whole Thing;
• Load Morph Settings Only;
• Load Render Settings Only;
• Load Morph + Render Settings Only.

Common uses

I want the exact result back
Use Load The Whole Thing.

I like the transition but want different endpoints
Use Load Morph Settings Only.

I want to reuse file geometry/cleanup/MPC layout
Use Load Render Settings Only.

I want to build a new Morph from one exported endpoint
Load/cross-load that endpoint into START or END.

Explorer recipes are different from result sidecars

🎹 An Explorer recipe describes a search centre and variation grammar. Loading it sends you to Explorer rather than treating it as a normal complete Morph result.

Use Explorer recipes when you want to restore/reuse a neighbourhood search, not merely one rendered candidate. See Bulk Explorer and Auditioning, Curation, and Building a Personal Library.

Standalone Drawn documents

Export Drawn creates a small schema-13 document containing the Drawn waveform and application identity.

Importing it changes only the destination patch's Drawn waveform state: its canonical 512-internal-cycle-sample runtime table plus any valid pristine construction/transform/normalise authority and most-recent population record carried by that Drawn document. It does not replace generator, routing, Morph, render, or Scanning-recipe state, so it is not a complete patch template.

Standalone Drawn JSON is intentionally suitable for hand/machine editing. See Drawn Waveform.

Standalone Scanning recipes

Scanning recipes have their own small declarative format: recipe name + base generator + Pot1/Pot2/Pot3 trajectories.

They do not contain executable DSP and do not contain Drawn waveform data. Imported custom recipes live in the current page session and can be used by Playground/Morph/Explorer as documented in Scanning Recipes.

Complete Morph/Explorer sidecars embed any custom recipe definition needed to reconstruct the saved work.

.json.gz and plain .json

🔧 v3.0 exports JSON as deterministic .json.gz by default.

FWG accepts both .json and .json.gz. Gzip is recognised by the 1F 8B magic bytes rather than trusting the filename extension alone.

Ordinary import guards are:

• maximum compressed input: 1 MiB;
• maximum decoded JSON: 512 KiB.

Gzip import requires browser DecompressionStream. Plain .json remains available when it is absent.

When Render Diagnostics is enabled, FWG intentionally bypasses those byte-size guards because its own support sidecars can be much larger; schema/content validation still applies.

Current and historical schema support

🔧 v3.0 emits schema 13.

The current public importer explicitly supports:

• schema 12 — public v2.9c;
• schema 13 — v3.0.

Other explicit schema numbers are rejected rather than guessed.

Supported schema-12 structures are migrated into current semantics where documented—for example the old 256-step window domain and historical Drawn representation. See Compatibility and Versioning.

Table Safety metadata

🔧 When Table Safety is used during a render, public JSON records the final structural disposition for each corrected table. table_safety counts/events and rendered notes do not double-count a temporary internal helper failure plus the owning START/END/Morph fallback as two delivered corrections. Batch aggregate counts use the same resolved view.

A final previous valid table substitution is therefore reported once as previous-valid; a final safety square substitution is reported once as the square.

Drawn data in sidecars

🔧 Current schema-13 Drawn storage uses one waveform authority at a time.

A pristine numeric construction pipeline may retain, in execution/read order:

data
resample_mode
wrap          (where applicable)
transform     (where present)
normalise     (when true)

data, resample_mode, and stage-1 wrap first materialise the ordinary bounded 512-internal-cycle-sample Float32 Drawn waveform. Optional transform then consumes exactly that materialised waveform; optional normalise:true is a final uniform gain stage. A transform never receives sparse anchors or private pre-admission reconstruction workspace.

Current v3 transform families are Fourier, Haar and Walsh. Fourier remains available as a normal resample_mode as well as a stage-2 transform; Haar and Walsh are transform-only. See Drawn Mathematical Reference for selector syntax and Drawn Wave-Shape Recipes for practical examples.

For hand-edited schema-13 Drawn JSON, omit transform/normalise when they are not used. transform:null, transform:"", and normalise:null are invalid explicit values; wrap:null is the deliberate exception and uses the ordinary local open/default topology.

After ordinary Drawn editing or deliberate flattening, the current literal 512-sample table becomes the sole saved authority. Standalone Export Drawn always writes that literal editable surface and drops active transform/normalise instructions, preventing double processing on re-import.

For numeric data:[...], ordinary numeric-array format metadata is irrelevant to current semantics and new numeric exports/examples omit it. Historical Base64/builtin encodings remain separate compatibility representations.

The exact built-in sine may use default_sine_v1; schema-12 256-point Drawn keeps its historical cyclic migration rule. Current sidecars preserve custom Drawn even when it is dormant so later editing/reconstruction does not silently lose it.

Missing or malformed dependencies

⚠️ Import is deliberately tolerant about optional/dormant fields but strict about authoritative data required to reconstruct the claimed active sound.

For current schema-13 material, if the effective route requires Drawn or a required custom Scanning definition and that dependency is missing/malformed, import fails visibly rather than silently substituting some default generator or sine.

Conversely, a dormant selector that is not actually consumed should not create a false dependency requirement.

Creation time and runtime environment

⚠️ Result sidecars contain created_utc. This is useful record-retention data captured from the local clock, not a trusted timestamp.

Ordinary result sidecars/Explorer recipes can also contain runtime_environment, including browser-reported identity/platform information and the current page URL. Imports ignore this block; it exists for troubleshooting and historical reconstruction.

If you plan to share a sidecar publicly, you may wish to remove optional runtime/provenance fields. See Sharing and Cleaning JSON Sidecars.

Optional Render Diagnostics

🔧 Load FWG from a page URL with the diagnostics query parameter appended:

?render_diagnostics=a

This is the ?... query component of the URL, not a control inside the normal interface. It can add detailed troubleshooting evidence to rendered sidecars without changing DSP, PCM, or random decisions. See Render Diagnostics and Support for the complete hosted/local URL explanation.

JSON is reproducibility data, not authentication

⚠️ A sidecar can show that the disclosed plan/inputs are sufficient to regenerate the result with the identified compatible executable. It does not by itself prove who created the file, when it was created, or that no file was edited/substituted.

For specialist provenance questions, see Authenticating and Timestamping FWG Outputs.

Technical note: export consistency

🔧 Morph, Bulk Random and Explorer resolve a per-file render/export plan before constructing the final artifact pair. Shared serializers derive common sidecar fields from that captured plan/result rather than rereading mutable live controls afterward.

This is why the sidecar can describe the plan that actually rendered the WAV even if the user changes a control while a long job is running. The exact internal object/cache layout is implementation detail; the public expectation is that each WAV/JSON pair describes one captured result consistently.

Related pages

• Sharing and Cleaning JSON Sidecars
• Compatibility and Versioning
• Drawn Waveform
• Scanning Recipes
• Randomisation and Seeds