@solidrt/flux-types 0.0.23 → 0.0.25

package/README.md

@@ -47,7 +47,7 @@ rely on must be named.
 - `Flux` global (`version`, `capabilities`).
 - `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
   `flux:p2p`, `flux:process`, `flux:path`, and (on a gui-enabled runtime)
-  `flux:camera`, `flux:microphone`, `flux:gpu`.
+  `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
   `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,
   `TextEncoder`/`TextDecoder`. These are deliberate subsets matching exactly what

package/gui/audio.d.ts

@@ -0,0 +1,50 @@
+// Sound playback (gui-enabled runtime only). The imperative primitive; `play`
+// decodes and starts a clip in one call, while `load` decodes once so a clip can
+// be replayed cheaply. Handles carry a `stop()` bound to just that voice, so the
+// raw track id never leaves the runtime.
+
+declare module "flux:audio" {
+  /** Options for {@link play} and {@link LoadedSound.play}. */
+  type PlayOptions = {
+    /** Repeat the clip until stopped. Defaults to false. */
+    loop?: boolean
+    /** Volume scale, 1.0 leaves the clip unchanged. Defaults to 1.0. */
+    gain?: number
+  }
+
+  /** A playing voice with controls bound to it. */
+  type SoundHandle = {
+    /** Stop this voice. A no-op if it already finished. */
+    stop(): void
+  }
+
+  /** A decoded clip that can be replayed without re-decoding. */
+  type LoadedSound = {
+    /** Start a fresh overlapping voice for this clip. */
+    play(options?: PlayOptions): SoundHandle
+    /** Release the decoded clip. Voices already playing keep going. */
+    unload(): void
+  }
+
+  /**
+   * Decode and start an encoded audio clip (Ogg/Vorbis or WAV). Returns
+   * immediately; the sound plays on the mixer's own thread. Use {@link load} to
+   * replay a clip repeatedly without decoding it each time.
+   */
+  export function play(bytes: Uint8Array, options?: PlayOptions): SoundHandle
+  /**
+   * Decode an encoded clip (Ogg/Vorbis or WAV) once and keep it in memory so it
+   * can be replayed cheaply. Call `unload()` on the result when done.
+   */
+  export function load(bytes: Uint8Array): LoadedSound
+  /**
+   * Open a clip for streaming: it is decoded on demand instead of loaded fully
+   * into memory, so a large track needs little RAM. Takes a `file()` from
+   * `flux:fs` (not a path), so the source rides the `file()` proxy override - a
+   * dev-server-proxied file streams from the server. Play the result as a single
+   * voice; do not overlap a stream with itself. Call `unload()` when done.
+   */
+  export function stream(source: ReturnType<typeof import("flux:fs").file>): LoadedSound
+  /** Stop every playing sound. */
+  export function stop(): void
+}

package/gui/gpu.d.ts

@@ -36,4 +36,21 @@ declare module "flux:gpu" {
   ): number
   /** Update a shader texture's float uniforms by name and re-render it. */
   export function setShaderParams(id: number, params: Record<string, number>): void
+  /**
+   * Capture a render-tree node's subtree into a new GPU texture, resolving once
+   * it has been rendered on the next paint pass. The node must be attached to
+   * the live tree (a detached node is never painted, so its capture rejects).
+   * Rendered at the current display scale, so `width`/`height` are the texture's
+   * actual pixel dimensions (ceil(logicalSize * displayScale)), not logical
+   * points. Each call returns an independent id you must {@link destroyTexture}
+   * when done. Use the returned id anywhere a texture id is accepted
+   * (`<texture src>`, a shader sampler input, {@link readTexture}).
+   */
+  export function captureSnapshot(nodeId: number): Promise<{ id: number; width: number; height: number }>
+  /**
+   * Read back a registered texture's current pixels as RGBA8 (tightly packed,
+   * top-to-bottom rows), for any texture id whatever created it (createTexture,
+   * createShader, captureSnapshot). Synchronous. Throws if the id is unknown.
+   */
+  export function readTexture(id: number): { width: number; height: number; data: Uint8Array }
 }

package/index.d.ts

@@ -25,6 +25,7 @@
 /// <reference path="./gui/rendertree.d.ts" />
 /// <reference path="./gui/camera.d.ts" />
 /// <reference path="./gui/microphone.d.ts" />
+/// <reference path="./gui/audio.d.ts" />
 /// <reference path="./gui/gpu.d.ts" />
 /// <reference path="./gui/raf.d.ts" />
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",