@octoseq/visualiser 0.1.0-main.e2ea119 → 0.1.0-main.ef9b77a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@octoseq/visualiser",
-    "version": "0.1.0-main.e2ea119",
+    "version": "0.1.0-main.ef9b77a",
     "description": "WASM-based visualiser for Octoseq",
     "license": "MIT",
     "repository": {

package/pkg/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "visualiser",
+  "type": "module",
+  "version": "0.1.0",
+  "files": [
+    "visualiser_bg.wasm",
+    "visualiser.js",
+    "visualiser.d.ts"
+  ],
+  "main": "visualiser.js",
+  "types": "visualiser.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/pkg/visualiser.d.ts

@@ -0,0 +1,320 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class WasmVisualiser {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Check if a script is currently loaded.
+   */
+  has_script(): boolean;
+  /**
+   * Load a Rhai script for controlling the visualiser.
+   * Returns true if the script was loaded successfully.
+   */
+  load_script(script: string): boolean;
+  /**
+   * Push a named signal for use in scripts.
+   * The signal will be available as `inputs.<name>` in Rhai scripts.
+   */
+  push_signal(name: string, samples: Float32Array, sample_rate: number): void;
+  /**
+   * Run script in analysis mode to collect debug.emit() signals.
+   *
+   * This runs the script headlessly across the full track duration,
+   * collecting all debug.emit() calls without rendering.
+   *
+   * Returns a JSON-serialized AnalysisResultJson.
+   */
+  run_analysis(script: string, duration: number, time_step: number): string;
+  /**
+   * Clear all named signals.
+   */
+  clear_signals(): void;
+  set_sigmoid_k(k: number): void;
+  /**
+   * Isolate a single entity for rendering (useful for debugging).
+   * Only this entity will be rendered.
+   */
+  isolate_entity(entity_id: bigint): void;
+  push_zoom_data(samples: Float32Array, sample_rate: number): void;
+  /**
+   * Clear entity isolation, resume normal rendering.
+   */
+  clear_isolation(): void;
+  /**
+   * Get current state values for debugging.
+   * Returns [time, scene_entity_count, mesh_count, line_count]
+   */
+  get_current_vals(): Float32Array;
+  /**
+   * Get the last script error message, if any.
+   */
+  get_script_error(): string | undefined;
+  /**
+   * Get the list of available signal names.
+   * Returns a JSON array of signal names.
+   */
+  get_signal_names(): string;
+  /**
+   * Get a list of all registered mesh asset IDs.
+   * Returns a JSON array of asset IDs.
+   */
+  list_mesh_assets(): string;
+  /**
+   * Push pre-extracted events for a band.
+   *
+   * Events are extracted by the TypeScript layer using the existing peak picker,
+   * then pushed here for script access via `inputs.bands[id].events`.
+   *
+   * The JSON format should be an array of event objects with:
+   * - time: f32
+   * - weight: f32
+   * - beat_position: Option<f32>
+   * - beat_phase: Option<f32>
+   * - cluster_id: Option<u32>
+   *
+   * Returns true if successful, false if parsing failed.
+   */
+  push_band_events(band_id: string, events_json: string): boolean;
+  /**
+   * Push a band-scoped signal for use in scripts.
+   * The signal will be available as `inputs.bands[band_id].{feature}` in Rhai scripts.
+   * Stores under both band_id and band_label for dual-access support.
+   *
+   * - `band_id`: The unique ID of the frequency band.
+   * - `band_label`: The user-visible label of the band.
+   * - `feature`: Signal type ("energy", "onset", "flux").
+   * - `samples`: Signal data.
+   * - `sample_rate`: Sample rate of the signal.
+   */
+  push_band_signal(band_id: string, band_label: string, feature: string, samples: Float32Array, sample_rate: number): void;
+  /**
+   * Set the musical time structure for beat-aware signal processing.
+   * The JSON format matches the TypeScript MusicalTimeStructure type.
+   * Returns true if successful, false if parsing failed.
+   */
+  set_musical_time(json: string): boolean;
+  /**
+   * Clear all band event streams.
+   */
+  clear_band_events(): void;
+  /**
+   * Push a named event stream (e.g., "beatCandidates") for script access.
+   *
+   * The event stream will be available as `inputs.<name>` in Rhai scripts.
+   * This is used for MIR-derived events like beat candidates, onset peaks, etc.
+   *
+   * The JSON format should be an array of event objects with:
+   * - time: f32
+   * - weight: f32
+   * - beat_position: Option<f32>
+   * - beat_phase: Option<f32>
+   * - cluster_id: Option<u32>
+   *
+   * Returns true if successful, false if parsing failed.
+   */
+  push_event_stream(name: string, events_json: string): boolean;
+  /**
+   * Set debug visualization options.
+   */
+  set_debug_options(wireframe: boolean, bounding_boxes: boolean): void;
+  /**
+   * Clear all band signals.
+   */
+  clear_band_signals(): void;
+  /**
+   * Clear the musical time structure.
+   * Beat-aware operations will fall back to 120 BPM default.
+   */
+  clear_musical_time(): void;
+  /**
+   * Get frequency bounds for all active bands at a given time.
+   * Returns a JSON array of { bandId, label, lowHz, highHz, enabled } objects.
+   */
+  get_band_bounds_at(time: number): string;
+  push_rotation_data(samples: Float32Array, sample_rate: number): void;
+  /**
+   * Render with a frame budget timeout.
+   *
+   * If the frame takes longer than `budget_ms` to process, it will be dropped
+   * and a warning logged. This prevents expensive scripts from freezing the browser.
+   *
+   * Returns true if the frame completed, false if it was dropped due to budget.
+   */
+  render_with_budget(dt: number, budget_ms: number): boolean;
+  /**
+   * Clear all named event streams.
+   */
+  clear_event_streams(): void;
+  /**
+   * Check if frequency bands are currently set.
+   */
+  has_frequency_bands(): boolean;
+  /**
+   * Register a mesh asset from OBJ content.
+   * The asset will be available as `mesh.load(asset_id)` in scripts.
+   * Returns true if successful, false if parsing failed.
+   */
+  register_mesh_asset(asset_id: string, obj_content: string): boolean;
+  /**
+   * Set the frequency band structure for band-aware processing.
+   * The JSON format matches the TypeScript FrequencyBandStructure type.
+   * Returns true if successful, false if parsing failed.
+   */
+  set_frequency_bands(json: string): boolean;
+  /**
+   * Get the number of events for a specific band.
+   * Returns 0 if no events are stored for this band.
+   */
+  get_band_event_count(band_id: string): number;
+  /**
+   * Get list of band keys (IDs and labels) that have signals.
+   * Returns a JSON array of strings.
+   */
+  get_band_signal_keys(): string;
+  /**
+   * Clear the frequency band structure.
+   */
+  clear_frequency_bands(): void;
+  /**
+   * Unregister a mesh asset.
+   * Returns true if the asset was unregistered, false if it didn't exist.
+   */
+  unregister_mesh_asset(asset_id: string): boolean;
+  /**
+   * Get the number of events in a named event stream.
+   * Returns 0 if no events are stored for this name.
+   */
+  get_event_stream_count(name: string): number;
+  /**
+   * Get the number of frequency bands.
+   */
+  get_frequency_band_count(): number;
+  /**
+   * Run script in analysis mode with event extraction support.
+   *
+   * This runs the script headlessly across the full track duration,
+   * collecting all debug.emit() calls AND extracting events from
+   * any signal.pick.events() calls.
+   *
+   * Returns a JSON-serialized ExtendedAnalysisResultJson.
+   */
+  run_analysis_with_events(script: string, duration: number, time_step: number): string;
+  /**
+   * Get entity positions as JSON for debugging.
+   * Returns a JSON array of objects with id, type, and position fields.
+   */
+  get_entity_positions_json(): string;
+  /**
+   * Drain and return any pending structured script diagnostics as JSON.
+   *
+   * Intended for UI consumption. Calling this clears the pending diagnostics
+   * queue so repeated polling does not duplicate messages.
+   */
+  take_script_diagnostics_json(): string;
+  constructor();
+  render(dt: number): void;
+  resize(width: number, height: number): void;
+  set_time(time: number): void;
+  push_data(samples: Float32Array, sample_rate: number): void;
+}
+
+export function create_visualiser(canvas: HTMLCanvasElement): Promise<WasmVisualiser>;
+
+/**
+ * Get the host-defined Script API metadata as a JSON string.
+ *
+ * This is a stable, versioned description of the scripting API surface and is
+ * intended to drive editor UX (autocomplete/hover/docs) and future language
+ * bindings.
+ */
+export function get_script_api_metadata_json(): string;
+
+export function init_panic_hook(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_wasmvisualiser_free: (a: number, b: number) => void;
+  readonly create_visualiser: (a: any) => any;
+  readonly get_script_api_metadata_json: () => [number, number];
+  readonly wasmvisualiser_clear_band_events: (a: number) => void;
+  readonly wasmvisualiser_clear_band_signals: (a: number) => void;
+  readonly wasmvisualiser_clear_event_streams: (a: number) => void;
+  readonly wasmvisualiser_clear_frequency_bands: (a: number) => void;
+  readonly wasmvisualiser_clear_isolation: (a: number) => void;
+  readonly wasmvisualiser_clear_musical_time: (a: number) => void;
+  readonly wasmvisualiser_clear_signals: (a: number) => void;
+  readonly wasmvisualiser_get_band_bounds_at: (a: number, b: number) => [number, number];
+  readonly wasmvisualiser_get_band_event_count: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_get_band_signal_keys: (a: number) => [number, number];
+  readonly wasmvisualiser_get_current_vals: (a: number) => [number, number];
+  readonly wasmvisualiser_get_entity_positions_json: (a: number) => [number, number];
+  readonly wasmvisualiser_get_event_stream_count: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_get_frequency_band_count: (a: number) => number;
+  readonly wasmvisualiser_get_script_error: (a: number) => [number, number];
+  readonly wasmvisualiser_get_signal_names: (a: number) => [number, number];
+  readonly wasmvisualiser_has_frequency_bands: (a: number) => number;
+  readonly wasmvisualiser_has_script: (a: number) => number;
+  readonly wasmvisualiser_isolate_entity: (a: number, b: bigint) => void;
+  readonly wasmvisualiser_list_mesh_assets: (a: number) => [number, number];
+  readonly wasmvisualiser_load_script: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_new: () => number;
+  readonly wasmvisualiser_push_band_events: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly wasmvisualiser_push_band_signal: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => void;
+  readonly wasmvisualiser_push_data: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmvisualiser_push_event_stream: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly wasmvisualiser_push_signal: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly wasmvisualiser_push_zoom_data: (a: number, b: number, c: number, d: number) => void;
+  readonly wasmvisualiser_register_mesh_asset: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly wasmvisualiser_render: (a: number, b: number) => void;
+  readonly wasmvisualiser_render_with_budget: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_resize: (a: number, b: number, c: number) => void;
+  readonly wasmvisualiser_run_analysis: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+  readonly wasmvisualiser_run_analysis_with_events: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+  readonly wasmvisualiser_set_debug_options: (a: number, b: number, c: number) => void;
+  readonly wasmvisualiser_set_frequency_bands: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_set_musical_time: (a: number, b: number, c: number) => number;
+  readonly wasmvisualiser_set_sigmoid_k: (a: number, b: number) => void;
+  readonly wasmvisualiser_set_time: (a: number, b: number) => void;
+  readonly wasmvisualiser_take_script_diagnostics_json: (a: number) => [number, number];
+  readonly wasmvisualiser_unregister_mesh_asset: (a: number, b: number, c: number) => number;
+  readonly init_panic_hook: () => void;
+  readonly wasmvisualiser_push_rotation_data: (a: number, b: number, c: number, d: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h9d1c5a23ecfcd5c8: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__heb49a8f426ac2d2e: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h53437a38721e89f7: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__hf5eaa61ced318e08: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h320f3d825d3712ba: (a: number, b: number, c: any, d: any) => void;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_externrefs: WebAssembly.Table;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;