tone-stream

Self-hosted MP3 tone generator & frequency sweep streamer
Built for speaker testing, room acoustics, and audio equipment tuning.

---

Features

• Continuous MP3 stream at /stream.mp3 — works with any media player, browser, or internet radio client
• Frequency sweep — linear, logarithmic, or exponential sweeps across any range (1–20,000 Hz), with configurable duration and looping
• Manual tone generator — sine, square, triangle, sawtooth waveforms with real-time frequency, amplitude, and waveform changes while playing
• Soundboard — 5 slots for audio files (MP3, WAV, FLAC, OGG, up to 50 MB each) with one-click playback
• Channel modes — stereo, mono, left-only, or right-only output for isolated speaker testing
• Master volume — global volume control (0–100%) applied to all sources
• Web UI — dark-themed interface with real-time controls, progress bars, and live state sync via Socket.io
• Settings persistence — all parameters saved to settings.json and restored on restart
• REST API + OpenAPI spec — full programmatic control; openapi.yaml included for RapidAPI, Postman, or code generators

Quick Start

npm install
npm start

Open http://localhost:8080 for the web UI. Stream URL: http://localhost:8080/stream.mp3

To stream to a smart speaker or other device on your network, use your machine's IP address:

# Find your IP
ipconfig getifaddr en0   # macOS (Wi-Fi)
hostname -I              # Linux

Then use http://<your-ip>:8080/stream.mp3 as the stream URL on the device.

Prerequisites: Node.js v18+ and ffmpeg in PATH.

Listening to the Stream

# Browser
open http://localhost:8080/stream.mp3

# ffplay (lowest latency)
ffplay -nodisp -fflags nobuffer -flags low_delay http://localhost:8080/stream.mp3

# mpv
mpv --cache=no http://localhost:8080/stream.mp3

# curl (save to file)
curl http://localhost:8080/stream.mp3 -o recording.mp3

The stream includes ICY metadata headers (icy-name, icy-br, icy-sr) for media player compatibility.

Web UI

Three tabbed panels:

Tab	Description
Sweep	Start/end frequency, duration, sweep type (log/linear/exp), waveform, amplitude, loop. Live progress bar.
Manual Tone	Logarithmic frequency slider, numeric input, waveform, amplitude. All params update in real time.
Soundboard	5 upload slots. Click to play/stop. Progress bar for playback position.

Header controls: master volume, stop-all, listener count, stream URL (click to copy), settings.

Settings

Setting	Default	Range
Bitrate	128 kbps	64–320
Sample Rate	44100 Hz	22050, 44100
Channel Mode	Stereo	stereo, mono, left, right
Buffer Duration	0.5s	0–5s
Chunk Interval	50ms	20–200ms

Changing settings restarts the encoder. Active listeners may experience a brief glitch.

REST API

See openapi.yaml for the full API specification. Import it into Postman, RapidAPI, or use it to generate client SDKs.

Real-time state updates are pushed via Socket.io on the root namespace.

Architecture

Engine (PCM) → Volume → Channel expansion → ffmpeg (MP3) → Connected clients

The server maintains a continuous MP3 stream powered by ffmpeg. Audio engines (tone, sweep, player) generate mono PCM samples mixed into the pipeline. When nothing is playing, silence is streamed. Only one source is active at a time — starting a new source stops the previous one.

A ring buffer holds recent audio so new clients receive a burst on connect for faster playback start.

Known Issues

• VLC: Playback does not work properly for unknown reasons. Use ffplay, mpv, or a browser instead.

Tech Stack

• Node.js + Express
• Socket.io for real-time UI updates
• ffmpeg / libmp3lame for MP3 encoding and audio file decoding

License

MIT