@solidrt/core 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -11,6 +11,7 @@
     "./gpu": "./src/gpu.ts",
     "./image": "./src/image.ts",
     "./microphone": "./src/microphone.ts",
+    "./sound": "./src/sound.ts",
     "./speech-recognition": "./src/speech-recognition.ts",
     "./text-input": "./src/text-input.ts",
     "./jsx-runtime": "./jsx-runtime.d.ts",
@@ -26,7 +27,7 @@
     "colord": "^2.9.3"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.24"
+    "@solidrt/flux-types": "0.0.25"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-beta.15",

package/src/gpu.ts

@@ -19,6 +19,13 @@ import * as gpu from "flux:gpu"
 // `<texture params={...}>` when a `<texture>` element is already in the tree.
 export { destroyTexture, setShaderParams, uploadTexture } from "flux:gpu"
 
+// captureSnapshot renders a node to a texture and readTexture reads any
+// texture's bytes back. Re-exported raw (no reactive auto-cleanup wrapper):
+// captureSnapshot resolves asynchronously, by which point the reactive owner is
+// no longer current, so the caller owns the returned id and frees it with
+// destroyTexture (as with any texture created after an await).
+export { captureSnapshot, readTexture } from "flux:gpu"
+
 /**
  * Uploads raw RGBA8 pixels to an immutable GPU texture and returns its id (use
  * it as `<texture src={id} />`). `data` must be exactly `width * height * 4`

package/src/sound.ts

@@ -0,0 +1,119 @@
+// Sound playback, reactive (SolidJS) layer. `createSound` decodes an encoded
+// clip (Ogg/Vorbis or WAV) once and owns its lifecycle: the decoded clip is
+// released, and any playing voices stopped, when the reactive owner is disposed.
+// Each play() is cheap (no re-decode). `createSoundStream` is the same but reads
+// a large track from a file path on demand instead of decoding it into memory.
+//
+// The imperative primitive lives in the `flux:audio` module; import
+// { play, load, stream } from "flux:audio" for non-reactive use.
+
+import { createSignal, onCleanup } from "@solidjs/signals"
+import { load, stream } from "flux:audio"
+import { file } from "flux:fs"
+
+type FluxFile = ReturnType<typeof file>
+
+type LoadedSound = ReturnType<typeof load>
+
+export type SoundOptions = {
+  /** Repeat the clip until stopped. Defaults to false. */
+  loop?: boolean
+  /** Volume scale, 1.0 leaves the clip unchanged. Defaults to 1.0. */
+  gain?: number
+  /**
+   * Let play() stack overlapping voices instead of restarting. Defaults to
+   * true: rapid triggers overlap. Set false for a single-voice sound where each
+   * play() cuts off the previous one.
+   */
+  overlap?: boolean
+}
+
+/** Options for a streamed sound. Streams are always single-voice. */
+export type SoundStreamOptions = {
+  /** Repeat the track until stopped. Defaults to false. */
+  loop?: boolean
+  /** Volume scale, 1.0 leaves the track unchanged. Defaults to 1.0. */
+  gain?: number
+}
+
+/** A decoded sound with reactive lifecycle. */
+export type Sound = {
+  /** Start the clip. Overlaps or restarts per the `overlap` option. */
+  play(): void
+  /** Stop every voice started from this sound. */
+  stop(): void
+  /** True after play() until stop() (does not track natural completion). */
+  playing(): boolean
+  /** Set if loading failed. */
+  error(): Error | undefined
+}
+
+// Shared reactive wrapper: owns the loaded handle, tracks live voices, and
+// disposes both on cleanup. `loader` runs once (may throw -> error signal).
+function reactiveSound(
+  loader: () => LoadedSound,
+  overlap: boolean,
+  playOptions: { loop?: boolean; gain?: number },
+): Sound {
+  let [error, setError] = createSignal<Error | undefined>(undefined, { ownedWrite: true })
+  let [playing, setPlaying] = createSignal(false, { ownedWrite: true })
+
+  let handle: LoadedSound | undefined
+  let voices: { stop(): void }[] = []
+  try {
+    handle = loader()
+  } catch (e) {
+    setError(e instanceof Error ? e : new Error(String(e)))
+  }
+
+  let stopAll = () => {
+    for (let v of voices) v.stop()
+    voices = []
+    setPlaying(false)
+  }
+
+  onCleanup(() => {
+    stopAll()
+    if (handle) {
+      handle.unload()
+      handle = undefined
+    }
+  })
+
+  return {
+    play() {
+      if (!handle) return
+      if (!overlap) stopAll()
+      voices.push(handle.play(playOptions))
+      setPlaying(true)
+    },
+    stop: stopAll,
+    playing,
+    error,
+  }
+}
+
+/**
+ * Decodes a sound once and owns its lifecycle: releases the clip and stops its
+ * voices when the reactive owner is disposed. play() replays without decoding.
+ * For imperative use, call load()/play() from "flux:audio".
+ */
+export function createSound(source: Uint8Array, options: SoundOptions = {}): Sound {
+  return reactiveSound(() => load(source), options.overlap ?? true, {
+    loop: options.loop,
+    gain: options.gain,
+  })
+}
+
+/**
+ * Streams a large track, decoding on demand instead of loading it into memory.
+ * Single-voice: each play() restarts it. Pass a path (resolved like flux:fs,
+ * relative to the process cwd) or a `file()` from flux:fs; a path is wrapped in
+ * `file()` for you, so a dev-server-proxied file streams over the proxy. Owns
+ * the stream's lifecycle: stopped and released when the reactive owner is
+ * disposed. For imperative use, call stream()/play() from "flux:audio".
+ */
+export function createSoundStream(source: string | FluxFile, options: SoundStreamOptions = {}): Sound {
+  let src = typeof source === "string" ? file(source) : source
+  return reactiveSound(() => stream(src), false, { loop: options.loop, gain: options.gain })
+}