# Cinematic Tutor · Plate 01 (The microphone) · Integration guide
For: the Cinematic Tutor app team. Plate version 1.1.0.
## What you get
| File | What it is |
|---|---|
| `index.html` | The whole plate in one file (about 1.2 MB): 3D, audio engine, fonts. No other files and no internet needed. |
| `host-demo.html` | A reference host. It embeds the plate, drives it the way Mr. Aly would, and logs every message. Open it next to this guide. |
## 1 · Put it on the institute site
Upload `ct-plate01.html` anywhere on the site, served over **HTTPS**. Browsers allow the microphone only on HTTPS (or `localhost`, or a file opened from disk).
To give a plate its own page, link to the file directly.
To embed it in a lesson page:
```html
```
- `allow="microphone"` is required. Without it, "Try your voice" is refused and the plate falls back to the synthesised voice, saying so on screen.
- The plate lays out as a full sheet from about 900 px wide, and as a vertical scroll below that.
- Sound starts only after the student clicks inside the plate. This is a browser rule, and a click in the host page does not count.
## 2 · URL parameters
| Param | Values | Effect |
|---|---|---|
| `mic` | `measure` `dynamic` `ldc` `pencil` `ribbon` `shotgun` | Microphone to open with. The default is `ldc`. |
| `view` | `studio` `cutaway` `field` `exploded` | View to open in. |
| `narration` | `host` | Hides the plate's narration bar, so Mr. Aly speaks instead. Lines are still sent to the host. |
| `tasks` | `off` | Hides the lesson-task panel, if the app shows progress itself. |
| `host` | an origin, e.g. `https://app.example` | Pins the origin the plate sends to and accepts commands from. Use this in production. |
## 3 · The bridge (postMessage)
Everything the plate sends has `source: 'ct-plate'`. Everything it accepts has `target: 'ct-plate'`.
### Plate → host
```js
{ source:'ct-plate', plate:'plate01', version:'1.1.0', type:'ready', manifest:{ title, mics, views, tones, detents, objectives, lines } }
{ ..., type:'narration', id:'proximity', ar:'…', en:'…' } // every line the plate says: give it to Mr. Aly
{ ..., type:'progress', done:['null','proximity'], total:6, complete:false, last:'proximity' }
{ ..., type:'event', name:'mic' | 'null-reached' | 'proximity-entered' | 'proximity-left' | 'clip', data:{ id } }
{ ..., type:'result', id:7, ok:true, value:… } // or ok:false, error:'…'
```
`ready` arrives once the plate has loaded. Wait for it before sending commands.
### Host → plate
```js
frame.contentWindow.postMessage({ target:'ct-plate', id: 7, action:'selectMic', args:['shotgun'] }, plateOrigin);
```
`id` is optional. When it is given, the plate replies with `type:'result'` and the same id.
| action | args | does |
|---|---|---|
| `selectMic` | `id` | Switches the microphone (body, pattern, sound). |
| `setPattern` | `detentId` or `k` (−1…1) | Turns the knob. Only on `ldc`; other mics have fixed patterns and return an error. |
| `setView` | `id` | Changes the view, with its camera move. |
| `placeSource` | `id, r_metres, angle_deg` | Moves `voice`, `guitar` or `noise`. The angle is measured from the mic's front. |
| `rotateMic` | `deg` | Turns the mic on the stage. |
| `setGain` | `dB` (0…36) | Sets the preamp gain. |
| `setTone` | `0` `100` `1000` `8000` | Test tone from the voice position. |
| `mute` / `solo` | `id, on` | Source buttons. |
| `say` | `lineId` or `{ar, en}` | Shows a narration line now. It is echoed back as `narration`. |
| `narration` | `'host'` or `'plate'` | Hides or shows the plate's own narration bar. |
| `sound` | `true` or `false` | Starts or stops audio. Starting may fail until the student has clicked in the plate. |
| `slow` | `true` or `false` | Slow motion. |
| `getState` | none | Returns `{ mic, k, view, yawDeg, gainDb, toneHz, sound, vu, sources[], readings, progress }`. |
| `resetProgress` | none | Clears the student's ticked tasks. |
## 4 · Mr. Aly mode
1. Embed with `?narration=host`.
2. On every `narration` message, have Mr. Aly speak `ar`, using your TTS or his recorded voice. Show `en` as a subtitle if you like.
3. Drive the lesson with commands. `host-demo.html` has the full nine-step script (`STEPS`). Copy it, then retime it to Mr. Aly's real speech durations instead of the fixed waits.
All narration text lives in `manifest.lines`, keyed by id. That is the voice-over script, ready to record once.
## 5 · Lesson tasks and progress
The plate ticks six tasks as the student actually does them: try all six mics, put the noise in a null, use proximity, compare omni, double the distance, turn the shotgun at 8 kHz. Progress is kept in the student's browser (`localStorage`, key `ct-plate01-progress`) and sent to you as `progress`. To record it per student, store it on your side against your own login. The plate never sees or sends personal data.
## 6 · Notes
- This guide's numbers are true of this build. Physics values are tested. Product-like details (voicing, tube length, null depth) are modelled and labelled «تقديري» on the sheet.
- Rebuild from source: `node tools/bundle.mjs ` produces `dist/ct-plate01.html`. `npm run check` runs the 56-assertion physics check.