Migrating from Engine 1.5
What changes when you move an Engine 1.5 integration to Engine 2, route by route.
What changes in the model
Section titled “What changes in the model”In Engine 1.5 a page opened a session, captured for a while and asked for the interpretation. In Engine 2 a person is enrolled in a protocol, and each capture is one position of it, with a plan of steps (see Protocols). Creating users and enrolling them is your backend’s job.
What stays the same
Section titled “What stays the same”- The API key never reaches the browser: your backend mints tokens and proxies Engine.
- Capture still sends facial geometry, never images.
Route by route
Section titled “Route by route”| Topic | Engine 1.5 | Engine 2 |
|---|---|---|
| Token | POST /token with user, tenant and securityKey: one token per end user |
POST /token with apiKey: one token per key. The end user moves from the token to each request (externalId, enrolment ids) |
| Users | Created on the fly with the first token | Created by your backend with POST /users; externalId is unique per organization |
| What you capture | A free session (POST /session, with its order) |
A position of a protocol the user is enrolled in (POST /user-protocols), identified by userProtocolId and protocolMechanicId, with its plan of steps |
| Taxonomy of the interpretation | Fields in the body of POST /session |
POST /user-protocols/{userProtocolId}/{protocolMechanicId}/context |
| Narrative (voice, depth, language) | In the body of the session | In the user’s profile (POST /users and PATCH /users/{external_id}), plus audience in /analyze |
| Sending frames | POST /process-kpn-emo with sessionId, step = order and baseline |
The same route with userProtocolId, protocolMechanicId and the step of the plan; no baseline flag; featuresMeta on every frame |
| Baseline | A baseline: true session; validity worked out by the client |
Its own route, POST and GET /users/{app_user}/baseline; the server says whether it is valid |
| Results | GET /results/{sessionId} |
GET /results/{userProtocolId}/{protocolMechanicId} (also per step and per enrolment) |
| Interpretation | POST /analyze with sessionId, timeStart, timeEnd |
POST /analyze with userProtocolId, protocolMechanicId, optional step and audience, cached per audience; also POST /analyze/stream |
| Events | GET /stream/{sessionId} |
GET /stream/{userProtocolId}, per enrolment, closed with stream.end and a reason |
| Listing sessions | GET /sessions/ |
GET /user-protocols/{userProtocolId}/{protocolMechanicId}/sessions and GET /users/{external_id}/status |
| Constellation Lite | lite_analysis in the session |
Not part of the public Engine 2 API; ask Neurologyca |
This guide covers the integration, not your data: for existing users and baselines, ask Neurologyca.
If you use the SDK
Section titled “If you use the SDK”| Engine 1.5 SDK | Engine 2 SDK |
|---|---|
createNeuroClient |
createProtocolClient |
defineNeuroCapture |
No component: createProtocolClient and your own screens (Steps and marking) |
siteKeyTokenProvider and the hosted gateway |
Removed: your backend’s proxy adds the token (Your backend) |
narrative |
Rejected with a message: the narrative goes in the user’s profile (POST and PATCH /users/{external_id}), from your backend |
lite_analysis |
Rejected: not part of Engine 2; ask Neurologyca |
contextText |
No equivalent: the only free text the interpretation receives is the transcript (the query phrase still exists) |
interpretationTimeoutMs |
Renamed analyzeTimeoutMs |
triggerAnalysis on the client |
Per capture (captureProtocol) |
| — | A new server package, @neurologyca/capture-server, for creating users, enrolling them and building the kit of a context |
Your proxy grows from the routes of Engine 1.5 to the 13 routes the Engine 2 SDK calls.
What Engine 2 adds
Section titled “What Engine 2 adds”The catalogue, user status and blocking, deletion with confirmation, Measurement, microinterventions, and key scopes. Start with the quickstart.
From 0.25 to 0.27
Section titled “From 0.25 to 0.27”If you already run the previous preview of the Engine 2 SDK (0.25), these are the changes to make, from the changelog of @neurologyca/capture (0.26.0 Breaking and 0.27.0) and of @neurologyca/capture-server 0.9.0. The full list is in SDK changelog.
Breaking
Section titled “Breaking”<neuro-capture>is removed: usecreateProtocolClientorcreateRecordingClient,describeStepand your own screens. What the element did for you (keeping the screen on, thebeforeunloadguard) is now yours: usekeepScreenOnandguardUnload.stop()resolves with the outcome: aCaptureOutcomelive, aRecordingResultwhen recording.RecordingSessionHandleno longer extendsProtocolSessionHandle: usecreateRecordingClient, which needs no cast.- One shape for
E_CONFLICT:e.reasonande.conflict.<field>. - The recording client (
@neurologyca/capture/record) records MP4/H.264 only. - A recording refuses a
captureIdalready stored in the browser (E_CAPTURE_ID_IN_USE). RecordingResulthas a requiredstorage, andProtocolSessionHandlehascaptureIdandstepTiming(): a hand-written test double must add them.CaptureSourcegains{ type: 'frames' }, so an exhaustiveswitchonsource.typestops compiling.- The recordings database moves to version 2: close tabs with an older SDK before recording.
capture.global.jsregisters no tag: the API is onwindow.NeuroCapture.@neurologyca/capture-server0.9.0 requires Node 20.3 or later (engines.nodeis>=20.3).
New or recommended
Section titled “New or recommended”- The browser needs no token: create the client without
getToken(it is now optional), behind your backend’s proxy (createEngineProxy). - Upload recordings with
uploadRecording, the browser half of the contract whose server half iscreateUploadReceiver. stepDurationswarns by default and has an'off'.- From 0.27.0, a
<video>is a full source: its audio reaches transcription (with itssrcset before), its end is the end of the source (source.ended), and you can record it.
From 0.27 to 0.43
Section titled “From 0.27 to 0.43”If you run 0.27, these are the changes to make up to @neurologyca/capture 0.43.0 and @neurologyca/capture-server 0.19.0, from their changelogs (the Breaking of 0.36.0, 0.36.3, 0.38.0, 0.42.0, 0.42.1 and 0.43.0, and the wider type of 0.28.0). The full list is in SDK changelog.
Breaking
Section titled “Breaking”- 0.28.0:
ManifestStep.endedBygains'source', the step that the end of the recorded source closed (a<video>or a stream that finished); before, it said'timer'. An exhaustiveswitchover it needs the new case. - 0.36.0 (kodec 5):
FORWARDED_CODEC_EVENTSno longer listshubert-enabled,hubert-revoked,voice-enabledandvoice-revoked; a listener on them never fires. - 0.36.0 renamed
PlanStep.targetConstellationHciIdtotargetHciIdand 0.36.3 undid it (withProtocolSummary.groupin@neurologyca/capture-server0.14.3): coming from 0.27 the name does not change, but code written against 0.36.0 to 0.36.2 goes back totargetConstellationHciId. - 0.38.0:
stop()no longer generates a second interpretation: it waits for the one Engine stores (up toanalyzeTimeoutMs) and only then callsPOST /analyzeonce, so it can take longer;analyze.progressonly arrives withinterpretation: 'stream'(The outcome). - 0.38.0:
PlanStepgains the requiredexpectsSpeechandpresentationSeconds, andSessionReportgainsinterpretationSource,interpretationModeandstreamDropsDuringWait: code that builds them by hand must add them. - 0.42.0: a
transcribe.selfHost.wasmPathsstring is now a prefix that must end in/, under which your host serves the onnxruntime pair the device asks for (CSP and transcription). - 0.42.0:
createProtocolClientthrowsE_UNKNOWN_OPTIONfor an option it does not know, ascreateRecordingClientalready did: remove any extra key from the config. - 0.42.0:
ProtocolClientHandlegainsprepare,releaseandcacheStatus(andRecordingClientHandle,prepareandrelease),SessionReportgainsstartupandtranscriptionLoad, andCaptureStartErrorgainsstageandreason: a typed test double must add them. - 0.42.1 and 0.43.0:
StartupMessageKeygains'first-frame.timeout-media'and'first-frame.face-reload-failed': aRecord<StartupMessageKey, string>of your own texts must add both. - 0.43.0:
StartupReport.schemais1 | 2andPreparedBlock.prepareIdcan benull. A receiver of startup reports validates schema 2 with@neurologyca/capture-server0.19.0 or later (Startup reports). - 0.43.0 (kodec
5.0.0-rc.14): a source that has already ended when the capture starts fails at once, withCaptureStartErrorandstage: 'source'; pass a live stream or a video that is still playing.
New or recommended
Section titled “New or recommended”client.prepare()andclient.release()(0.42.0) load the models before Start (Prepare before Start), andkeepPrepared(0.43.0) keeps them from one capture to the next (Keep the models between captures).startup,onStartupStageandSTARTUP_MESSAGES(0.42.0) show the startup stage by stage, with caps so it cannot hang (The startup screen).signalincaptureProtocol(0.42.0) cancels a capture while it starts, andcaptureProtocol({ transcribe: false })runs one capture without the microphone on a client configured with transcription.
From 0.43 to 0.45
Section titled “From 0.43 to 0.45”If you run 0.43, these are the changes to make up to @neurologyca/capture 0.45.0 and @neurologyca/capture-server 0.20.1, from their changelogs (0.44.0, 0.45.0, 0.20.0 and 0.20.1). None of them breaks at runtime: what changes is the reading of a 202 and some types that gain required fields. PlanStep.expectsSpeech (0.38.0) and targetConstellationHciId (0.36.3) do not change in this stretch. Coming from an earlier version, first follow From 0.27 to 0.43, whose 0.43.0 is the last breaking release. The full list is in SDK changelog.
Changes to make
Section titled “Changes to make”- 0.44.0:
client.analyze()(oncreateProtocolClientandcreateRecordingClient) resolves toAnalyzeAnswer, which adds the requiredinProgressandretryAfterMstointerpretation,fromCacheandraw: a typed test double that builds its result must add both (inProgress: false, retryAfterMs: nullfor an ordinary answer). - 0.44.0: at the close of a capture, a
202 ANALYSIS_IN_PROGRESSno longer ends withE_INTERPRETATION_TIMEOUT: the SDK waits and asks again (analysis.in-progress) and, if the wait runs out, ends with the newE_ANALYSIS_IN_PROGRESS(recoverable, statustimeout). Code that branches onE_INTERPRETATION_TIMEOUTto say “interpretation pending” must also handleE_ANALYSIS_IN_PROGRESS(Errors), and an exhaustiveswitchoverProtocolErrorCodeneeds the new case. - 0.44.0 and 0.20.0: a
nullinterpretation withinProgress: truemeans “interpreting”, not “none”: checkinProgressbefore treatinginterpretation: nullas final, and ask again afterretryAfterMs(The 202 of the interpretation). - 0.20.0:
AnalyzeResult(analyze()andEngineAdmin.analyze) andAudienceReading(analyzeForAudiences) gain the requiredinProgressandretryAfterMs,ProtocolSummaryand itsgroupgaininterpreted(boolean | null), andTenantKitgainskind('context' | 'measurement'): a typed test double of any of them must add them. - 0.20.0:
buildTenantKitno longer throwsE_KIT_NO_CONTEXTfor Measurement: it giveskind: 'measurement', withtaxonomy.contextId: MEASUREMENT_CONTEXT_IDand a notice to capture withtriggerAnalysis: false. Branch onkit.kindwhere you caughtE_KIT_NO_CONTEXTto fall back to a fixed Measurement configuration (Your backend).
New or recommended
Section titled “New or recommended”credentials(0.45.0) oncreateProtocolClient,createRecordingClientandurlTokenProvider:'include'for a proxy on another origin that decides by your session cookie, withcors: { origins, credentials: true }increateEngineProxyandcapture-server0.20.1, which exposesRetry-Afterto that page (A proxy on another origin).- 0.45.0: an
/analyzeasked again after a202gets only what is left of the wait, so the close ends at most about 10 s pastanalyzeTimeoutMs.