@denaudio/den 0.0.0-stage → 0.2.0

package/docs/wavetable.md

@@ -0,0 +1,101 @@
+# Bounded resident wavetable candidate
+
+`@denaudio/den/wavetable` exports `wavetableSource`, `WavetableConfig` and
+`WavetableControls`. This is a candidate source, not an approved sound or a
+bandlimited wavetable engine. Existing oscillator, instrument and sounds are unchanged.
+
+## Layout and ingress
+
+Instantiate one `residentSample` from `@denaudio/den/sample`, then pass that shared
+resident to `wavetableSource`. The source does not create an asset loader or a
+second PCM buffer. Use the resident's existing native `event<{data:Float32Array}>`
+and `sample.load(data)` ingress, outside audible playback when practical. Native
+dispatch copies PCM at a block boundary; this is not callback-free streaming.
+
+PCM is frame-major mono: concatenate complete cycles of equal length. Do not
+duplicate the first sample at the end. `frameLength` is an integer 4..4096;
+`frameCount` is an integer 1..16. Their product must fit `sample.capacity`, which
+must be 4..65536. Construction rejects invalid layouts. Extra loaded PCM after the
+required product is ignored. A shorter or empty asset produces zero with
+`missing=true` for the whole source, rather than playing a partial table.
+
+The maximum layout holds 16 × 4096 = 65536 float32 samples (256 KiB). With the
+sample lane's explicit CAPACITY_16 ingress and 262144-byte payload capacity,
+the event payload arena contributes another 4 MiB, plus native metadata and
+I/O/state. Ingress belongs to the shared resident, not to each oscillator. A
+source has two cycle interpolations/four integer resident reads (eight bounded
+PCM taps) regardless of frame count,
+plus 36 bytes of declared scalar values before native layout/alignment. There is
+no unrolled table bank, mipmap builder, FFT, dynamic allocation or JS DSP callback.
+
+## Controls and sound
+
+- `sampleRate`: finite 8000..192000 Hz, fixed at construction.
+- `phaseCycles`: initial/reset phase in [0,1), default0.
+- `frequencyHz`: float32 signal, clipped to [0,.45 × host sample rate]. Negative
+  values and NaN become0; positive infinity saturates. At zero Hz phase holds.
+- `frame`: fractional frame index, clipped to [0,frameCount−1]. NaN becomes0.
+  Frame interpolation is linear without smoothing or wrap of the frame selector.
+- `reset`: level-sensitive. True emits the configured phase on that sample,
+  then advances. A held reset repeats the same phase, though morph can change.
+- Return: `{output, missing}`. Output is not peak-normalized or hard-clipped.
+
+Cycle-local integer positions and fractions are split before adding a frame
+offset, preserving tiny fractional contributions against large finite PCM. Each
+cycle uses two integer resident reads and a convex linear mix. Both selected
+cycles wrap independently from their last PCM sample back to their
+own first sample, then their outputs are mixed. A cycle never interpolates into
+the next morph frame. `sourceSampleRate` metadata is intentionally irrelevant:
+each frame is one cycle, so frequency is controlled in host Hz, not playback-rate
+conversion. The resident reader substitutes zero for NaN/infinite PCM taps;
+arbitrary finite PCM amplitude is retained. Interpolated values are not stored in
+float scalar scratch states, preserving tiny/subnormal samples.
+
+Every resident revision, including equal-length replacement and revision integer
+wrap, restarts the configured phase. Phase still advances while the asset is
+missing. Replacement restarts it again when data arrives. There is no replacement
+crossfade. No note/gate policy, envelope, gain stage or automatic unison is added.
+
+Phase and frame materialization use exact power-of-two-scaled f64 native state to
+avoid the upstream scalar flush below 1e-30. Tiny positive float32 frequencies
+therefore accumulate from zero, subject to ordinary f64 rounding once added to a
+nonzero phase. No artificial minimum musical frequency is imposed. State uses
+the existing native snapshot mechanism. Only identical graph/config/sample-rate
+continuation is tested; PCM contents and the shared resident revision are part
+of that snapshot. No new serialization or cross-schema migration guarantee.
+
+The phase scale is 2^1020 so even f64 `Number.MIN_VALUE` initialization survives
+the native guard. Phase is always wrapped below 1 before scaling, leaving over
+16× finite headroom; advance/multiply/read arithmetic occurs only after unscaling.
+Morph is a float32 control, so its separate 2^128 scale is sufficient and remains
+far from f64 overflow at frame 15. Scaled state is never multiplied by PCM.
+
+## Quality boundaries
+
+Linear cycle interpolation attenuates high harmonics but is not antialiasing.
+High table harmonics fold even with legal fundamental frequency. Morph scanning,
+abrupt replacement, reset and frequency modulation can add bandwidth. There are
+no pitch bands or runtime harmonic rejection in this candidate. Pre-bandlimited
+assets may help static playback; they do not prove modulation is alias-free.
+
+Tests cover 44.1/48/96 kHz, independent periodic interpolation and sine-frequency
+oracles, exact phase/reset/hold, frame 1/length4, wrapped endpoints, missing/short
+assets, revision wrap, max resident, full finite/subnormal/nonfinite PCM and exact
+snapshot continuation. An explicit high-harmonic test preserves the known folded
+alias instead of labeling the source bandlimited. Packed consumer evidence is
+separate from human listening, browser scheduling and hardware real-time proof.
+
+## Optional prepared pitch bands
+
+The same public subpath also exposes an additive host-preparation/native-reader
+candidate. See [prepared pitch bands](./wavetable-bands.md) for its separate layout,
+capacity, transition and quality contracts. The unbanded reader retains the
+separate layout and control contract described above.
+
+The cycle-local interpolation correction also fixes the former loss of tiny phase
+at nonzero frame offsets. A frozen pre-fix fixture records the failing case
+(phase 1e-40, a 0→3e38 ramp, expected 0.48 but formerly 0 in frame 1). Ordinary coherent
+quarter-sample reads remain bit-identical to that fixture; general ordinary-rate
+reads stay within the independent interpolation tolerance. Endpoint-safe convex
+weighting can legitimately improve previous rounding/cancellation at extreme
+PCM. Initial instrument/FX settings are untouched.

package/docs/windowed-pitch-shift.md

@@ -0,0 +1,112 @@
+# Bounded moving-window pitch effect
+
+`windowedPitchShift` from `@denaudio/den/windowed-pitch-shift` is a CANDIDATE
+mono input pitch effect made entirely from the existing unworklet 0.4.1 graph,
+native controls, fixed buffers and snapshots. It changes the read speed of a
+continuously arriving input. It does not reuse or change `dualHeadDelay`.
+
+## Entry and allocation
+
+Instantiate with `sampleRate: ctx.sampleRate` (integer 8000..192000) and optional
+`windowSamples` (even integer 32..16384, default 2048). This fixes the delay-sweep
+width W and allocates W+3 f64 history values, or 8(W+3) bytes excluding native
+driver overhead. No resizing, runtime asset load, FFT or second audio runtime.
+
+Call `tick(input, { ratio, retrigger, reset })` exactly once per sample. It returns
+`{ output, ratioRejected }`. Input must be finite f32; all finite magnitudes,
+including subnormals, are supported through exact binary internal scaling.
+`ratio` is an audio-rate f32 input-time speed in [0.5,2], corresponding to one
+octave down/up. NaN, infinities and adjacent out-of-range f32 values are rejected,
+leaving the last valid ratio unchanged. Initial ratio is 1. There is no implicit
+smoothing or semitone conversion; hosts may compose those explicitly.
+
+## Exact sample law, latency and gain
+
+Before consuming input x[n], let p be the stored phase in [0,1). Read the existing
+history at delays dA=1+Wp and dB=1+W frac(p+1/2), using linear interpolation and
+zero for unavailable history. The A weight is 1-|2p-1|; B uses its exact complement.
+The emitted sample is their weighted sum. Store x[n] after reading, then advance
+p by (1-ratio)/W modulo one. Between head wraps, input time therefore advances
+by `ratio` samples per output sample. A head wraps only at its zero-weight point;
+this does not make arbitrary input, retrigger or parameter edits click-free.
+
+W denotes delay excursion, not a fixed-duration grain or STFT frame. At constant
+nonunity ratio, one head cycle lasts W/|1-ratio| output samples; the other is a
+half-cycle away. A large W lowers that window modulation rate and raises delay.
+Ratio 1 stops phase movement rather than resetting it.
+
+All reads have ages between 1 and W+1 samples. There is no single fixed latency
+for pitch-shifted audio. Initially (or after a phase retrigger), ratio 1 gives an
+exact 1+W/2-sample delay: at default W=2048 this is 1025 samples, about 21.35 ms
+at 48 kHz. Returning to ratio 1 after arbitrary modulation freezes two weighted
+different delays, which can comb-filter or cancel; it is not transparent bypass.
+Mixing with dry audio adds phase coloration. The caller owns mixing and any
+alignment decision; neither a dry tap nor automatic level compensation is hidden.
+
+Both the interpolation and crossfade are convex. Output peak cannot exceed the
+largest absolute retained input sample (up to floating rounding). Once history
+is full, constant input passes at exactly unity gain. There is no feedback. If
+the final nonzero input is at n, output is zero from n+W+2 onward, under every
+ratio/retrigger sequence. An impulse may be repeated, attenuated or skipped.
+
+## Reset, retrigger and state
+
+`reset` has priority. It silences the current sample, discards that input,
+invalidates history without clearing the entire allocation, and holds phase and
+write cursor at zero. Held reset remains silent. The first sample after release
+starts at phase zero with empty history. During reset a valid ratio is accepted;
+an invalid ratio falls back to 1 instead of preserving the pre-reset value.
+
+`retrigger` rephases the current read to zero while retaining existing history
+and the current valid ratio. The sample then advances normally. A held retrigger
+uses the initial midpoint delay every sample, even when ratio is not 1. An
+instantaneous rephase can click; this is an explicit articulation control, not a
+crossfade or automatic note policy.
+
+History, cursor, valid age, phase and last valid ratio are native persistent
+state. The output temporary is transient. Restoration is supported only for the
+same processor, schema, configuration and sample rate; no cross-schema migration
+is provided. Capture rendered native controls, not pending suspended edits.
+
+## Audible limits and verification boundary
+
+Linear interpolation is not a bandlimited resampler. Upward transposition of
+content above sampleRate/(2*ratio) folds across Nyquist; even lower inputs can
+show interpolation images and window sidebands. The two windows can color,
+amplitude-modulate, smear, repeat, skip or cancel material, especially transients
+and tones whose periods do not fit W. Window size and ratio are audible design
+choices, not quality guarantees. There is no formant preservation, transient
+alignment, WSOLA, phase vocoder or general independent duration/time stretching.
+
+The dominant output pitch need not equal ratio times input pitch for undersized
+or noncoherent windows. For example, W=64, ratio=2 and input
+`0.75*cos(2*pi*n/128)` cancel the desired doubled-frequency bin (1/64 cycles per
+sample, measured amplitude about 1.1e-16), while the original-frequency bin
+(1/128 cycles per sample) remains at about 0.608049 amplitude. This measured
+window limitation also means a larger/default W is not a pitch-quality guarantee.
+
+Tests use an independent unbounded absolute-input timeline, analytic coherent
+sinusoid frequency/phase checks, retained cancellation and alias counterexamples,
+endpoint and gain bounds, reset/retrigger and in-flight same-schema continuation
+at 44.1/48/96 kHz offline. The isolated packed consumer checks public declarations,
+native per-sample ratio controls and fixed maximum allocation. Local timing is
+diagnostic only. No browser/hardware realtime deadline, human listening approval
+or golden-audio status follows from these tests.
+
+## Live state and control restoration
+
+Pinned core 0.4.1 copies worklet state before the host restores AudioParam values.
+Restoring saved phase while an old ratio is still rendering can advance that
+phase before unity ratio arrives; unity then holds the changed phase indefinitely.
+For W2048 and an old ratio .5, one 128-sample quantum changes phase by 1/32 and
+read age by 64 samples. A coherent 375 Hz input at 48 kHz therefore changes sign.
+An even gap can coincidentally preserve that particular tone's phase; a passing
+window is not proof of an atomic operation.
+
+The tested browser composition first sets every saved control and confirms it
+rendered, then restores without reset or retrigger. Native telemetry is checked
+exactly and the original complex-phase assertion remains. This caller protocol
+uses the existing native API, not an upstream fix or a general live-restore
+guarantee for arbitrary changing automation/input. Exact same-schema offline
+continuation and the deterministic stale-gap counterexample remain separate
+evidence. See [shared contracts](contracts.md).

package/package.json

@@ -1,6 +1,271 @@
 {
   "name": "@denaudio/den",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Composable DSP modules and instrument/delay engines for unworklet",
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuichkun/den.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE",
+    "docs"
+  ],
+  "exports": {
+    "./character-filter": {
+      "types": "./dist/character-filter.d.ts",
+      "import": "./dist/character-filter.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./gate": {
+      "types": "./dist/gate.d.ts",
+      "import": "./dist/gate.js"
+    },
+    "./envelope": {
+      "types": "./dist/envelope.d.ts",
+      "import": "./dist/envelope.js"
+    },
+    "./lfo": {
+      "types": "./dist/lfo.d.ts",
+      "import": "./dist/lfo.js"
+    },
+    "./oscillator": {
+      "types": "./dist/oscillator.d.ts",
+      "import": "./dist/oscillator.js"
+    },
+    "./instrument": {
+      "types": "./dist/instrument.d.ts",
+      "import": "./dist/instrument.js"
+    },
+    "./delay-fx": {
+      "types": "./dist/delay-fx.d.ts",
+      "import": "./dist/delay-fx.js"
+    },
+    "./delay-settings": {
+      "types": "./dist/delay-settings.d.ts",
+      "import": "./dist/delay-settings.js"
+    },
+    "./filter": {
+      "types": "./dist/filter.d.ts",
+      "import": "./dist/filter.js"
+    },
+    "./voice-policy": {
+      "types": "./dist/voice-policy.d.ts",
+      "import": "./dist/voice-policy.js"
+    },
+    "./delay-readhead": {
+      "types": "./dist/delay-readhead.d.ts",
+      "import": "./dist/delay-readhead.js"
+    },
+    "./instrument-example": {
+      "types": "./dist/instrument-example.d.ts",
+      "import": "./dist/instrument-example.js"
+    },
+    "./state-variable-filter": {
+      "types": "./dist/state-variable-filter.d.ts",
+      "import": "./dist/state-variable-filter.js"
+    },
+    "./biquad-eq": {
+      "types": "./dist/biquad-eq.d.ts",
+      "import": "./dist/biquad-eq.js"
+    },
+    "./crossover": {
+      "types": "./dist/crossover.d.ts",
+      "import": "./dist/crossover.js"
+    },
+    "./formant-bank": {
+      "types": "./dist/formant-bank.d.ts",
+      "import": "./dist/formant-bank.js"
+    },
+    "./dynamics": {
+      "types": "./dist/dynamics.d.ts",
+      "import": "./dist/dynamics.js"
+    },
+    "./drive": {
+      "types": "./dist/drive.d.ts",
+      "import": "./dist/drive.js"
+    },
+    "./modulation-fx": {
+      "types": "./dist/modulation-fx.d.ts",
+      "import": "./dist/modulation-fx.js"
+    },
+    "./stereo-delay": {
+      "types": "./dist/stereo-delay.d.ts",
+      "import": "./dist/stereo-delay.js"
+    },
+    "./reverb": {
+      "types": "./dist/reverb.d.ts",
+      "import": "./dist/reverb.js"
+    },
+    "./source": {
+      "types": "./dist/source.d.ts",
+      "import": "./dist/source.js"
+    },
+    "./resonator": {
+      "types": "./dist/resonator.d.ts",
+      "import": "./dist/resonator.js"
+    },
+    "./modulation": {
+      "types": "./dist/modulation.d.ts",
+      "import": "./dist/modulation.js"
+    },
+    "./performance": {
+      "types": "./dist/performance.d.ts",
+      "import": "./dist/performance.js"
+    },
+    "./sample": {
+      "types": "./dist/sample.d.ts",
+      "import": "./dist/sample.js"
+    },
+    "./wavetable": {
+      "types": "./dist/wavetable.d.ts",
+      "import": "./dist/wavetable.js"
+    },
+    "./virtual-analog": {
+      "types": "./dist/virtual-analog.d.ts",
+      "import": "./dist/virtual-analog.js"
+    },
+    "./spectral": {
+      "types": "./dist/spectral.d.ts",
+      "import": "./dist/spectral.js"
+    },
+    "./convolution": {
+      "types": "./dist/convolution.d.ts",
+      "import": "./dist/convolution.js"
+    },
+    "./frequency-shifter": {
+      "types": "./dist/frequency-shifter.d.ts",
+      "import": "./dist/frequency-shifter.js"
+    },
+    "./lookahead-limiter": {
+      "types": "./dist/lookahead-limiter.d.ts",
+      "import": "./dist/lookahead-limiter.js"
+    },
+    "./multiband-dynamics": {
+      "types": "./dist/multiband-dynamics.d.ts",
+      "import": "./dist/multiband-dynamics.js"
+    },
+    "./musical-examples": {
+      "types": "./dist/musical-examples.d.ts",
+      "import": "./dist/musical-examples.js"
+    },
+    "./curve-shaper": {
+      "types": "./dist/curve-shaper.d.ts",
+      "import": "./dist/curve-shaper.js"
+    },
+    "./oversampled-drive": {
+      "types": "./dist/oversampled-drive.d.ts",
+      "import": "./dist/oversampled-drive.js"
+    },
+    "./dual-head-delay": {
+      "types": "./dist/dual-head-delay.d.ts",
+      "import": "./dist/dual-head-delay.js"
+    },
+    "./mpe-expression": {
+      "types": "./dist/mpe-expression.d.ts",
+      "import": "./dist/mpe-expression.js"
+    },
+    "./windowed-pitch-shift": {
+      "types": "./dist/windowed-pitch-shift.d.ts",
+      "import": "./dist/windowed-pitch-shift.js"
+    },
+    "./spectral-gate": {
+      "types": "./dist/spectral-gate.d.ts",
+      "import": "./dist/spectral-gate.js"
+    },
+    "./prepared-convolution": {
+      "types": "./dist/prepared-convolution.d.ts",
+      "import": "./dist/prepared-convolution.js"
+    },
+    "./loop-crossfade": {
+      "types": "./dist/loop-crossfade.d.ts",
+      "import": "./dist/loop-crossfade.js"
+    },
+    "./resident-recorder": {
+      "types": "./dist/resident-recorder.d.ts",
+      "import": "./dist/resident-recorder.js"
+    },
+    "./freeze-reverb": {
+      "types": "./dist/freeze-reverb.d.ts",
+      "import": "./dist/freeze-reverb.js"
+    },
+    "./resident-time-stretch": {
+      "types": "./dist/resident-time-stretch.d.ts",
+      "import": "./dist/resident-time-stretch.js"
+    },
+    "./pitch-quantizer": {
+      "types": "./dist/pitch-quantizer.d.ts",
+      "import": "./dist/pitch-quantizer.js"
+    },
+    "./spectral-freeze": {
+      "types": "./dist/spectral-freeze.d.ts",
+      "import": "./dist/spectral-freeze.js"
+    },
+    "./filterbank-vocoder": {
+      "types": "./dist/filterbank-vocoder.d.ts",
+      "import": "./dist/filterbank-vocoder.js"
+    },
+    "./live-buffer": {
+      "types": "./dist/live-buffer.d.ts",
+      "import": "./dist/live-buffer.js"
+    },
+    "./live-granular": {
+      "types": "./dist/live-granular.d.ts",
+      "import": "./dist/live-granular.js"
+    },
+    "./spectral-texture": {
+      "types": "./dist/spectral-texture.d.ts",
+      "import": "./dist/spectral-texture.js"
+    },
+    "./spatial-chains": {
+      "types": "./dist/spatial-chains.d.ts",
+      "import": "./dist/spatial-chains.js"
+    },
+    "./musical-controls": {
+      "types": "./dist/musical-controls.d.ts",
+      "import": "./dist/musical-controls.js"
+    }
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "test": "npm run build && vitest run && node --test --test-concurrency=1 tests/*.test.mjs && node --test tests/realtime/*.test.mjs",
+    "prepack": "npm run build",
+    "build:consumer": "node scripts/build-consumer.mjs",
+    "build:integration": "node scripts/build-integration.mjs",
+    "build:site": "node scripts/build-site.mjs",
+    "build:catalog": "node scripts/build-catalog.mjs",
+    "release:version": "node scripts/release-version.mjs",
+    "release:pack": "node scripts/release-pack.mjs",
+    "test:release": "node --test tests/release.test.mjs tests/release-package.test.mjs"
+  },
+  "peerDependencies": {
+    "@unworklet/core": "0.6.0"
+  },
+  "devDependencies": {
+    "@unworklet/core": "0.6.0",
+    "@unworklet/lang": "0.6.0",
+    "@unworklet/offline": "0.6.0",
+    "@unworklet/test": "0.6.0",
+    "@unworklet/unplugin": "0.6.0",
+    "playwright": "1.60.0",
+    "typescript": "5.9.3",
+    "vite": "7.3.6",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}