# AquarellEQ and Orbit: AI usage guide > Make editable, evolving music with Orbit, or visualize an existing track with Watercolor, Fire, Nebula, Crystal Garden or Mushroom Nocturne. The canonical site is https://www.aquarelleq.com/. This guide is linked from https://www.aquarelleq.com/llms.txt; generated command schemas are at https://www.aquarelleq.com/agent-tools.json. The operation-by-operation feature map is https://www.aquarelleq.com/agent-coverage.txt. ## Implemented browser interfaces After the active page loads, use `window.aquarellAgent`. On the Orbit page, `window.orbitAgent` is an alias to the exact same API and command registry. The homepage exposes site actions. Dedicated studios add source, playback, visual, composition and media actions. Orbit adds the musical editor and the five visual worlds using one shared live session. ```js const api = window.aquarellAgent; const tools = api.describe(); const current = await api.getState(); const result = await api.execute('site.setTheme', { preference: 'dark' }); ``` `describe()` is synchronous and returns names, descriptions, JSON input schemas, actual WebMCP status and resource limits. `getState()` is asynchronous and returns a result envelope whose `data` has `{ state: { site: ..., visualizer: ..., orbit: ... }, files: [...], jobs: [...] }`; only providers on the active page are present. Introspection does not start audio, advance the music or create a renderer. `visualizer.getPlayback` reads the transient playhead separately, without changing revisions. Supporting secure browsers also advertise these same actions through native WebMCP. Reading this guide or llms.txt does not connect an AI to the page: the agent needs a browser integration that can invoke page JavaScript or discovered WebMCP tools. No remote MCP server, plugin, backend, keys or HTTP command endpoints are required or supplied. Calls execute inside the open browser tab and return JavaScript objects, which a browser/tool transport can return as JSON. Static documentation uses ordinary GET requests; do not POST commands to documentation URLs or invent `/api` or `/mcp` routes. The homepage's “Make music with your AI” section has a visible starting prompt. `site.getInfo` returns its exact text, section ID, Orbit/guide link destinations and copy feedback in `data.agentPrompt`. `site.copyPrompt` invokes the same Copy prompt action as the visible button, returning `copied: true` only after the browser clipboard write succeeds. A denied or unavailable clipboard reports `CLIPBOARD_WRITE_FAILED` or `CLIPBOARD_UNAVAILABLE`; the text remains selectable. Reading `agentPrompt.text` is the semantic equivalent of selecting the prompt text and does not write to the clipboard or start music. Reveal it with `site.showSection({section:'make-music-with-ai'})` or navigate to `site.navigate({page:'home',section:'make-music-with-ai'})`. Open Orbit is `site.navigate({page:'orbit'})`; follow/read the returned Agent guide link with an ordinary GET. ## Site and visualizer actions Use the exact names and schemas returned by `api.describe()` on each page. Use `visualizer.getCapabilities` for the selected world's real setting keys, numeric limits, step sizes, palette indices, examples, panels, media and eligible Orbit loop counts. | Feature | Implemented commands | | --- | --- | | Routes and appearance | `site.getInfo`, `site.navigate`, `site.setTheme`; homepage also has `site.previewVisualizer` for the hero and `site.setCardPreview` for silent animated cards. Homepage/studios expose `site.showSection`, `site.setDisclosure` and `site.showGuide`; section/FAQ IDs and states come from `site.getInfo`. `site.navigate` accepts an optional Orbit `visualizer` or destination `section`. | | Homepage AI starting prompt | `site.getInfo` exposes `agentPrompt.text`, links and clipboard feedback; `site.copyPrompt` calls the exact UI copy action. The section ID is `make-music-with-ai`. | | Visual inspection | `visualizer.getState`, `visualizer.getCapabilities`, `visualizer.getPlayback`. | | Scene and composition | `visualizer.setSettings`, `visualizer.resetSettings`, `visualizer.setText`, `visualizer.importBackground`, `visualizer.clearBackground`, `visualizer.openBackgroundPicker`. | | Transport and view | `visualizer.setPlaying`, `visualizer.setVolume`, `visualizer.setMuted`, `visualizer.setImmersive`, `visualizer.setFullscreen`, `visualizer.setPanel`. | | Dedicated studio sources | `visualizer.importSource`, `visualizer.loadExample`, `visualizer.openSourcePicker`, `visualizer.seek`, `visualizer.setLoop`, `visualizer.setMicrophone`. | | Orbit visual view | `visualizer.setView`, `visualizer.setRenderer` and the actual Save editable music action `visualizer.openSave`; music is retained in the same live session. `openSave` reveals Your pocket collection and reports the semantic `target: "pocketCollection"`, without relying on canonical DOM IDs or creating a saved copy. Source-file/microphone tools are on dedicated studios, while editable Orbit project/loop imports use `orbit.*`. | | Export panel options and UI results | `visualizer.getExport`, `visualizer.setExportOptions`, `visualizer.downloadExport`. Select options without rendering and inspect/download a result started by a person. | | Render and keep | `visualizer.renderFrame`, `visualizer.export`, `visualizer.cancelOperation`, `site.downloadArtifact`; common `agent.*` tools stage/release files and inspect/cancel jobs or release artifacts. | Examples on an active dedicated studio: ```js const source = api.attachFile(file, { filename: file.name, mediaType: file.type }); const load = await api.execute('visualizer.importSource', { fileId: source.fileId }); // Poll agent.getJob using load.data.jobId; release source.fileId when finished. const look = await api.execute('visualizer.setSettings', { settings: { palette: 1 } }); const text = await api.execute('visualizer.setText', { title: 'My song', artist: 'My name' }); const started = await api.execute('visualizer.export', { media: 'mp4', format: 'phone' }); ``` Homepage animated previews retain reduced-motion, Save Data, visibility and viewport restrictions; a blocked preview reports its reason instead of overriding those preferences. Settings are validated together before applying any part of a patch. Unsupported keys and out-of-range/off-step values are rejected. Text fields accept at most 100 characters. Background images use a staged file ID and accept PNG/JPEG/WebP up to 20 MiB; decode failure/cancellation preserves the previous image. Native file pickers need a trusted browser gesture and user selection; successful opening reports awaiting selection rather than claiming an import completed. Microphone permission and device availability are real browser requirements; cancelling a pending grant stops any late-acquired tracks. `visualizer.setImmersive` controls the page's artwork layout. `visualizer.setFullscreen` separately requests actual native browser fullscreen; it can fail for support, activation or permission reasons. Native fullscreen is reported from the document, not inferred from a CSS class. Panels are opened/closed explicitly and available names reflect the current layout. For Watercolor MP4 only, `paper` can be `light` or `dusk`. Other worlds export their current scene appearance. Orbit visual exports accept `media: 'wav'` or `'mp4'` plus eligible `loops`; MP4 accepts `format: 'desktop'` or `'phone'`. WAV has no video format/paper settings. Dedicated studios render the full finite uploaded/example track and do not take Orbit loop counts. A live microphone is not an MP4 source. PNG and MP4 include the current text/background composition. The image is fitted as centered cover with scene-dependent blending; the app has no background drag/crop/zoom/rotation/opacity controls or text-position editor. Renderer canvases have no camera/drawing pointer gestures; camera elevation is exposed as a setting where offered. UI and agent media operations share the same resource reservation and cancellation cleanup. UI jobs are identifiable by `metadata.interface: "ui"`; their binary output stays with the visible UI. `visualizer.getExport` exposes that panel’s current options/running/result metadata, and `visualizer.downloadExport` requests its existing Download link. Agent renders return an artifact inside their completed job. `site.downloadArtifact({ artifactId })` requests the browser download and reports `downloadRequested`, never disk completion. Local blob URLs, file IDs, jobs and artifacts end with the document session. Navigate only after keeping needed results; rediscover the new page's API and tools. ## One result protocol Example of an actual successful result, with illustrative request ID and revision: ```json { "apiVersion": 1, "requestId": "tempo-change-1", "command": "orbit.setTempo", "status": "applied", "revision": 8, "changed": [ { "path": "/orbit/music/tempo", "before": 72, "after": 90 } ], "data": { "bpm": 90 } } ``` `changed` uses JSON Pointer paths and actual before/after values. Large values can be summarized to keep responses bounded; read the relevant state command for full data. Do not assume a request applied because its arguments were valid. - `applied`: the reported application state changed. - `unchanged`: the requested setting was already active, or a read returned information without editing the application. - `queued`: a loop, comparison or song change is waiting for a musical boundary. Inspect pending state and the active source after the handoff. Acceptance is not yet application. - `running`: an export job started. `data.jobId` identifies it; there is not yet a completed download. - `rejected`: inspect `error.code`, `error.message` and optional `error.details`. Invalid arguments, unknown IDs, incompatible Follow/Turns settings, busy operations and browser activation requirements are reported explicitly. Command errors resolve to rejected result envelopes instead of requiring exception handling. A failure during an external browser action can still report observed changes, such as a panel opened before audio activation failed; inspect `changed`. Direct `attachFile` is a synchronous binary-staging method and can throw an `AgentError` for a bad object or quota. ## Retries and concurrent editing ```js const request = await api.execute('orbit.setTempo', { bpm: 90 }, { requestId: 'tempo-change-1', ifRevision: current.revision }); ``` An optional `requestId` makes mutation retries idempotent within the bounded request cache. Retry the same name, arguments and revision with that ID; use a new ID for a new action. Reusing an ID for a different request is rejected. The current limits are exposed by `describe()`; request retention is five minutes, with up to 128 retained requests. Read calls do not consume mutation-retry entries. Optional `ifRevision` rejects a stale edit before its handler runs. Read a fresh state after `REVISION_MISMATCH`. Revisions observe meaningful application changes, including human edits and actual note/key evolution, while excluding continuous playhead clocks. Omitted fields in a setter are preserved. Use explicit `enabled`, `playing` and note-state values instead of assuming a toggle's starting state. Direct calls also accept an `AbortSignal` in the third-argument options. Cancellation stops cooperative work and cancels a job started by that call; it is not an Undo operation for already-applied music. Use `orbit.undo` for supported editor changes. Do not blindly retry a rejected operation that reports a partial change. ## WebMCP uses the same actions In a supported secure browser context, each AquarellEQ page registers its tools through `document.modelContext`. The adapter detects the browser API; it does not install a polyfill or change browser settings. A supplied older navigator-based preview is recognized only when its real tool APIs exist, and is identified as legacy in the status. WebMCP is experimental and depends on the browser and agent. Discover native tools through the agent/browser's WebMCP mechanism, then call the returned tool handle for the desired command. Tool names correspond to direct API command names. A browser integration can add its own handle suffix; use the discovered handle rather than guessing it. Schema descriptions and bounds are supplied at discovery. For example, the business arguments for the `orbit.setTempo` tool are `{ "bpm": 90 }`. Optional transport metadata is passed as: ```json { "bpm": 90, "_request": { "requestId": "tempo-change-1", "ifRevision": 7 } } ``` The adapter removes `_request`, forwards those fields as the direct API's options, and sends the browser cancellation signal to the same command handler. Its callback returns the same result object; the browser/agent transport can serialize it as JSON text. Native registration uses AbortSignal cleanup, refreshes when page providers change and retires when the document ends. Page restoration re-registers tools. `api.describe().webmcp.available` means tools are actually registered, not merely that a browser feature exists. If unavailable, direct calls remain usable through an appropriate browser integration. A page navigation ends the old session: rediscover globals and tools on the destination page. ## Musical commands and coordinates The packaged catalogue covers instrument creation/removal, melody voices and drum kits, levels/mutes, written notes, one-time transformations, note evolution, harmony/key automation, Timbre movement, Follow chains, Turns, live pads/recording/repeat patterns, Fill/Break/Solo/nucleus gestures, presets/random trials/recovery, saved collections, arrangements, comparison, naming/covers/listen links, project and loop imports, exports, Undo, appearance, tools, Help and achievements. Read current instrument and section IDs instead of referring to visible ordinals. Ring, step, preset index, saved slot and section position are zero-based. There are four note rings and sixteen steps. Melody ring 0 is the highest register and ring 3 the lowest. Drums use the selected kit's sound labels. String Pluck is the Melody voice `pluck`. `orbit.setNote` sets one note explicitly. `orbit.setNotes` supplies four arrays of unique steps from 0 through 15, including empty arrays for silent rings. A follower copying a rhythm must first keep the copied notes or disable Follow before editing written notes. Each follower can have one lead; multiple followers and acyclic chains are supported. Matching/copying and separate Turns on the same pair require explicit conflict resolution. Disabling a configured relationship preserves its settings. `orbit.openTool` reveals a control without applying its musical effect; card tools use the supplied ID or selected instrument. It includes the instrument `volume` popup. Live recording and pads use the existing shared clock and named instrument. Releasing a pad ends the physical press; with repeating-note latch enabled, latched notes can continue. `orbit.stopHeldNotes` is the narrow Stop held notes action: clear held/latched notes while preserving recording and the latch preference. Use `orbit.releasePerformance` for the broader release lifecycle, which also stops recording and releases other temporary performance gestures. `durationMs` is for a transient press with latch disabled. Releasing Break schedules its return at the loop boundary. Nucleus swell is an editor-view gesture; switch to the editor before holding it. Loading a preset, saved loop, imported loop or comparison can queue while playing. A `play: true` option requests audio startup; omission preserves the existing transport state. Live music has no fixed ending, while its exports are finite. An arrangement supports up to four independent sections, with 1, 2 or 4 loops each; captures freeze a musical moment. Project backups, saved loops, sections and a kept comparison are distinct resources. ### Saved loops, backups and downloads The pocket collection is the editor's place to save and revisit individual loops. **Save this loop** keeps a separate editable copy on this browser/device, including its notes, sounds and automation. Choose **Edit** on a pocket card to rename, load, replace or remove that saved loop; the editor shows only the chosen card's controls. `orbit.saveLoop`, `getCollection`, `loadLoop`, `renameLoop` and `removeLoop` act on these same saved copies. Slot numbers and storage do not change when their controls move. To reveal a particular saved card's editor, read the collection and pass its zero-based slot: ```js const saved = await api.execute('orbit.getCollection'); const entry = saved.data.slots.find(Boolean); if (entry) { await api.execute('orbit.openTool', { tool: 'saved', slot: entry.slot }); } ``` The optional `slot` is valid only for the `saved` tool. `orbit.getInterface` reports the focused `collectionEditor.slot` and the `saved-loop-manager` disclosure's open state. Direct `renameLoop` or `saveLoop({slot})` calls perform the edit without opening its interface; replacing a slot updates that saved copy with the current loop. **Downloads & backups** contains portable project backup/restore and loop downloads. A `.orbit.json` project backup preserves the whole editable workspace, including current music, pocket collection, song sections and comparison. WAV is rendered audio, MIDI is note/drum data and PNG is artwork; these downloads are different from a whole-project backup. A listen link contains the current editable loop, with its sounds and automation, rather than the full collection or project. Clearing browser storage can remove local saves, so download a project backup to move editable work to another device or keep a portable copy. ### Twist, space and reshape notes Twisting shifts the existing notes of one ring around the same sixteen-step loop, preserving its note count and the instrument's other rings: ```js const state = await api.execute('orbit.getState'); const id = state.data.music.constellations[0].id; await api.execute('orbit.transformNotes', { id, operation: 'rotate', ring: 0, offset: 2 }); ``` A positive offset moves notes later; a negative offset moves them earlier. Offsets wrap around the loop. Give `ring` and `offset` for `rotate`. Use `spread` to set an exact evenly spaced count on one ring: ```js await api.execute('orbit.transformNotes', { id, operation: 'spread', ring: 3, count: 4, offset: 1 }); ``` This puts four notes on the lowest ring, starting at step 1. `spread` requires `ring` and `count`; its offset is optional and defaults to zero. Counts range from 0 through 16, and zero clears that ring. `clear` empties all rings. `left` and `right` move the whole phrase one step, `echo` adds answers four steps later, `space` keeps alternate notes on each ring, and `random` changes the pattern once. Those operations do not accept ring/count/offset arguments. Repeating a transformation with a new request ID can perform another edit; use the same request ID to retry a single intended action safely. ### Automation and excluding keys Per-instrument note evolution, shared harmony and Timbre movement are independent. The following enables modest note changes and automatic key movement while excluding A minor (`sunroom`) from future key choices: ```js await api.execute('orbit.setInstrument', { id, autoRandomize: true, mutation: 25 }); await api.execute('orbit.setHarmony', { autoKey: true, keyEvery: 1, keyDrift: 0, keyPool: ['daydream', 'afterhours'] }); ``` The current harmony IDs are `daydream` (C major), `sunroom` (A minor) and `afterhours` (D minor); read capabilities for the active version. `keyPool` is the complete allowed list, not a list of exclusions. Keep at least one key. Excluding the current key affects future automatic choices; set `mood` explicitly if an immediate change is wanted. Key intervals are 0.25, 0.5 or 1 loop, and `keyDrift` controls timing drift for shorter intervals. Automatic Tone & space uses the same graph, interval and curvature as the editor: ```js await api.execute('orbit.resetTimbre'); await api.execute('orbit.setTimbre', { motion: { enabled: true, every: 0.5, curve: 70, seed: 12345 } }); ``` The optional unsigned 32-bit seed controls this movement path, not note or harmony randomness. Starting a stopped movement without a seed chooses a fresh path, like the UI. Disabling movement or changing its timing/path preserves the current heard position before reanchoring. Setting a manual `tone` or `haze` takes control and stops automatic movement unless `motion` is also explicitly supplied in the same call. `orbit.resetTimbre` is the Original action: restore the original Tone & space point and stop movement while retaining its configured timing/curvature. Read `orbit.getState`'s `data.playback.field` for the live point rather than treating the stored starting point as its current position. ### Follow and Turns Use `orbit.setFollow({target, source, mode, enabled:true})` with `room` for gaps, `meet` for matching beats, or `mirror` for copying. `orbit.swapFollow({target})` exchanges that connection's lead and follower in one atomic edit, retaining other followers. It rejects circular chains, an occupied new follower and incompatible Turns. `orbit.getRhythmPreview({target})` returns the written/heard rings and Before/After step preview without playing audio. `orbit.keepFollowNotes({id:target})` keeps the result of any enabled Follow mode as editable notes and stops that connection; Undo restores the old notes and settings. `orbit.setTurns` sets `enabled`, member IDs and `every`. A disabled draft may have zero or one member; enabling requires two or more. The editor determines turn order from instrument order. `orbit.matchTurns` gives included instruments the first included instrument's rhythm. Stop the conflicting Follow or Turns setting explicitly before asking for an incompatible combination. ## Interface and learning controls The API exposes the editor's interface lifecycle as well as musical edits: ```js const ui = await api.execute('orbit.getInterface'); await api.execute('orbit.setDialog', { dialog: 'help', open: true }); await api.execute('orbit.setDialog', { dialog: 'help', open: false }); await api.execute('orbit.setGuide', { group: 'all', open: false }); ``` Dialog IDs are `help`, `addInstrument`, `audioExport`, `projectRestore` and `sharedListening`. `orbit.setDetails({sectionId,open})` only accepts advertised disclosure IDs; discover them from the interface instead of inventing DOM selectors. Open the relevant editor tool when its contents should be visible. `orbit.closeTool` closes the contextual tool, while `orbit.setDialog` closes the selected modal through its own lifecycle. Closing the audio-export review does not cancel an export job; use `agent.cancelJob` for a running job. `orbit.dismissNotice` accepts `welcome`, `achievementReward`, `toast` or `levelPopup`. Dismissal does not undo music or change earned progress. `orbit.setGuide` independently sets selected-goal `visible`, category `group` (including `all`), or floating-guide `open`. A floating guide can remain hidden while the selected goal is hidden. `orbit.nextAchievement` follows the editor's next-unearned-goal ordering and dismisses the reward card; set `keepGuideOpen:true` for the floating guide's Next goal behavior. `orbit.showAchievement({id,reveal:true})` selects a real goal and reveals its actual control without performing the task or awarding progress. | Editor function | Command or semantic equivalent | | --- | --- | | Play/pause, Tempo, master mute/volume, Swing | `setTransport`, `setTempo`, `setMix` | | Add/remove instrument, voice/kit, individual level/mute | `addInstrument`, `removeInstrument`, `setInstrument` | | Plant/erase, draw a phrase, twist a ring, even spacing | `setNote`, `setNotes`, `transformNotes` with `rotate` or `spread` | | New pattern, Shift, Echo, Make space, clear notes | `transformNotes` with `random`, `left`, `right`, `echo`, `space` or `clear` | | Change each loop and its Amount | `setInstrument` with `autoRandomize` and `mutation` | | Shared key, automatic key timing/drift, include/exclude keys | `setHarmony`, with a complete allowed `keyPool` | | Tone & space graph/sliders, movement interval/curve, Original | `setTimbre`, `resetTimbre` | | Follow apply/change/disable, swap, preview, keep result | `setFollow`, `swapFollow`, `getRhythmPreview`, `keepFollowNotes` | | Turns members/interval/disable and pass the same rhythm | `setTurns`, `matchTurns` | | Instrument selection, recording, latch/pattern/rate, live pads | `selectInstrument`, `setPerformance`, `playPad` | | Stop held notes, broad release, Fill/Break, Solo/nucleus | `stopHeldNotes`, `releasePerformance`, `performanceGesture`, `solo`, `charge` | | Ready-made/random loops, queue cancellation and original-loop recovery | `listPresets`, `loadPreset`, `randomSong`, `cancelQueued`, `returnToLoop` | | Pocket collection save/listen and Edit card rename/load/replace/remove | `getCollection`, `saveLoop`, `loadLoop`, `renameLoop`, `removeLoop`; `openTool` with `tool:'saved',slot` reveals the chosen card's controls | | Song capture/sources/name/repeat/length/order/remove/play | `getArrangement`, `captureSection`, `setArrangement`, `updateSection`, `removeSection`, `clearArrangement`, `loadExampleArrangement`, `setArrangementPlayback` | | Kept-versus-draft comparison | `getComparison`, `keepComparison`, `useComparison`, `clearComparison` | | Name/cover, copy listen link, listen/remix, imports/backups | `setCreation`, `getShare`, `copyShareLink`, `previewShare`, `remixShared`, `importLoop`, `getProject`, `importProject` | | WAV/MIDI/PNG/project and arranged-song WAV exports | `getExportOptions`, `export`, `exportArrangement`, shared job/artifact commands | | Panels, volume popup, dialogs, details, notices and project review | `openTool`, `closeTool`, `getInterface`, `setDialog`, `setDetails`, `dismissNotice`, `openProjectPicker`, `confirmProjectRestore` | | Theme, Undo, goals, categories, floating guide and next goal | `setTheme`, `undo`, `getAchievements`, `showAchievement`, `setGuide`, `nextAchievement` | Names in this table use the `orbit.` prefix. The machine-readable catalogue and active `describe()` include each command's full schema. Semantic equivalents change the same underlying state; they do not synthesize pointer dragging or keyboard events. The [complete editor coverage map](agent-coverage.txt) records each operation, its command and its canonical source owner, including all automation and interface controls. ## Imports: local file handles or JSON For editable backups, use a JSON object directly: ```js const backup = await api.execute('orbit.getProject'); const restored = await api.execute('orbit.importProject', { project: backup.data }); ``` For a local file supplied by a browser picker or integration: ```js const staged = api.attachFile(file, { filename: file.name }); const restored = await api.execute('orbit.importProject', { fileId: staged.fileId }); await api.releaseFile(staged.fileId); ``` `file` is an actual browser `File` or `Blob`; it is not a string containing an operating-system path. Attaching retains the object locally without reading or uploading it. Hosted media/background-image import commands consume the same staged file IDs; discover their schemas on the active visualizer page. For JSON-only agents, `agent.stageFile` accepts `{ filename, mediaType, dataBase64 }` and returns file metadata with `fileId`. Base64 must be canonical and padded. This path accepts at most 8 MiB decoded; use a browser file picker or direct binary attachment for larger local files. Direct attachment accepts up to 256 MiB per file, eight files and 512 MiB total retained data. Release files when finished. Project backups are validated before replacing the project and must fit the existing 20 MiB project limit. `orbit.importLoop` accepts either a loop snapshot or an encoded listen URL; it parses the URL locally without fetching another website. The browser file picker and microphone permission still require browser/user cooperation. These tools cannot read arbitrary local paths or silently grant permissions. Replacing media and changing composition use the same validation/decoder paths as the visible application. ## Exports: jobs and artifact handles ```js const started = await api.execute('orbit.export', { format: 'wav', loops: 4, evolve: true }); const polled = await api.execute('agent.getJob', { jobId: started.data.jobId }); ``` Poll `agent.getJob` until its `data.status` is `completed`, `failed` or `cancelled`. A running job exposes progress. A completed job's `data.data` contains the export result, including its artifact metadata. For an Orbit export, that includes `{ artifact: { artifactId, url, filename, mediaType, bytes }, ... }`. The artifact URL is a local `blob:` download handle in this document, not an uploaded public file. Use it in the browser's download flow, then release it through `agent.releaseArtifact`. Completion means bytes were rendered; it does not prove a download finished on disk. `agent.cancelJob` cancels running work, and released/cancelled/disposed artifacts are revoked. Handles do not survive navigation or session disposal. A cancelled task can take time to release a browser encoder/offline renderer; wait until busy state clears before starting another heavy task. Orbit supports WAV, MIDI, instrument PNG and editable `.orbit.json` exports; `orbit.exportArrangement` renders a full song WAV. Read `orbit.getExportOptions` for allowed loop counts and durations. Standalone offers up to 16 loops; AquarellEQ can offer eligible counts up to 32. Finished Orbit audio/video must fit four minutes including the ending/container allowance. Captures retain enabled evolution coherently without mutating the live composition. Hosted visualizers additionally expose their PNG/MP4 export commands, styles, palettes and composition settings. Existing uploaded tracks retain their own full-track export behavior. Rendering pauses playback, preserves editable music and returns a finite result. Device/browser encoder and canvas limits can reject an export; inspect the job error. Artifact retention is limited to eight handles, 2 GiB per artifact and 4 GiB total. These limits retain existing Blob/File handles without copying their bytes; browser memory/storage and encoder limits still apply. Read the live `describe().limits` and release completed artifacts when no longer needed. ## Browser behavior and scope The API is local to the active page and shares its current music/settings. Introspection and tool registration do not start audio, create another musical clock or load an unrelated renderer. Audio startup, microphone permission, clipboard access, fullscreen and file selection obey ordinary browser rules. A fresh document without audio activation rejects live startup promptly (`REQUIRES_USER_INTERACTION` for Orbit, `USER_ACTIVATION_REQUIRED` for host visualizer commands), leaving playback stopped instead of waiting indefinitely for AudioContext.resume. Use the actual Play or Use microphone control, then retry after checking state. Source files can still decode into a paused source without audio activation. No account, backend, remote MCP server, Codex plugin, third-party upload or external message is created by these commands. Saved data uses the existing local persistence; portable backups remain the way to move editable projects between devices. The interface does not bypass browser security or publish a user's music automatically. ## Choose a starting page | Goal | Public page | | --- | --- | | Choose a visualizer | https://www.aquarelleq.com/ | | Make or edit music | https://www.aquarelleq.com/orbit/ | | Visualize a track in watercolor | https://www.aquarelleq.com/watercolor/ | | Visualize a track with fire | https://www.aquarelleq.com/fire/ | | Visualize a track with a nebula | https://www.aquarelleq.com/nebula/ | | Visualize a track with crystals | https://www.aquarelleq.com/crystals/ | | Visualize a track with mushrooms | https://www.aquarelleq.com/mushrooms/ | The five dedicated visualizers accept an existing audio/video file, a bundled example song or microphone input. Their source controls include Open audio / video, Examples, Use microphone and Make music. Make music opens Orbit; it does not convert an uploaded track into editable Orbit notes. ## Using the browser controls Inspect the current page's accessible names, labels and control state before acting. Instrument names, counts and playback labels change with the music. Scope repeated controls such as Mute, New pattern and Follow to the intended instrument card. Prefer labeled controls and keyboard interaction over coordinates when the browser tool supports them. The editor moves its original tool sections into contextual panels. Closed sections can still exist in a hidden reserve, and closing animations can briefly show a passive picture of a section. Interact with the visible, enabled controls. Opening a panel does not itself apply its musical settings. The shared tool row contains Try loops, Arrange, Saved & exports, Compare, Name & share and Timbre. Clicking an open tool's button closes its panel; the panel's close button also works. Only one contextual tool panel is open at a time. Closing a panel does not generally undo its applied settings. Closing or switching away from Play & record ends its recording and held/repeating notes while the ordinary loop can continue. | Task | Current controls and expected behavior | | --- | --- | | Start or stop the loop | Use Play/Pause. Opening the page does not start audio. Browser audio startup can require a user gesture. | | Add an instrument | Use Add instrument or Add another instrument, then choose Melody, Drums or Bass. String Pluck is a Melody voice. | | Edit notes | Use each card's circular note board. Toggle dots to add/erase notes, or drag a ring to shift its timing. Focused dots support arrow-key navigation and Enter/Space to toggle; Shift + Left/Right twists the focused ring one step. | | Change a pattern | New pattern changes that card's notes once. Change each loop enables ongoing note evolution; its Amount slider appears inside that control. | | Mix an instrument | Use its voice/drum selector, Mute and Volume. Solo is a hold-to-listen action; releasing it restores the prior mix/playback state. | | Change tempo, harmony or tone | Open Timbre, whose inner heading is Change the sound. Tempo, Swing, shared key and Tone & space affect the whole loop. Fine-tuning sliders provide an alternative to dragging the sound graph. | | Create an infinite song | Combine optional Change each loop, Change key automatically and Move tone & space automatically. Live music can continue developing with no fixed ending; infinite song describes open-ended playback, not an infinitely long export file or a guarantee that a pattern never repeats. | | Connect rhythms | Open Follow on the intended follower card, choose a lead and an effect, then Apply rhythm connection. Each follower can have one lead; a lead can have multiple followers, and acyclic chains are supported. Apply disappears when the selected settings are already active. | | Alternate instruments | Open Turns on an instrument card and choose the partner/timing. Follow and Turns are separate settings; the UI explains incompatible combinations on the same pair. | | Try a ready-made loop | Open Try loops and choose Try loop on a card. There are ten authored loops. Cards have no Add to song action. Back to my loop restores the music from before the trial. | | Generate music | Random song generates a new editable loop. Back to my loop and ordinary Undo support recovery. | | Arrange several sections | Open Arrange. Add current loop as a section captures the live music. Change the loop and capture again; up to four independent sections can each last 1, 2 or 4 loops. Source selection and capture controls are inside Arrange. | | Keep a comparison | Open Compare and keep a version before experimenting. The kept version and latest draft are separate from saved loops and song sections. | | Keep editable music | Open Saved & exports to reach Your pocket collection. Save this loop keeps a separate local copy; Edit on a saved card opens that copy's rename, Load, Replace and Remove controls. Downloads & backups offers Download project backup and Restore a project; .orbit.json backups include the whole editable workspace, collection and song. | | Share an editable loop | Open Name & share to name it, choose a cover and copy a listen link. A shared loop link does not publish the whole saved collection or project backup. | | Visualize Orbit music | Use Visualize / Visualize this loop. The visual view keeps the same music session and enabled evolution. Back to editing returns to the editor; Save editable music opens Your pocket collection, with canonical reveal and focus. | For concrete feature examples, try Pocket parade for a detailed drums-only beat; Signal garden for multiple Follow connections; Prism relay for Turns across melody voices; or Endless skylight for notes, key and Timbre movement together. Trying a loop changes the live draft. Saved loops and existing song sections stay separate. ## Verify an action and keep the music After a browser action, read the updated control values, pressed/expanded state and visible status text. Opening Follow is different from applying a connection. An absent Apply button can mean the current settings are already applied. A collapsed panel does not mean its effect was disabled. While music is playing, trial loops and comparison changes can queue for the next complete loop. Read Queued / next loop feedback and wait for the handoff before reporting that the new music is active. Pausing applies a pending loop recall immediately. Live note evolution can keep changing notes after an action, so a later note pattern need not match an earlier snapshot. The current loop autosaves on this browser/device. Save this loop keeps a separate copy; a project backup is a portable editable file. Save before a longer experiment and download a backup when the music needs to move between devices. Undo is available for ordinary edits, but the current visit's Undo history is not a portable backup. Clearing browser storage can remove local music and settings. Audio playback state and rendered artwork can be inspected through the UI, but they do not by themselves prove that sound reached the listener's speakers or that a download finished. Report the result actually observed by the browser tool. ## Exports and browser requirements In Orbit's visual view, Export media offers finite WAV audio or MP4 video. Available loop counts come from 1, 2, 4, 8, 16 and 32, filtered by the four-minute finished-file limit. The 240-second maximum includes the ending and container timing allowance. Read the offered duration; not every count is available at every tempo. Enabled evolution is captured in the finite performance. Playback pauses during rendering. Downloads & backups, below Your pocket collection, offers Download audio for WAV, Download notes & drums for MIDI, Download image for PNG instrument artwork, Name & share, and editable project backups. It does not duplicate the local saved-loop list. Read the options shown by each download dialog. A media file is a rendered result, not an editable project backup. A finished render presents its own download action; wait for completion rather than treating the start of rendering as a finished download. The dedicated visualizers offer PNG frames and landscape/portrait 1080p MP4 exports. The Orbit four-minute limit does not apply to existing uploaded tracks. Microphone input is for live visualization; use an audio/video file for a dedicated studio's MP4 export. Media processing happens locally in the browser. Visual rendering needs WebGL 2 and hardware acceleration. MP4 export needs H.264 and AAC encoding through WebCodecs in a supported browser. Keep the page open while exporting; device performance and mobile background playback vary.