Skip to content

protocol.md

Latest commit

 

History

History
57 lines (44 loc) · 2.15 KB

protocol.md

File metadata and controls

57 lines (44 loc) · 2.15 KB
Raw

Wire protocol

All audio is mono float32 in [-1.0, 1.0], little-endian, at the rate in config.SAMPLE_RATE (16 kHz). Two transports share this sample format.

WebSocket streaming — GET /ws/stream

Duplex, one denoised chunk returned per input chunk.

  1. Handshake (client → server, TEXT/JSON): 
    { "chunk_samples": 320, "vad": true }
  2. Ack (server → client, TEXT/JSON): 
    { "ok": true, "sample_rate": 16000, "chunk_samples": 320,
  "enhancer": "spectral-gate", "vad": true }
    On a bad handshake the server replies { "ok": false, "error": "..." } and closes.
  3. Audio (client → server, BINARY): exactly chunk_samples float32 samples (chunk_samples * 4 bytes) per message.
  4. Audio (server → client, BINARY): exactly chunk_samples denoised float32 samples per input chunk. A wrong-sized input gets a TEXT error frame instead.
  5. The client closes the socket (or sends TEXT "bye") to end the stream.

With vad: true the server gates clearly-silent input chunks to zero on output, suppressing residual noise during pauses.

HTTP batch — POST /api/enhance
Request body raw float32 PCM (len % 4 == 0)
Request header X-Sample-Rate: 16000
Response audio/wav (denoised, mono int16 WAV)
Errors 400 if the body is empty or not float32-aligned

Health — GET /health

{ "ok": true, "service": "denoise-stream", "version": "0.1.0",
  "sample_rate_hz": 16000, "chunk_samples": 320, "enhancer": "spectral-gate" }

Raw-TCP framing (protocol.py)

A self-contained length-prefixed format used by the low-level transport and the unit tests. Little-endian throughout:

header  := magic[8 bytes = "DNSTREAM"]  sample_rate[uint32]  chunk_samples[uint32]   (16 bytes)
frame   := num_floats[uint32]  payload[num_floats * 4 bytes]
EOS     := num_floats == 0  (no payload)

The 8-byte magic lets a mismatched endpoint fail fast with a clear error rather than misinterpreting bytes as audio.