Working with Projects

An Aether project is a single .aether file: the graph (nodes, connections, property values), sequencer patterns, patch definitions, sample references, MIDI virtual devices with their bindings, and embedded scripts. Opening a project restores exactly the state that was saved.

Saving

Cmd-S - Save. The first save prompts for a filename and location through the native file dialog. The default directory is ~/Documents/Aether Projects/ and is created on first use. Subsequent Cmd-S saves overwrite in place and show a "Project saved" toast.

For a snapshot under a new name, use the Save As… entry in the toolbar's File menu - there's no keyboard shortcut for Save As wired in 0.1.0.

Projects save synchronously: the save completes before control returns.

Opening

Cmd-O - Open. The native file dialog points at the projects directory by default. Picking a .aether file replaces the current graph.

Projects can also be opened:

  • From the welcome overlay on cold launch.
  • From the command line: /Applications/Aether.app/Contents/MacOS/aether --file path/to/file.aether launches Aether with the project preloaded. (Finder double-click and open -a Aether file.aether are not yet wired - the .app bundle doesn't register .aether as a document type in 0.1.0.)
  • Auto-reopen: the most recently opened project is remembered across restarts and reopens automatically unless a different file is passed on startup.

The .aether Format

.aether files are redb databases (embedded key-value store). Graph content is serialised with serde_json inside the redb tables, so the format is binary at the file level but structured JSON at the row level.

Format compatibility disclaimer. Project files written by 0.1.0 are not guaranteed to open in future builds. The graph, property, and sequencer schemas may change as the engine evolves. Treat anything built in 0.1.0 as a snapshot of the tool at that point in time.

Backup Strategies

Three approaches, in rough order of reliability:

  1. Copy the .aether file. Works until the format changes. Fine for short-term backups within the 0.1.0 release.
  2. Export as a Rhai script. export_graph() in the console returns the current graph as a Rhai string that rebuilds the same patch when re-run. Scripts are plain text, diff-friendly, and the scripting API is the more stable surface across releases. See Running Scripts.
  3. Version control. .aether is binary, so git diffs are useless - but the file is small enough that keeping copies in a repository works for milestone snapshots.

For any patch worth keeping long-term, the script export is the right call.

Autosave

There is no autosave in 0.1.0. Every save is explicit. Long sessions should Cmd-S habitually. A future release will add periodic background saves; for now, treat unsaved work as volatile.

Where Projects Live

  • Default directory. ~/Documents/Aether Projects/, created on first save or open.
  • Last-opened pointer. ~/Library/Application Support/aether/settings.json holds the path to auto-reopen on next launch.

No .aether demo projects ship in 0.1.0. The starting patches live as Rhai scripts under Contents/Resources/scripts/demos/ and scripts/tutorial/; run one from the console with include("external://scripts/demos/lofi-chill") to build the graph.