Codewave

A code-driven, deterministic engine for cinematic sound effects.

---

codewave is an open-source, AI-free procedural sound design engine for Node.js and TypeScript. It generates rich, layered, cinematic sound effects — whooshes, risers, impacts, rumbles, flybys — entirely through pure digital signal processing and synthesis.

No samples. No external AI or ML models. No browser dependency. Just code.

---

Table of Contents

• Overview
• Core Principles
• Installation
• Local Development
• Quick Start
• API Reference
• Project Architecture
• Issues and Roadmap
• Developer
• License

---

Overview

Sound effects are typically produced by hand in a DAW or pulled from sample libraries — a manual, one-off process that's difficult to automate or version. codewave takes a different approach: sound effects are described as code, composed from primitive building blocks (oscillators, noise, envelopes, filters), and rendered deterministically to an audio file.

This makes sound design scriptable, reproducible, and automatable — usable directly inside content pipelines, build tools, or by an AI agent writing calls to the library on your behalf.

---

Core Principles

A Programmable Medium

Sound effects are defined declaratively in code rather than recorded or hand-edited. Layered soundscapes are built the same way you'd compose a UI or a data pipeline — through readable, composable functions.

Built for Both Humans and AI Agents

The API is designed to be self-explanatory enough for either to use correctly on the first try.

Design choice	Purpose
Plain-English parameters	intensity, weight, reverbMix instead of synthesizer jargon
Complete JSDoc coverage	Every function documents valid ranges and exact parameter behavior
Strict TypeScript types	Enums and interfaces guide correct usage via autocomplete
Sensible defaults	whoosh() alone produces a finished, cinematic result

Deterministic and Exact

• Exact duration — a requested duration of 3.0 seconds always renders to exactly 3.0 × sampleRate samples. Reverb tails and envelope releases are budgeted to fit within that window.
• Zero silent randomness — any pseudo-randomness (e.g. noise generation) uses a deterministic PRNG with a fixed default seed. Output is byte-identical across runs. Variation is only introduced through an explicit, opt-in seed parameter.

The same call with the same parameters produces the same result, every time — a guarantee AI-generated audio cannot offer.

Cinematic Quality by Default

To avoid the thin, harsh character of basic wave generators, professional sound-design technique is built directly into the defaults.

Technique	Effect
Layering	Presets stack multiple noise, texture, and sub-bass layers automatically
Detuned unison	Stacked oscillators are slightly detuned and phase-offset for weight and thickness
Curved automation	Envelopes and sweeps default to eased curves rather than abrupt linear transitions
Soft saturation	A gentle master soft-clip stage (tanh-based) adds analog-style warmth
Reverb send	A Schroeder-style algorithmic reverb places sounds in a sense of physical space

---

Installation

npm install codewave

---

Local Development

git clone https://github.com/ahmadfarooqofficial/code-wave.git
cd code-wave
npm install
npm run build
npm test

npm test runs src/verify.ts, which asserts exact-duration output and byte-identical determinism, and writes reference audio files to test_sfx/.

---

Quick Start

High-Level Presets

import { whoosh, impact } from 'codewave';

const transition = whoosh({
  duration: 1.2,
  intensity: 0.8,
  weight: 0.7,
  reverbMix: 0.25
});
transition.save('test_sfx/whoosh_test.wav');

const explosion = impact({
  duration: 2.5,
  intensity: 0.9,
  weight: 0.8
});
explosion.save('test_sfx/impact.wav');

Composition API — Custom Sound Design

import { SoundDesign, noise, osc, sweep } from 'codewave';

const customSound = new SoundDesign({ duration: 1.5, sampleRate: 44100 })
  .layer('air', noise('pink')
    .filter('bandpass', { freq: sweep(300, 3500, 'easeOut'), q: 1.5 })
    .envelope({ attack: 0.3, decay: 0.8, sustain: 0.1, release: 0.4 })
  )
  .layer('sub', osc('sine', { freq: sweep(120, 50, 'easeOut'), count: 3, detune: 15 })
    .filter('lowpass', { freq: 150 })
    .envelope({ attack: 0.1, decay: 1.0, sustain: 0.1, release: 0.3 })
    .gain(0.7)
  )
  .effect('saturation', { drive: 1.8 })
  .effect('reverb', { mix: 0.25, roomSize: 0.6 })
  .render();

customSound.save('custom_sfx.wav', { bitDepth: 24 });

---

API Reference

whoosh(options?: WhooshOptions): SoundBuffer

Parameter	Default	Description
duration	1.2	Duration in seconds
intensity	0.7	Scales the air filter sweep endpoint (2000–5800 Hz) and master saturation (1.0–2.5)
weight	0.6	Sub-bass layer gain
reverbMix	0.2	Master reverb send level
seed	12345	Seed for the deterministic PRNG

riser(options?: RiserOptions): SoundBuffer

Parameter	Default	Description
duration	3.0	Duration in seconds
intensity	0.8	Highpass sweep ceiling and oscillator detune spread
pitchRange	[80, 480]	Start and end frequency of the oscillator sweep
reverbMix	0.25	Master reverb level

impact(options?: ImpactOptions): SoundBuffer

Parameter	Default	Description
duration	2.0	Duration in seconds
intensity	0.6	Scales distortion drive (1.0–5.0)
weight	0.7	Sub-bass thud volume

rumble(options?: RumbleOptions): SoundBuffer

Parameter	Default	Description
duration	5.0	Duration in seconds
intensity	0.5	Lowpass sweep frequency boundary

jetFlyby(options?: JetFlybyOptions): SoundBuffer

Parameter	Default	Description
duration	2.5	Duration in seconds
intensity	0.7	Doppler pitch-shift speed and depth

ratchet(options?: RatchetOptions): SoundBuffer

Parameter	Default	Description
duration	2.0	Duration in seconds
intensity	0.6	Click-rate sweep boundary (10–40 Hz)
reverbMix	0.15	Reverb send level

---

Project Architecture

src/
├── dsp/
│   ├── wav.ts         # Binary PCM WAV encoder
│   ├── noise.ts       # White, pink, brown noise via Mulberry32 PRNG
│   ├── oscillator.ts  # Sine, square, saw, triangle generators & detuned stacking
│   ├── envelope.ts    # ADSR envelope with easing interpolation
│   ├── filter.ts      # Sweepable biquad lowpass/highpass/bandpass filters
│   └── effects.ts     # Saturation, hard clipping, Schroeder reverb
├── types.ts           # Shared TypeScript interfaces and types
├── sweep.ts           # Sweeping automation generator
├── chain.ts           # Fluent sound-design layer builder
├── engine.ts          # Composition coordinator
├── buffer.ts          # SoundBuffer class wrapping Float32Array
└── verify.ts          # Engine tests and reference WAV generator

---

Issues and Roadmap

Bug reports, questions, and feature or preset requests are welcome via GitHub Issues.

---

Developer

Ahmad Farooq

---

License

MIT License. Copyright (c) 2026 Ahmad Farooq. Free to use, modify, and redistribute in closed- and open-source projects.