code-HFD / scripts /data /generate_office_background_candidates.py
Tinghong-Ye22's picture
Add files using upload-large-folder tool
9fc9873 verified
Raw History Blame Contribute Delete
20.9 kB
#!/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="<i2").astype(np.float32) / 32768.0
def _write_pcm16_mono(path: Path, samples: np.ndarray) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
pcm = np.round(np.clip(samples, -1.0, 1.0) * 32767.0).astype("<i2")
with wave.open(str(path), "wb") as handle:
handle.setnchannels(1)
handle.setsampwidth(2)
handle.setframerate(SAMPLE_RATE)
handle.writeframes(pcm.tobytes())
def _speech_ratio(samples: np.ndarray) -> 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("<i2")
frame_samples = int(0.03 * SAMPLE_RATE)
vad = webrtcvad.Vad(3)
decisions = []
for start in range(0, pcm.size - frame_samples + 1, frame_samples):
decisions.append(
vad.is_speech(pcm[start : start + frame_samples].tobytes(), SAMPLE_RATE)
)
return np.asarray(decisions, dtype=np.bool_)
def _speech_free_segments(
samples: np.ndarray,
*,
margin_seconds: float,
minimum_seconds: float,
) -> 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()