# Platphorm Sonify - Complete Documentation

> Real-time robot sonification tool. Backend events become ambient lofi music.

## Overview

Platphorm Sonify is a web application that converts robot fleet events into a
real-time ambient lofi music stream. Built with Next.js and Tone.js, it
provides a WebAudio-based sonification engine with 6 sound modules:

1. Lofi Beat - Reactive boom-bap at 75 BPM (degrades with low system health)
2. Ambient Pad - Jazz chord progressions (shifts major/minor with health)
3. Sub Bass - Rolling bass line (follows chord mode)
4. Rhodes Keys - FM synthesis electric piano (mood-aware voicings)
5. Robot Events - Event-triggered sounds (coin drops, warnings, noise bursts)
6. Vinyl Crackle - Ambient texture (louder when health is low)

## System Health

The system maintains a global health score (0.0 to 1.0) that affects all modules:

- Health > 0.6: Bright, clean sound. Cyan visualizer. Major keys.
- Health 0.3-0.6: Warm/amber. Filter cuts highs. Minor keys introduced.
- Health < 0.3: Red/harsh. Bitcrushed beat. Full minor mode. More crackle.

Health adjustments:
- LOGIN: +0.05
- TASK_START: +0.03
- TASK_END (success): +0.02
- LOGOUT: -0.08
- E_STOP/EMERGENCY: -0.15
- TASK_CANCELLED: -0.06
- Bad goto_outcome: -0.06
- Natural decay: trends toward 0.7 over time

## API Reference

### POST /api/events

Send robot events to trigger sounds. Accepts a single event object or an array.

Request body:
```json
{
  "robot_id": "xap035",
  "event_type": "TASK_START",
  "time": "2026-01-19 18:48:30",
  "task_id": "b98843f3-3629-4f1a-a52e-fec620fb45fe",
  "destination": "Charge 7",
  "badge_code": "Charge 7",
  "duration_sec": 0,
  "goto_outcome": ""
}
```

Response:
```json
{
  "success": true,
  "count": 1,
  "total": 15,
  "latestSeq": 42
}
```

### GET /api/events

Query parameters:
- after_seq (integer) - Return events with sequence > N (cursor-based polling)
- all (string "1") - Return all stored events
- limit (integer, max 100, default 50)

Response:
```json
{
  "events": [...],
  "latestSeq": 42,
  "total": 15
}
```

### DELETE /api/events

Clears all stored events.

### GET /api/health

Returns service health status, version, and uptime.

### GET /api/docs

Returns OpenAPI 3.1 specification as JSON.

## Event Types

### Good Events (coin sounds, health boost)
| event_type | Sound | Health Delta |
|---|---|---|
| LOGIN | 7-note ascending coin cascade with shimmer | +0.05 |
| TASK_START | 3-layer coin (attack + body + shimmer tail) | +0.03 |
| TASK_END (no bad outcome) | Warm FM bell | +0.02 |

### Bad Events (degraded sounds, health damage)
| event_type / goto_outcome | Sound | Health Delta |
|---|---|---|
| LOGOUT | Exponential pitch drop (powering down) | -0.08 |
| E_STOP, EMERGENCY, FAULT | Double metallic hit + noise burst | -0.15 |
| TASK_CANCELLED, ERROR | Detuned DuoSynth warning | -0.06 |
| goto_outcome: INACTIVE | Warning tone | -0.06 |
| goto_outcome: ABORTED | Warning tone | -0.06 |
| goto_outcome: ABORTED_VIA_TOUCHSCREEN | Warning tone | -0.06 |
| goto_outcome: CANCELLED, FAILED | Warning tone | -0.06 |

## Polling Architecture

The client uses sequence-based cursor polling:
1. On play start, seeds cursor to current latestSeq (no replay of old events)
2. Polls GET /api/events?after_seq=N every 2 seconds
3. Only new events (seq > cursor) are passed to the sound module
4. Each event plays exactly once, never replayed

## Integration

### MCP Events
Events can be sourced from https://mcp.platphormnews.com

### Webhooks
POST events to /api/events from any webhook-capable system.
Supports batch sending (array of events) for efficiency.

## Discovery

- RSS: /rss.xml (RSS 2.0), /feed.xml (Atom)
- Sitemap: /sitemap.xml
- Robots: /robots.txt
- OpenAPI: /api/docs
- LLM: /llms.txt (summary), /llms-full.txt (this file), /llms-index.json
- JSON-LD: Embedded in page HTML
- Well-known: /.well-known/security.txt

## Organization

- Parent: https://platphormnews.com
- Organization: https://platphormnews.com
- MCP: https://mcp.platphormnews.com