#!/usr/bin/env python3 """Generate and curate quiet, speech-free office background-audio candidates. The output is for listening review only. It deliberately does not overwrite the production ``full_duplex_white_noise`` cache or encode Qwen hidden states. """ from __future__ import annotations import argparse import hashlib import json import math import wave from pathlib import Path from typing import Any import numpy as np SAMPLE_RATE = 16_000 DEMAND_RECORD = { "title": "DEMAND: Diverse Environments Multichannel Acoustic Noise Database", "doi": "10.5281/zenodo.1227121", "url": "https://zenodo.org/records/1227121", "license": "CC BY-SA 3.0", } def _dbfs(value: float) -> float: return 20.0 * math.log10(max(float(value), 1e-12)) def _audio_stats(samples: np.ndarray) -> dict[str, float]: return { "rms_dbfs": _dbfs(np.sqrt(np.mean(np.square(samples), dtype=np.float64))), "peak_dbfs": _dbfs(np.max(np.abs(samples), initial=0.0)), } def _fade(samples: np.ndarray, sample_rate: int, seconds: float = 0.04) -> None: count = min(int(round(seconds * sample_rate)), samples.size // 2) if count <= 0: return ramp = np.linspace(0.0, 1.0, count, endpoint=False, dtype=np.float64) samples[:count] *= ramp samples[-count:] *= ramp[::-1] def _normalize_quietly( samples: np.ndarray, target_rms_dbfs: float, max_peak_dbfs: float = -12.0, ) -> np.ndarray: value = np.asarray(samples, dtype=np.float64).copy() value -= np.mean(value) _fade(value, SAMPLE_RATE) rms = float(np.sqrt(np.mean(np.square(value), dtype=np.float64))) if rms <= 1e-12: raise ValueError("Cannot normalize silent audio") scale = (10.0 ** (target_rms_dbfs / 20.0)) / rms peak = float(np.max(np.abs(value), initial=0.0)) if peak > 0.0: scale = min(scale, (10.0 ** (max_peak_dbfs / 20.0)) / peak) return np.clip(value * scale, -1.0, 1.0).astype(np.float32) def _spectral_noise( rng: np.random.Generator, count: int, *, exponent: float, low_hz: float, high_hz: float, ) -> np.ndarray: frequencies = np.fft.rfftfreq(count, d=1.0 / SAMPLE_RATE) spectrum = rng.normal(size=frequencies.size) + 1j * rng.normal( size=frequencies.size ) safe_frequency = np.maximum(frequencies, 1.0) color = safe_frequency ** (-0.5 * exponent) high_pass = 1.0 - np.exp(-np.square(frequencies / max(low_hz, 1.0))) low_pass = np.exp(-np.power(frequencies / max(high_hz, 1.0), 4.0)) spectrum *= color * high_pass * low_pass spectrum[0] = 0.0 value = np.fft.irfft(spectrum, n=count) std = float(np.std(value)) if std <= 1e-12: raise RuntimeError("Generated degenerate spectral noise") return value / std def _slow_modulation( count: int, *, frequency_hz: float, depth: float, phase: float, ) -> np.ndarray: time = np.arange(count, dtype=np.float64) / SAMPLE_RATE return 1.0 - depth + depth * np.sin( 2.0 * np.pi * frequency_hz * time + phase ) def _base_office_air( rng: np.random.Generator, count: int, *, low_weight: float, ) -> np.ndarray: air = _spectral_noise( rng, count, exponent=0.8, low_hz=35.0, high_hz=6_000.0, ) duct = _spectral_noise( rng, count, exponent=1.5, low_hz=20.0, high_hz=1_200.0, ) return (1.0 - low_weight) * air + low_weight * duct def _tone( count: int, frequency_hz: float, amplitude: float, phase: float, ) -> np.ndarray: time = np.arange(count, dtype=np.float64) / SAMPLE_RATE return amplitude * np.sin(2.0 * np.pi * frequency_hz * time + phase) def _keyboard_events( rng: np.random.Generator, samples: np.ndarray, event_count: int, ) -> None: if samples.size < SAMPLE_RATE: event_count = min(event_count, 2) low = int(0.15 * SAMPLE_RATE) high = max(low + 1, samples.size - int(0.15 * SAMPLE_RATE)) for position in rng.integers(low, high, size=event_count): duration = int(rng.uniform(0.012, 0.028) * SAMPLE_RATE) end = min(int(position) + duration, samples.size) length = end - int(position) if length <= 0: continue time = np.arange(length, dtype=np.float64) / SAMPLE_RATE envelope = np.exp(-time / rng.uniform(0.0025, 0.0055)) click = rng.normal(size=length) * envelope click += 0.45 * np.sin( 2.0 * np.pi * rng.uniform(900.0, 2_200.0) * time ) * envelope samples[int(position) : end] += rng.uniform(0.08, 0.16) * click def _procedural_candidate( kind: str, *, seed: int, duration_seconds: float, target_rms_dbfs: float, ) -> np.ndarray: rng = np.random.default_rng(seed) count = int(round(duration_seconds * SAMPLE_RATE)) phase = float(rng.uniform(0.0, 2.0 * np.pi)) if kind == "quiet_hvac": value = _base_office_air(rng, count, low_weight=0.62) value *= _slow_modulation( count, frequency_hz=0.055, depth=0.08, phase=phase ) value += _tone(count, 50.0, 0.010, phase) elif kind == "desk_fan": value = _base_office_air(rng, count, low_weight=0.48) value *= _slow_modulation( count, frequency_hz=0.13, depth=0.12, phase=phase ) value += _tone(count, 83.0, 0.030, phase) value += _tone(count, 166.0, 0.012, phase * 0.7) elif kind == "computer_fans": value = _base_office_air(rng, count, low_weight=0.34) value += _tone(count, 218.0, 0.018, phase) value += _tone(count, 273.0, 0.010, phase * 0.5) value *= _slow_modulation( count, frequency_hz=0.037, depth=0.06, phase=phase ) elif kind == "aircon_cycle": value = _base_office_air(rng, count, low_weight=0.70) cycle = 0.72 + 0.28 * ( 0.5 + 0.5 * np.sin( 2.0 * np.pi * 0.021 * np.arange(count, dtype=np.float64) / SAMPLE_RATE + phase ) ) value *= cycle value += _tone(count, 100.0, 0.014, phase) elif kind == "sparse_keyboard": value = _base_office_air(rng, count, low_weight=0.42) _keyboard_events( rng, value, event_count=max(3, int(round(duration_seconds * 0.7))), ) else: raise ValueError(f"Unknown procedural candidate: {kind}") return _normalize_quietly(value, target_rms_dbfs) def _read_pcm16_mono(path: Path) -> np.ndarray: with wave.open(str(path), "rb") as handle: if ( handle.getframerate() != SAMPLE_RATE or handle.getnchannels() != 1 or handle.getsampwidth() != 2 or handle.getcomptype() != "NONE" ): raise ValueError(f"Expected mono PCM16 {SAMPLE_RATE} Hz WAV: {path}") raw = handle.readframes(handle.getnframes()) return np.frombuffer(raw, dtype=" None: path.parent.mkdir(parents=True, exist_ok=True) pcm = np.round(np.clip(samples, -1.0, 1.0) * 32767.0).astype(" float: return float(np.mean(_speech_decisions(samples), dtype=np.float64)) def _speech_decisions(samples: np.ndarray) -> np.ndarray: try: import webrtcvad except ImportError as exc: raise RuntimeError( "Real recordings require `python -m pip install webrtcvad-wheels` " "for conservative speech screening." ) from exc pcm = np.round(np.clip(samples, -1.0, 1.0) * 32767.0).astype(" tuple[list[tuple[int, int]], dict[str, Any]]: """Return long, unmodified spans that stay away from every VAD hit. A production source may use one returned span, but it must never join two spans. The margin is deliberately applied before splitting so a source cannot graze a suspicious transient at either boundary. """ decisions = _speech_decisions(samples) frame_samples = int(round(0.03 * SAMPLE_RATE)) forbidden = np.zeros(samples.size, dtype=np.bool_) margin = max(int(round(float(margin_seconds) * SAMPLE_RATE)), 0) for frame_index in np.flatnonzero(decisions): start = max(int(frame_index) * frame_samples - margin, 0) end = min((int(frame_index) + 1) * frame_samples + margin, samples.size) forbidden[start:end] = True minimum = max(int(round(float(minimum_seconds) * SAMPLE_RATE)), 1) segments: list[tuple[int, int]] = [] start = 0 while start < forbidden.size: while start < forbidden.size and forbidden[start]: start += 1 end = start while end < forbidden.size and not forbidden[end]: end += 1 if end - start >= minimum: segments.append((start, end)) start = end + 1 return segments, { "vad_frame_seconds": 0.03, "vad_mode": 3, "vad_frame_count": int(decisions.size), "vad_positive_frames": int(decisions.sum()), "vad_positive_ratio": float(decisions.mean()) if decisions.size else 0.0, "vad_margin_seconds": float(margin_seconds), "minimum_segment_seconds": float(minimum_seconds), } def _sha256(path: Path) -> str: digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest() def _save_candidate( output_dir: Path, filename: str, samples: np.ndarray, metadata: dict[str, Any], ) -> dict[str, Any]: path = output_dir / filename _write_pcm16_mono(path, samples) record = { "filename": filename, "path": str(path.resolve()), "sample_rate": SAMPLE_RATE, "duration_seconds": samples.size / SAMPLE_RATE, **_audio_stats(samples), **metadata, } record["sha256"] = _sha256(path) return record def generate_candidates( output_dir: Path, *, duration_seconds: float, seed: int, demand_root: Path | None, ) -> list[dict[str, Any]]: if duration_seconds <= 0: raise ValueError("duration_seconds must be positive") output_dir.mkdir(parents=True, exist_ok=True) records: list[dict[str, Any]] = [] procedural_specs = [ ("quiet_hvac", -40.0), ("desk_fan", -38.0), ("computer_fans", -40.0), ("aircon_cycle", -38.0), ("sparse_keyboard", -38.0), ] for offset, (kind, target_dbfs) in enumerate(procedural_specs): samples = _procedural_candidate( kind, seed=seed + offset, duration_seconds=duration_seconds, target_rms_dbfs=target_dbfs, ) records.append( _save_candidate( output_dir, f"synthetic_{kind}_{target_dbfs:.0f}dbfs.wav", samples, { "family": "procedural", "kind": kind, "seed": seed + offset, "target_rms_dbfs": target_dbfs, "speech_screen": "speech-free by construction", }, ) ) if demand_root is not None: real_specs = [ ("OOFFICE_ch01.wav", 10.0, -40.0), ("OOFFICE_ch01.wav", 180.0, -40.0), ("OHALLWAY_ch01.wav", 10.0, -40.0), ("OHALLWAY_ch01.wav", 160.0, -40.0), ] count = int(round(duration_seconds * SAMPLE_RATE)) for source_name, start_seconds, target_dbfs in real_specs: source_path = demand_root / source_name source = _read_pcm16_mono(source_path) start = int(round(start_seconds * SAMPLE_RATE)) excerpt = source[start : start + count] if excerpt.size != count: raise ValueError( f"DEMAND excerpt is too short: {source_path} at {start_seconds}s" ) ratio = _speech_ratio(excerpt) if ratio > 0.005: raise RuntimeError( f"Rejected possible speech in {source_name} at " f"{start_seconds:.1f}s: VAD ratio={ratio:.3%}" ) samples = _normalize_quietly(excerpt, target_dbfs) stem = Path(source_name).stem.lower() records.append( _save_candidate( output_dir, ( f"real_demand_{stem}_{int(start_seconds):04d}s_" f"{target_dbfs:.0f}dbfs.wav" ), samples, { "family": "DEMAND", "source_file": str(source_path.resolve()), "source_start_seconds": start_seconds, "target_rms_dbfs": target_dbfs, "webrtc_vad_mode": 3, "speech_frame_ratio": ratio, "source_record": DEMAND_RECORD, }, ) ) return records def generate_production_sessions( output_dir: Path, *, synthetic_duration_seconds: float, seed: int, demand_root: Path, vad_margin_seconds: float, minimum_real_session_seconds: float, ) -> list[dict[str, Any]]: """Build long source-local tracks; no file contains a loop or splice.""" if synthetic_duration_seconds < 450.0: raise ValueError( "Production synthetic sessions must cover the longest HFD source; " f"got {synthetic_duration_seconds:.3f}s, expected at least 450s" ) output_dir.mkdir(parents=True, exist_ok=True) records: list[dict[str, Any]] = [] procedural_specs = [ ("quiet_hvac", -40.0), ("desk_fan", -38.0), ("computer_fans", -40.0), ("aircon_cycle", -38.0), ("sparse_keyboard", -38.0), ] for offset, (kind, target_dbfs) in enumerate(procedural_specs): samples = _procedural_candidate( kind, seed=seed + offset, duration_seconds=synthetic_duration_seconds, target_rms_dbfs=target_dbfs, ) records.append( _save_candidate( output_dir, f"synthetic_{kind}_{int(synthetic_duration_seconds)}s.wav", samples, { "family": "procedural", "kind": kind, "seed": seed + offset, "target_rms_dbfs": target_dbfs, "speech_screen": "speech-free by construction", "continuous": True, "looped": False, "spliced": False, }, ) ) for source_name in ("OOFFICE_ch01.wav", "OHALLWAY_ch01.wav"): source_path = demand_root / source_name source = _read_pcm16_mono(source_path) segments, vad_report = _speech_free_segments( source, margin_seconds=vad_margin_seconds, minimum_seconds=minimum_real_session_seconds, ) for segment_index, (start, end) in enumerate(segments): samples = _normalize_quietly(source[start:end], -40.0) stem = source_path.stem.lower() records.append( _save_candidate( output_dir, ( f"real_demand_{stem}_safe{segment_index:02d}_" f"{start / SAMPLE_RATE:06.2f}s-" f"{end / SAMPLE_RATE:06.2f}s.wav" ), samples, { "family": "DEMAND", "source_file": str(source_path.resolve()), "source_start_seconds": start / SAMPLE_RATE, "source_end_seconds": end / SAMPLE_RATE, "target_rms_dbfs": -40.0, "speech_screen": "WebRTC VAD mode 3 with excluded margins", "continuous": True, "looped": False, "spliced": False, "source_record": DEMAND_RECORD, **vad_report, }, ) ) window_samples = int(round(0.6 * SAMPLE_RATE)) stride_samples = int(round(0.4 * SAMPLE_RATE)) for record in records: sample_count = int(round(float(record["duration_seconds"]) * SAMPLE_RATE)) record["sample_count"] = sample_count record["window_count"] = ( 0 if sample_count < window_samples else (sample_count - window_samples) // stride_samples + 1 ) record["key"] = f"sessions/{Path(record['filename']).stem}" record["relative_path"] = f"sessions/{record['filename']}" return records def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--output-dir", type=Path, required=True) parser.add_argument("--duration-seconds", type=float, default=20.0) parser.add_argument("--seed", type=int, default=260730) parser.add_argument( "--production-sessions", action="store_true", help=( "Generate long, non-looped production tracks instead of short " "listening-review excerpts." ), ) parser.add_argument("--vad-margin-seconds", type=float, default=1.0) parser.add_argument("--minimum-real-session-seconds", type=float, default=20.0) parser.add_argument( "--demand-root", type=Path, default=None, help="Optional directory containing OOFFICE_ch01.wav and OHALLWAY_ch01.wav.", ) return parser.parse_args() def main() -> None: args = parse_args() if args.production_sessions: if args.demand_root is None: raise ValueError("--production-sessions requires --demand-root") records = generate_production_sessions( args.output_dir, synthetic_duration_seconds=args.duration_seconds, seed=args.seed, demand_root=args.demand_root, vad_margin_seconds=args.vad_margin_seconds, minimum_real_session_seconds=args.minimum_real_session_seconds, ) manifest_path = args.output_dir / "session_manifest.json" manifest_path.write_text( json.dumps( { "format": "hfd_continuous_background_sessions_v1", "status": "production", "sample_rate": SAMPLE_RATE, "window_seconds": 0.6, "stride_seconds": 0.4, "session_count": len(records), "sessions": records, }, ensure_ascii=False, indent=2, ) + "\n", encoding="utf-8", ) print( f"[ready] Generated {len(records)} continuous production sessions: " f"{args.output_dir}" ) print(f"[ready] Manifest: {manifest_path}") return records = generate_candidates( args.output_dir, duration_seconds=args.duration_seconds, seed=args.seed, demand_root=args.demand_root, ) manifest_path = args.output_dir / "candidate_manifest.json" manifest_path.write_text( json.dumps( { "status": "listening review only; not used by training", "candidate_count": len(records), "candidates": records, }, ensure_ascii=False, indent=2, ) + "\n", encoding="utf-8", ) print(f"[ready] Generated {len(records)} review candidates: {args.output_dir}") print(f"[ready] Manifest: {manifest_path}") if __name__ == "__main__": main()