Skip to content

About

Signal Room: a local PCM16 audio workbench with C-powered gain, normalization, fades, waveform comparison, native playback, and WAV downloads.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Signal Room · Audio Toolkit

A little control. A cleaner signal. A local audio workbench for PCM16 WAV files, powered by a C11 processor.

Compare real before-and-after waveforms, adjust gain, normalize peaks, add linear fades, listen to both versions, and download a processed WAV. The browser and CLI use the same C executable.

Signal Room comparing an original and peak-normalized WAV

Build and run

Requires a C11 compiler, Make, and Python 3.9+. There are no third-party runtime packages, JavaScript build tools, accounts, or API keys.

git clone https://github.com/Ugo175/audio-toolkit.git
cd audio-toolkit
make
python3 server.py

Open http://127.0.0.1:8771. The workbench loads an original generated demo and renders the default preset. Playback is never automatic. Stop the server with Ctrl+C. Use python3 server.py --port 8772 if the default port is occupied.

A one-minute demo

  1. Compare the demo waveforms. The six-second stereo source peaks at approximately −11.8 dBFS; the default Bring it up preset normalizes it near 0 dBFS with short fades and no clamped samples.
  2. Play Original, then Processed. Starting either player pauses the other. Both players initially use half playback volume; this does not change the samples in the downloaded file.
  3. Select Soft edges and render again to see the longer fades.
  4. Keep normalization enabled and raise gain to 4×. Render: the clamped-sample meter and warning show where the level exceeded PCM16 limits.
  5. Return to Bring it up, render, then choose Download WAV. The source file is never overwritten.
  6. Load your own supported WAV using Choose WAV or the drop area. Adjust settings and render to compare it.

See the demo and verification checklist and mobile screenshot.

Controls and measurements

Control Behavior
Gain Multiplies sample level; browser range is 0–4×
Peak normalization Scales the original absolute peak to 32767 before gain
Fade in / out Linear frame envelopes, applied after gain; browser range is 0–10 seconds
Render changes Runs the C processor and refreshes processed playback, waveforms, and meters
Download WAV Saves the current rendered output with a -processed.wav suffix

Changing settings makes the old output stale and disables processed playback and download until another render completes. Presets set controls; they do not silently modify a rendered file.

Waveforms use a fixed ±1 scale and show the minimum and maximum sample across all channels in up to 240 time windows. They are amplitude envelopes, not a sample-accurate editor or a spectral display. The original and processed files use the same scale.

Peak and RMS are unweighted sample measurements across all interleaved channels, relative to 32768. They are not LUFS or true-peak measurements. Silence has no finite dBFS value and displays as −∞. Rounded normalized peaks may display 0.0 dBFS even though the positive target is 32767.

The clamped count comes directly from C. Values outside the signed 16-bit range saturate instead of wrapping around. Saturation can still cause audible distortion; reduce gain to avoid it. Existing full-scale samples in the source are not counted as newly clamped unless processing pushes them outside the range.

Supported files and limits

  • Little-endian RIFF/WAVE, integer PCM16, one format chunk, one nonempty audio-data chunk, and 1–32 interleaved channels.
  • The browser/API accepts files up to 8 MiB. The CLI accepts up to 256 MiB and numeric processing values up to 1,000,000.
  • Other PCM bit depths, float WAV, compressed audio, RF64, and extensible WAV are rejected. MP3, AAC, and FLAC are not converted.
  • RIFF length, chunk bounds/padding, byte rate, and frame alignment are validated by C before analysis.
  • Native browser playback support varies, especially for multichannel audio or unusual sample rates. Processing and downloading can still work when playback is unavailable.
  • Sample rate, channel count, duration, and ancillary chunks are preserved. Ancillary analysis metadata is copied unchanged and is not recomputed.
  • Fades apply the same factor to every channel in a frame. Overlapping fades multiply. A fade longer than the file only traverses part of its ramp. No dithering, EQ, resampling, or limiting beyond saturation is applied.

Privacy and lifecycle

This is a local development app, not a hosted service. The Python server binds to loopback. Browser file data goes only to the local C-processing bridge. Each request uses a temporary directory that is removed after processing. The app has no recording database, browser persistence, or remote audio upload.

WAV bytes and rendered output remain in browser memory until replaced or the page closes; downloaded files remain wherever the browser saves them. Refreshing resets the workbench to its generated demo. The server caches only the original synthesized demo in memory. This server is intended for trusted personal use, not public production hosting.

CLI and batch processing

make
python3 examples/generate_demo.py
./audio examples/studio-sketch.wav louder.wav --gain 1.5
./audio examples/studio-sketch.wav faded.wav --normalize --fade-in 0.15 --fade-out 0.35
python3 batch.py --output-dir processed --normalize examples/studio-sketch.wav
make test

examples/generate.py also provides the original one-second sine-tone example. Both generators refuse to overwrite existing files. The six-second browser demo is an original synthesized chord with amplitude pulses; it contains no downloaded media or copyrighted recording.

CLI output files must not already exist. Batch processing rejects output-name collisions, reports failed inputs, and retains successful outputs if another input fails. Neither the C executable nor the batch script overwrites source files.

Architecture

web/ → local HTTP API → server.py → workbench.py → compiled audio.c
                                                 ↓
                                    metadata, envelopes, level statistics

CLI / batch.py ────────────────────────────────→ compiled audio.c

The Python bridge invokes C using an argument array and temporary files; it does not implement a second gain/fade algorithm. Even inspection passes through C validation via a no-op render. The frontend renders server-provided measurements and plays the exact WAV bytes produced by C. It uses system fonts, native audio controls, and inline waveform SVGs.

The local HTTP server serves a fixed asset list, rejects foreign origins and hosts, limits upload sizes, and sets a content security policy. A production deployment would need an appropriate server, concurrency/resource limits, and an explicit retention policy.

Verification

make test

The 14 tests cover C saturation, normalization, silence, stereo fades, metadata preservation, malformed RIFF data, overwrite protection, batch processing, level/envelope statistics, generated demo validity, browser/CLI byte parity, option validation, and HTTP handling. HTTP tests briefly bind a loopback server.

Browser checks cover real waveform rendering, native playback advancement, mutual playback pause, stale-output protection, clipping feedback, invalid fades, a complete WAV download, mobile layout, and JavaScript errors. See docs/DEMO.md.

Future work

Streaming processing for larger files, additional PCM formats, optional true-peak/loudness measurement, and batch controls in the browser.

Origins

Created by Ugochukwu Igweagu, inspired by the Volume exercise in my CS50 projects collection. This standalone implementation adds RIFF parsing, saturation, normalization, fades, batch processing, a browser workbench, level statistics, and tests. See ATTRIBUTION.md.

About

Signal Room: a local PCM16 audio workbench with C-powered gain, normalization, fades, waveform comparison, native playback, and WAV downloads.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages