# ISR Roadmap

## notify.py — NTFY Loudness Notifications

### Context

Street ambience recorder. Goal: detect notable audio events (speech, thunder,
sustained unusual sounds) in hourly recording files and push a notification via
a self-hosted NTFY server. Generic short events (car horn, passing vehicle)
should be filtered out by a minimum section duration.

### Design decisions

| Topic | Decision |
|---|---|
| Detection | RMS + minimum section duration filter (KISS — no FFT for now) |
| Timing | Configurable: `immediate` / `daily` / `both` |
| Config | `[notify]` section in existing `config.ini` |
| Code structure | `notify.py` imports `analyze_wav` / `analyze_flac` from `web.py` (DRY) |
| Source name | Included in notification body; configurable display name per source |

---

### Config additions (`config.example.ini`)

Add a `[notify]` section to `config.ini`:

```ini
[notify]
enabled              = true
ntfy_url             = https://ntfy.example.com/mytopic   ; full URL incl. topic
mode                 = immediate   ; immediate | daily | both
daily_time           = 08:00       ; HH:MM — used in daily and both modes
debounce_minutes     = 60          ; immediate mode: suppress repeat notifications within this window
min_section_duration = 2.0         ; seconds — sections shorter than this are ignored (filters car horns etc.)
min_sections         = 1           ; number of qualifying sections required to trigger a notification
loudness_threshold   = 0.05        ; RMS 0–1, same scale as web.py analysis threshold
```

Per recording source, add an optional `display_name`:

```ini
[radio1]
type         = stream
url          = http://icecast.example.com:8000/live
display_name = Street mic north   ; shown in notification; defaults to section name [radio1]
```

---

### Notification format

```
Title:  ISR — Notable audio · Street mic north
Body:   radio1_20260427_0300.wav
        3 notable sections (≥ 2.0 s each)
        → 00:12 – 00:18
        → 01:45 – 01:52
        → 47:03 – 47:11
        Peak RMS: 0.312
```

Daily digest example:

```
Title:  ISR Daily Digest · 2026-04-27
Body:   Street mic north — 4 files with notable events
        03:00 file · 3 sections (peak 0.312)
        07:00 file · 1 section  (peak 0.091)
        14:00 file · 2 sections (peak 0.204)
        21:00 file · 1 section  (peak 0.178)
```

---

### Implementation plan

#### Phase 1 — Core

1. **`config.example.ini`** — add `[notify]` section and `display_name` key to
   source section examples (as shown above).

2. **`notify.py` — file watcher**
   - Polls `recordings/status.json` every 30 s.
   - Tracks which files were in `active` on the previous poll.
   - When a file disappears from `active` it was just closed → queues it for
     analysis.
   - Skips files with extensions that cannot be analysed (anything other than
     `.wav` / `.flac`).

3. **`notify.py` — analysis + filter**
   - Imports `analyze_wav` / `analyze_flac` from `web.py`.
   - Applies `loudness_threshold` from `[notify]` config.
   - Filters resulting sections to those with duration ≥ `min_section_duration`.
   - Counts filtered sections against `min_sections` threshold.

4. **`notify.py` — NTFY HTTP POST**
   - Plain `urllib` POST to `ntfy_url` (no extra dependencies).
   - Sets `Title` and message body as described above.
   - Logs success / failure to stdout.

#### Phase 2 — Cadence modes

5. **Immediate mode with debounce**
   - Fires right after the file closes and analysis passes.
   - Persists last-notification timestamp per source to a small
     `notify_state.json` in the recordings directory.
   - Suppresses sending if last notification for that source was within
     `debounce_minutes`.

6. **Daily digest mode**
   - Appends qualifying events to `notify_log.jsonl` in the recordings
     directory (one JSON line per event: timestamp, source, filename, sections,
     peak RMS).
   - On each poll checks whether `daily_time` has passed today and no digest
     has been sent yet (tracked in `notify_state.json`).
   - Reads all undigested entries from `notify_log.jsonl`, groups by
     `display_name`, sends one notification per source with notable activity.
   - Marks entries as digested.

7. **Both mode**
   - Immediate path: only fires when peak RMS exceeds a second, higher
     threshold (`alarm_threshold`, default `0.3`; add to `[notify]` config).
   - Daily digest path: fires for everything that passes `min_sections`.

#### Phase 3 — Integration

8. **Docker** — optional `notify` service in `docker-compose.yml`:
   ```yaml
   notify:
     build: .
     command: python notify.py
     volumes:
       - ./recordings:/app/recordings
       - ./config.ini:/app/config.ini:ro
     restart: unless-stopped
   ```

9. **README** — new section documenting `notify.py` usage, config keys, and
   Docker setup.

---

### Open questions (decide before implementing)

- **Log rotation**: `notify_log.jsonl` grows indefinitely. Options: cap at N
  days (configurable), cap at N MB, or leave cleanup to the user. No decision
  made yet.
- **Multiple NTFY topics per source**: current design uses one global topic.
  If per-source topics are ever needed, `ntfy_url` could be moved to the source
  section and override the global one.
- **FFT / frequency analysis** (future): distinguishing thunder (low rumble,
  50–200 Hz) from speech (300–3000 Hz) from vehicles would reduce false
  positives further. Deferred — requires `numpy` and adds meaningful complexity.