@adatechnology/game-audio 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -578,6 +578,64 @@ declare function noiseClassRecipe(row: NoiseClass, id?: string): SoundRecipe;
 /** The game's classes as a bank (`sfx_pistol`... and `sfx_unknown`). Subject banks pick their own classes from `GAME_SFX_CLASSES`. */
 declare const GAME_SFX_BANK: SoundBank;
 
+/** A length in seconds: a number, a `[min, max]` range or a named number. */
+type SceneLength = number | readonly [number, number] | ParamRef;
+type SceneNoise = {
+    readonly type?: BiquadFilterType;
+    readonly f: Range;
+    /** The filter slides here over `d` (needs a fixed `d`). */
+    readonly f2?: number;
+    readonly q?: number;
+    readonly a?: number;
+    readonly d: SceneLength;
+    readonly vol: Range;
+    readonly wet?: number;
+    readonly delay?: Range;
+};
+/** `sNoise` (cena L1323): noise from a random point, a filter (default lowpass, Q 0.7), the gain rising over `a` and falling over `d`. */
+declare function sceneNoise(o: SceneNoise): Layer;
+type SceneTone = {
+    readonly wave?: OscillatorType;
+    readonly f: Range;
+    readonly f2?: number;
+    readonly d: SceneLength;
+    readonly vol: Range;
+    readonly wet?: number;
+    readonly delay?: Range;
+};
+/** `sTone` (cena L1324): an oscillator sliding from `f` to `f2` (back to `f` when none), the gain rising over 0.002 s and falling over `d`. */
+declare function sceneTone(o: SceneTone): Layer;
+type SceneVoice = {
+    /** Start and end frequency of the sweep (the page ramps linearly from `f0` to `f1` over the length). */
+    readonly f0: Range;
+    readonly f1: Range;
+    /** Length in seconds. */
+    readonly d: SceneLength;
+    /** Centre of the first and second formant (Q 4 and 6) and of the breath band (Q 1.1). */
+    readonly fA: Range;
+    readonly fB: Range;
+    /** Level of the breath noise. */
+    readonly noise: Range;
+    readonly vol: Range;
+    readonly wave?: OscillatorType;
+};
+/**
+ * `voice` (cena L1325): an oscillator swept from `f0` to `f1` with a vibrato of 4 to 10 Hz (depth 0.08 of `f0`) through two formant bands plus a band of
+ * breath noise, summed and boosted 3.2 times, the gain rising over 0.1 s, held to 0.6 of the length and falling; reverb send 0.45. It is the one
+ * layer the page builds with `voice(...)`, so a scream is two of them.
+ */
+declare function sceneVoice(o: SceneVoice): Layer;
+/** The layer played `count` times (a team `for` loop whose body draws numbers): each pass is its own layer, so the draws stay in the loop's order. */
+declare const sceneMany: (count: number, make: () => Layer) => Layer[];
+type SceneRecipeOptions = {
+    /** Named numbers drawn first (`PlayOptions.params` can override them). */
+    readonly vars?: SoundRecipe['vars'];
+    readonly bus?: BusId;
+    readonly group?: string;
+};
+/** A recipe in the art scene's mix: positional with the art scene's curve (`vol / (1 + d² × 0.008)`) and pan; `line` is the team code it comes from (`cena:<line>`). */
+declare function sceneRecipe(id: string, layers: readonly Layer[], line: string, options?: SceneRecipeOptions): SoundRecipe;
+
 declare const LIBRARY_SOUNDS: readonly SoundRecipe[];
 declare const LIBRARY_LOOPS: readonly LoopRecipe[];
 declare const LIBRARY_BANK: SoundBank;
@@ -780,4 +838,4 @@ type AudioBenchText = {
 };
 declare const audioBenchTextOf: (locale: string) => AudioBenchText;
 
-export { type AudioBenchText, type AudioChannel, type AudioEngine, type AudioEngineOptions, type AudioLoopHandle, type AudioScenarioLike, type AudioStats, type AudioTestModule, type AudioTestModuleOptions, type Automation, BENCH_BANK, BUILD_ORDERS, BUS_IDS, BUS_PRIORITY, type BuildOrder, type BusId, type BusSetting, type Curve, DEFAULT_LISTENER, DEFAULT_MAX_VOICES, DEFAULT_MIX, DISTANCE_CURVES, type DeepPartial, type DistanceCurveName, type DistanceMode, type EngineSink, type Envelope, type EnvelopePoint, type Falloff, type FilterBank, type FilterSpec, type FormantVoiceSource, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, type Layer, type LayerSource, type Listener, type LoopAction, type LoopOrder, type LoopRecipe, type LoopState, MIX_PROFILES, type MixChain, type MixProfile, type Modulator, type NoiseClass, type NoiseSource, type OscSource, PAN_LIMIT, PAN_MIN_DISTANCE, type ParamRef, type PlanInput, type PlannedAutomation, type PlannedEnvelopePoint, type PlannedFilter, type PlannedLayer, type PlannedModulator, type PlannedSource, type PlayOptions, type Range, type RealizeTarget, type RealizedVoice, type SoundBank, type SoundPlan, type SoundRecipe, type SoundRegistry, type Time, VOICE_GROUPS, type VoiceDecision, type VoiceGroup, type VoiceHandle, type VoiceManager, type VoiceManagerOptions, type VoiceRefusal, type VoiceRequest, type VoiceStats, audioBenchTextOf, bufferOf, buildChain, busGain, busPriority, createAudioEngine, createAudioSink, createAudioTestModule, createLoopState, createRng, createSoundRegistry, createVoiceManager, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, listenerDistance, noiseClassRecipe, panFor, planSound, realize, resolveMix, streamFor, streamSeed, unlockContext };
+export { type AudioBenchText, type AudioChannel, type AudioEngine, type AudioEngineOptions, type AudioLoopHandle, type AudioScenarioLike, type AudioStats, type AudioTestModule, type AudioTestModuleOptions, type Automation, BENCH_BANK, BUILD_ORDERS, BUS_IDS, BUS_PRIORITY, type BuildOrder, type BusId, type BusSetting, type Curve, DEFAULT_LISTENER, DEFAULT_MAX_VOICES, DEFAULT_MIX, DISTANCE_CURVES, type DeepPartial, type DistanceCurveName, type DistanceMode, type EngineSink, type Envelope, type EnvelopePoint, type Falloff, type FilterBank, type FilterSpec, type FormantVoiceSource, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, type Layer, type LayerSource, type Listener, type LoopAction, type LoopOrder, type LoopRecipe, type LoopState, MIX_PROFILES, type MixChain, type MixProfile, type Modulator, type NoiseClass, type NoiseSource, type OscSource, PAN_LIMIT, PAN_MIN_DISTANCE, type ParamRef, type PlanInput, type PlannedAutomation, type PlannedEnvelopePoint, type PlannedFilter, type PlannedLayer, type PlannedModulator, type PlannedSource, type PlayOptions, type Range, type RealizeTarget, type RealizedVoice, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SoundBank, type SoundPlan, type SoundRecipe, type SoundRegistry, type Time, VOICE_GROUPS, type VoiceDecision, type VoiceGroup, type VoiceHandle, type VoiceManager, type VoiceManagerOptions, type VoiceRefusal, type VoiceRequest, type VoiceStats, audioBenchTextOf, bufferOf, buildChain, busGain, busPriority, createAudioEngine, createAudioSink, createAudioTestModule, createLoopState, createRng, createSoundRegistry, createVoiceManager, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, listenerDistance, noiseClassRecipe, panFor, planSound, realize, resolveMix, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext };

package/dist/index.global.js

@@ -66,6 +66,11 @@ var GameAudio = (() => {
     planSound: () => planSound,
     realize: () => realize,
     resolveMix: () => resolveMix,
+    sceneMany: () => sceneMany,
+    sceneNoise: () => sceneNoise,
+    sceneRecipe: () => sceneRecipe,
+    sceneTone: () => sceneTone,
+    sceneVoice: () => sceneVoice,
     streamFor: () => streamFor,
     streamSeed: () => streamSeed,
     unlockContext: () => unlockContext
@@ -356,8 +361,8 @@ var GameAudio = (() => {
     const depth = typeof modulator.depth === "object" && "scaleOf" in modulator.depth ? sourceFrequency * modulator.depth.factor : pending.depth ?? 0;
     return { target: modulator.target, ...modulator.wave ? { wave: modulator.wave } : {}, rate: pending.rate, depth, ...modulator.base === void 0 ? {} : { base: modulator.base } };
   }
-  function finishEnvelope(envelope, duration, level) {
-    return envelope.map(([time, value, curve, fixed2]) => ({ time: timeOf(time, duration), value: fixed2 === "fixed" ? value : value * level, curve }));
+  function finishEnvelope(envelope2, duration, level) {
+    return envelope2.map(([time, value, curve, fixed2]) => ({ time: timeOf(time, duration), value: fixed2 === "fixed" ? value : value * level, curve }));
   }
   function planLayer(layer, scope, defaults, levelInEnvelope, soundLevel) {
     const pending = drawLayer(layer, scope);
@@ -596,6 +601,83 @@ var GameAudio = (() => {
   }
   var GAME_SFX_BANK = { id: "game_sfx", sounds: [...GAME_SFX_CLASSES, GAME_SFX_FALLBACK].map((row) => noiseClassRecipe(row)) };
 
+  // src/recipes/scene.ts
+  var ATTACK = 2e-3;
+  function lengthOf(d, attack) {
+    if (typeof d === "number") return attack + d;
+    if (Array.isArray(d)) return [attack + d[0], attack + d[1]];
+    return { ...d, add: (d.add ?? 0) + attack };
+  }
+  var envelope = (attack) => [
+    [0, 1e-4, "set", "fixed"],
+    [attack, 1, "exp"],
+    ["1d", 1e-4, "exp", "fixed"]
+  ];
+  function sceneNoise(o) {
+    const a = o.a ?? ATTACK;
+    const over = typeof o.d === "number" ? o.d : 0;
+    return {
+      filters: {
+        mode: "serial",
+        bank: [{ type: o.type ?? "lowpass", frequency: o.f2 === void 0 ? { set: o.f } : { set: o.f, to: o.f2, curve: "exp", over }, q: o.q ?? 0.7 }]
+      },
+      duration: lengthOf(o.d, a),
+      gain: o.vol,
+      ...o.delay === void 0 ? {} : { at: o.delay },
+      ...o.wet === void 0 ? {} : { wet: o.wet },
+      source: { kind: "noise", offset: "random", offsetScale: 1.5, loop: true },
+      envelope: envelope(a)
+    };
+  }
+  function sceneTone(o) {
+    return {
+      source: { kind: "osc", wave: o.wave ?? "sine", frequency: { from: o.f, to: o.f2 ?? "from", curve: "exp", over: "duration" } },
+      duration: lengthOf(o.d, ATTACK),
+      gain: o.vol,
+      ...o.delay === void 0 ? {} : { at: o.delay },
+      ...o.wet === void 0 ? {} : { wet: o.wet },
+      envelope: envelope(ATTACK)
+    };
+  }
+  function sceneVoice(o) {
+    return {
+      duration: lengthOf(o.d, 0),
+      gain: o.vol,
+      wet: 0.45,
+      source: {
+        kind: "formant_voice",
+        wave: o.wave ?? "sawtooth",
+        frequency: { from: o.f0, to: o.f1, curve: "linear", over: "duration" },
+        vibrato: { rate: [4, 10], depth: 0.08 },
+        formants: [
+          { frequency: o.fA, q: 4 },
+          { frequency: o.fB, q: 6 }
+        ],
+        breath: { frequency: o.fB, q: 1.1, gain: o.noise },
+        mix: 3.2
+      },
+      envelope: [
+        [0, 1e-4, "set", "fixed"],
+        [0.1, 1, "exp"],
+        ["0.6d", 1, "set"],
+        ["1d", 1e-4, "exp", "fixed"]
+      ]
+    };
+  }
+  var sceneMany = (count, make) => Array.from({ length: count }, make);
+  function sceneRecipe(id, layers, line, options = {}) {
+    return {
+      id,
+      bus: options.bus ?? "world",
+      pan: true,
+      layers,
+      falloff: DISTANCE_CURVES.art_scene,
+      ...options.vars ? { vars: options.vars } : {},
+      ...options.group ? { group: options.group } : {},
+      sources: [`cena:${line}`]
+    };
+  }
+
   // src/library/crowd_rumble.json
   var crowd_rumble_default = {
     id: "crowd_rumble",
@@ -1149,10 +1231,10 @@ var GameAudio = (() => {
         assign(filter.frequency, band.frequency, time);
         if (band.q !== void 0) filter.Q.value = band.q;
       }
-      const envelope = context.createGain();
-      applyEnvelope(envelope.gain, layer.envelope, time);
-      oscillator.connect(envelope);
-      envelope.connect(filter);
+      const envelope2 = context.createGain();
+      applyEnvelope(envelope2.gain, layer.envelope, time);
+      oscillator.connect(envelope2);
+      envelope2.connect(filter);
       oscillator.start(time);
       oscillator.stop(end(layer, time));
       return oscillator;
@@ -1189,12 +1271,12 @@ var GameAudio = (() => {
       rampTo(node.frequency, filter.frequency, time);
       return node;
     });
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
     let tail = source;
     for (const filter of filters) tail = tail.connect(filter);
-    tail.connect(envelope);
-    envelope.connect(outputStage(plan, layer, target));
+    tail.connect(envelope2);
+    envelope2.connect(outputStage(plan, layer, target));
     source.start(time, layer.source.kind === "noise" ? layer.source.offset : 0);
     source.stop(end2(layer, time));
     return [source];
@@ -1208,10 +1290,10 @@ var GameAudio = (() => {
       assign(oscillator.frequency, layer.source.frequency, time);
       rampTo(oscillator.frequency, layer.source.frequency, time);
     }
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
-    oscillator.connect(envelope);
-    envelope.connect(outputStage(plan, layer, target));
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
+    oscillator.connect(envelope2);
+    envelope2.connect(outputStage(plan, layer, target));
     oscillator.start(time);
     oscillator.stop(end2(layer, time));
     return [oscillator];
@@ -1240,10 +1322,10 @@ var GameAudio = (() => {
     breathBand.connect(breathLevel);
     for (const formant of formants) formant.connect(mix);
     breathLevel.connect(mix);
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
-    mix.connect(envelope);
-    envelope.connect(outputStage(plan, layer, target));
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
+    mix.connect(envelope2);
+    envelope2.connect(outputStage(plan, layer, target));
     const stop = end2(layer, time);
     oscillator.start(time);
     vibrato.start(time);
@@ -1281,17 +1363,17 @@ var GameAudio = (() => {
       return { lfo, depth, target: modulator.target };
     });
     const lfos = depths.map(({ lfo }) => lfo);
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
-    for (const { depth, target: modulated } of depths) if (modulated === "gain") depth.connect(envelope.gain);
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
+    for (const { depth, target: modulated } of depths) if (modulated === "gain") depth.connect(envelope2.gain);
     const filters = (layer.filters?.bank ?? []).map((filter) => filterNode(context, filter, time));
     let tail = oscillator;
     for (const filter of filters) tail = tail.connect(filter);
-    tail.connect(envelope);
-    envelope.connect(target.output);
+    tail.connect(envelope2);
+    envelope2.connect(target.output);
     if (layer.wet && target.wet) {
       const send = gainNode(context, layer.wet);
-      envelope.connect(send);
+      envelope2.connect(send);
       send.connect(target.wet);
     }
     const stop = end2(layer, time);
@@ -1307,11 +1389,11 @@ var GameAudio = (() => {
     const { context } = target;
     const source = noiseSource(target, layer.source.kind === "noise" && layer.source.loop);
     const filters = (layer.filters?.bank ?? []).map((filter) => filterNode(context, filter, time));
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
     let tail = source;
     for (const filter of filters) tail = tail.connect(filter);
-    tail.connect(envelope).connect(target.output);
+    tail.connect(envelope2).connect(target.output);
     source.start(time, layer.source.kind === "noise" ? layer.source.offset : 0);
     source.stop(time + layer.duration + layer.tail);
     return source;
@@ -1324,9 +1406,9 @@ var GameAudio = (() => {
       assign(oscillator.frequency, layer.source.frequency, time);
       rampTo(oscillator.frequency, layer.source.frequency, time);
     }
-    const envelope = context.createGain();
-    applyEnvelope(envelope.gain, layer.envelope, time);
-    oscillator.connect(envelope).connect(target.output);
+    const envelope2 = context.createGain();
+    applyEnvelope(envelope2.gain, layer.envelope, time);
+    oscillator.connect(envelope2).connect(target.output);
     oscillator.start(time);
     oscillator.stop(time + layer.duration + layer.tail);
     return oscillator;
@@ -1883,8 +1965,8 @@ var GameAudio = (() => {
       const layers2 = planned.layers.map((layer, index) => {
         const source = layer.source.kind === "noise" ? `noise@${layer.source.offset.toFixed(4)}` : layer.source.kind === "osc" ? `${layer.source.wave}@${layer.source.frequency.value ?? layer.source.frequency.from}` : layer.source.kind;
         const filters = (layer.filters?.bank ?? []).map((filter) => `${filter.type}@${(filter.frequency.value ?? filter.frequency.from ?? 0).toFixed(1)}`).join(" ");
-        const envelope = layer.envelope.map((point) => `${point.time.toFixed(3)}:${point.value.toPrecision(3)}`).join(" ");
-        return `  ${text.sheet.layer} ${index + 1}: ${source} at ${layer.at.toFixed(3)} for ${layer.duration.toFixed(3)} ${filters} [${envelope}]`;
+        const envelope2 = layer.envelope.map((point) => `${point.time.toFixed(3)}:${point.value.toPrecision(3)}`).join(" ");
+        return `  ${text.sheet.layer} ${index + 1}: ${source} at ${layer.at.toFixed(3)} for ${layer.duration.toFixed(3)} ${filters} [${envelope2}]`;
       });
       return [head, ...layers2].join("\n");
     };