simulate-scene

---
name: simulate-scene
description: Use when the user wants a test signal or a simulated RF environment with no hardware — translate intent into a scene and register it as a persistent simulated device.
---

# Simulate Scene

Create a simulated device whose "on-air" contents you control. This is the no-hardware on-ramp, and a real workflow in its own right: prototype a receiver against known ground truth before going on-air, or reproduce a colleague's scenario without their antenna.

## Method

1. **Translate intent into elements.** Each element is `{kind, freq, amplitude, params}`:
   - `tone` — an unmodulated carrier at `freq`.
   - `fm_tone` — an NBFM voice carrier; `params.mod_freq` is the modulating audio tone (e.g. 1000 for 1 kHz). Renders only when the capture `sample_rate` is a multiple of 100000.
   - `noise` — a noise floor (`freq` ignored).
   - `iq_file` — replay a recorded capture (usually created via transmit, not by hand).
2. **Always add a noise floor.** Include a `noise` element (amplitude ≈ 0.005). A noiseless scene produces analysis artifacts (phantom sidebands) that confuse survey-spectrum.
3. **Register it.** `simulate_scene(device_id, elements)`. The scene is saved to `scenes/<device_id>.yaml` and the device reappears in later sessions — it's a shareable, git-friendly fixture.
4. **Verify the scene is what you intended.** `capture` the device and run survey-spectrum; confirm the signals land where you placed them.

## Judgment

- Keep amplitudes sane: a strong carrier ≈ 1.0, a weaker one ≈ 0.3–0.5, noise ≈ 0.005. Huge dynamic range makes weak signals invisible.
- Place signals comfortably inside the captured band — elements beyond ±45% of the sample rate from the center are skipped at render time.
- Name devices for what they represent (`fm_band`, `ism_test`), since the name becomes the scene filename.