# CreatorStudio Suite — Overview

**CreatorStudio is a complete passenger-announcement platform for public transit.** One team authors
what the whole fleet says — the stops, the connections, the safety and service messages — in a visual
web app, presses **Publish**, and every vehicle immediately speaks and displays the right thing at the
right moment, in the right language, with a tamper-evident record of what each passenger actually heard.

It replaces per-vehicle programming and vendor-locked hardware workflows with **one authoring tool, one
always-on engine, and open standards** (MQTT PIS-PT in; ADT audio + LED/TFT sign frames out). It runs in
the cloud for a whole operator or as a single container **on the vehicle** — same software either way.

---

## What it does — at a glance

| | |
|---|---|
| 🎧 **Author** | Build announcements as *playlists* — spoken text, live variables (`{nextStop}`, `{connectingServices}`…), pauses and audio clips — in a browser. A worked example library ships to start from. |
| ⚡ **Trigger** | 33 built-in transit triggers (approaching / arrived / departing, doors, stop request, detour, disruption, last stop…) plus **custom fact-based triggers** over 40 live journey facts, universal prerequisite gates (door / stop-button / speed) and **geofence zones** you draw on a map. |
| 🗣️ **Speak** | Neural text-to-speech from **Azure, ElevenLabs or Acapela** (swap suppliers without re-authoring), ~50 voices across a dozen languages, per-line voice and bilingual "also speak in". |
| ▦ **Show** | Author full **LED sign templates** (layouts · displays · vehicle faces) that match the Luminator **MatrixRenderer** Presentation Schema — Text / Image / Rectangle, scroll, blink, colour rules, symbols — then render interior LED, exterior front/side/rear and TFT live, in real **FNT** fonts, as mono or **RGB Mobitec FF** frames — or **Hanover HCPS/SuperX** frames for Hanover panels. Sign control is **vendor-independent**: one render pipeline, a protocol adaptor per sign vendor. The same trigger that speaks can override which layout each face shows. |
| 🧾 **Prove** | A durable, tamper-evident **proof-of-play** audit trail: what was *dispatched* vs what the vehicle *confirmed it played*, where and when — exportable as signed evidence for accessibility (ADA) compliance. |
| 🖥️ **Operate** | A live fleet cockpit: heading-up map, per-vehicle event feed, sign previews, performance/health telemetry, and a route simulator to test announcements before they reach a bus. |

---

## The suite — how the pieces fit

```mermaid
flowchart LR
  CREATOR["🎨 Suite — Creator<br/>Authoring: playlists, LED signs, triggers, voices <i>(same app)</i>"]
  SUPA[("☁️ Azure PostgreSQL + Blob<br/>Config store + live notify · shared MP3 cache")]
  TTS["🗣️ TTS cloud<br/>Azure AI Speech · Acapela · ElevenLabs"]
  FEED["🛰️ Fleet journey data<br/>Live PT-PIS trip data, one stream per vehicle"]
  BROKER{{"📡 MQTT broker<br/>The integration hub — topics are the API"}}
  ENGINE["⚙️ Suite — Engine<br/>Trigger + audio + matrix LED pipeline <i>(same app)</i>"]
  DASH["🖥️ Web dashboard<br/>Monitor cockpit · diagnostics · proof · history"]

  subgraph VEHICLE["On the vehicle"]
    direction TB
    VEH["🔊 Vehicle player<br/>Go · Python · browser<br/>→ loudspeaker · interior/exterior LED signs"]
    PAX["📱 Passenger information app<br/>Onboard live screen — current &amp; next stop,<br/>route &amp; destination <i>(browser /player)</i>"]
  end

  CREATOR -->|"publish config"| SUPA
  SUPA -->|"live sync ~1 s"| ENGINE
  ENGINE <-->|"synthesize (cached)"| TTS
  FEED -->|"journey data"| BROKER
  BROKER -->|"PIS data"| ENGINE
  ENGINE -->|"audio + LED"| BROKER
  BROKER -->|"announcements"| VEH
  BROKER -->|"passenger info"| PAX
  DASH <-->|"monitor + control"| BROKER
```

- The **MQTT broker is the integration hub — the topics *are* the API.** Everything talks through it: the live PT-PIS journey feed comes in, the Engine's audio + LED frames go out to the vehicles, and the dashboard rides the same topics to monitor and control the fleet.
- On the vehicle, the **Passenger information app** (the browser `/player`) shows riders the live journey — current and next stop, route and destination — while the **vehicle player** (headless Go/Python, or the same browser page) makes the sound and drives the interior/exterior LED signs. Both render straight from the broker's topics; nothing else needs installing.
- **CreatorStudio** (authoring — playlists, **LED signs**, triggers, voices, and the route simulator) and the **Web dashboard** (one Monitor cockpit with the map, the fleet feed and the live sign previews in a drawer, plus diagnostics, proof of play and history) are browser apps sharing one design system — and one portal, which also publishes the **Documentation Center**.
- The **Engine** turns the trip feed into audio and matrix sign frames (Luminator MatrixRenderer-compatible layouts, real FNT fonts, mono/RGB Mobitec FF **and** Hanover HCPS/SuperX — sign-vendor independent) and reads its config live from **Azure PostgreSQL** (`pg_notify`/LISTEN) — a *Publish* hot-swaps the fleet in ~1 s with no redeploy. Voices are synthesized once via the **TTS cloud** and cached fleet-wide.

## How an announcement happens

From a live trip signal to sound on the bus and pixels on the signs — one pass through the engine:

```mermaid
flowchart TB
  FEED["🛰️ Live PIS-PT trip data<br/>{tenant}/{vehicleId}/pis/0/#"]
  subgraph ENGINE["CreatorStudio Engine"]
    direction TB
    CTX["VehicleContext<br/>merge topics → journey state"]
    ENG["Trigger engine<br/>edge-detect · debounce · gates"]
    PIPE["Pipeline<br/>trigger → playlist(s) · LED layouts · priority"]
    REND["Render<br/>resolve {variables} → MP3 + matrix frames"]
  end
  CACHE[("MP3 cache<br/>one synth per phrase, fleet-wide")]
  TTS["☁️ TTS supplier"]
  AUDIO["🔊 vehicle player"]
  SIGNS["▦ interior + exterior LED<br/>FNT · FF mono/RGB"]
  PROOF["🧾 proof-of-play"]

  FEED --> CTX --> ENG -->|"approaching-stop · doors-open · detour…"| PIPE --> REND
  REND <-->|"key = hash(text + voice)"| CACHE
  CACHE -.->|"miss → synthesize"| TTS
  REND --> AUDIO
  REND --> SIGNS
  REND --> PROOF
  AUDIO -.->|"ack when the clip finishes"| PROOF
```

Only **state-changing** signals wake the trigger engine (the high-frequency GNSS firehose is gated),
identical phrases are synthesized **once for the whole fleet** and reused from the cache, and the
played-ack closes the loop so the audit records what a passenger actually *heard* — not just what was
dispatched. Sign faces resolve through the same trigger: a firing trigger can override the layout on
each vehicle face; otherwise the bound **Display** cycles pick the active layout from live journey state.

---

## Customer benefits

- **Accessibility compliance you can prove.** Every announcement and sign change is recorded — dispatched
  vs vehicle-confirmed, with location, timestamp and transcript — and exportable as a signed proof pack.
  When a regulator or a rider asks "did the stop get announced?", you have the evidence.
- **One tool for the whole fleet.** Author once, Publish once; the change reaches every vehicle instantly
  over the air. No per-vehicle programming, no field visits, no re-flashing signs.
- **No vendor lock-in on voices.** Compare Azure, ElevenLabs and Acapela side-by-side and switch suppliers
  without touching a single announcement. ~50 neural voices, a dozen languages, bilingual stops.
- **Resilient by design.** TTS retries, a circuit breaker and fallback audio keep the fleet talking when a
  supplier wobbles; if the cloud is unreachable the engine keeps running on the last-known-good config.
- **Scales without re-work.** Identical phrases are synthesized once and reused fleet-wide, so cost and
  latency stay flat as vehicles are added — thousands of vehicles from one engine.
- **Deploy anywhere.** Run it centrally for an operator, or as a single hardened container **on the
  vehicle** (multi-arch, non-root) for on-board autonomy — the same software, your choice.
- **A better passenger experience.** Clear spoken announcements plus a live, branded passenger information
  screen (current/next stop, countdown, a personal "getting off at" alert) that works on any device.
- **Signs as first-class content.** Design destination and interior LED layouts the same way you design
  playlists — visual editor, trigger-driven cycles, Ultima vehicle roster — and ship them as the same
  MatrixRenderer / Mobitec FF content the Luminator Suite already understands. Sign hardware is
  **vendor-independent**: the identical rendered pixels also drive **Hanover** LED destination signs
  (HCPS/SuperX graphic frames), so mixed Luminator + Hanover fleets run from one pipeline.

---

## Where to go next

This documentation is ordered high-level first, then progressively deeper into the technical detail:

1. **[Screens & Features](#screens-features)** — a visual tour of every screen and what it does.
2. **[Functional Specification](#functional-specification)** — what the system does, in requirement-level detail (actors, use cases, functional & non-functional requirements, data model).
3. **[Architecture](#architecture)** — how it's built: backend/client architecture, software design, interfaces, the runtime sequence, performance and security.
4. **[Scaling](#scaling)** — the numbers and the knobs behind "thousands of vehicles from one engine".
5. **[On-Vehicle Deployment](#on-vehicle-deployment)** — running the engine as a container on the bus.
6. **[Setup & Reference](#setup-reference)** — install, configure, run and deploy (developer/operator reference).