Skip to content
DevLab

Test your integration

Test with deterministic data: your sandbox, a video of yours, synthetic frames for CI, the SDK under a fake camera, forced states and the webhook.

On this page
  1. Your sandbox
  2. The playground in DevLab
  3. Questions, language and transcription
  4. Audience
  5. Going back and forth, and your sessions of the last 24 h
  6. Session length in the playground
  7. The SDK with a video of yours
  8. Synthetic frames for your CI
  9. The SDK in CI, with a fake camera
  10. Forcing states
  11. The webhook, locally

Your test environment is your sandbox (Your environments). Create people with an opaque externalId (the SDK’s createUser generates a UUID) and delete them when you finish with DELETE /users/{externalId} (Engine requires { "confirm": "<externalId>" } in the body; see Privacy). Never test with real people unless they consented.

Playground in the header runs real captures against your organization and shows every call. It has six sections: Measure, Flow, Baseline, Results, Deferred (server-side) and SDK and API (the full map, with what each one has and what you see when something is missing, is in Where everything is). In the playground, a session is what you measure each time you press Measure (Engine’s session for that position, with its steps); a run is the test person DevLab creates and their calls panel, which can gather several sessions.

  • Not signed in, or without a team with an active key, nothing is measured or stored: you see the recorded example. The bar says “Not signed in: nothing is measured or stored” or “No team: nothing is measured or stored”; a team whose key was revoked has its own message, “Your team has no active key”. Sign in, or ask for a team with an active key (Your DevLab account).
  • Context and protocol. In Measure and Deferred you choose what to measure in two steps: Context first (Measurement at the top, each context with its number of protocols) and then Protocol, which lists only that context’s protocols; a context with a single protocol shows it fixed. Changing the context selects its first protocol. The choice is kept only in this browser tab, is the same in both sections and never goes in the URL. In Deferred, a context this environment does not record appears disabled, with the reason, and with a protocol whose kit has no assigned context Record stays disabled, with the reason. With a single context there is no Context control.
  • Source. In Measure and Baseline you choose where the frames come from: Sample video (the default when this DevLab has them), Camera or Synthetic sample. If this DevLab has no sample videos, the playground says so and falls back to the camera when your browser has one, or else to the synthetic sample. The synthetic sample is frames, not video, so it only works through the HTTP API and cannot be recorded in Deferred.
  • Preparing the capture. With a session and an active team, Measure prepares the capture when you enter it (it downloads the face model, and the speech recognition by itself only on a good connection, without data saver and on a screen at least 1024 px wide; being in the cache is not enough) and shows the progress, stage by stage, before you press Measure: the bar says “Ready · press Measure” when it is done. Speech recognition is large (about 160 MB), so when it does not download by itself, the page says it will do it when you press Measure and offers Download now and Cancel download; if the speech recognition stops advancing, Continue without speech carries on without it for that capture. Baseline uses the same prepared face (it leaves the speech for the session); only while a deferred recording is running does it load its own. What is downloaded and from where is in Privacy.
  • Same person, same source. A baseline and the measurements that use it must come from the same person and the same source. If you switch the source of a person already captured, a dialog (“Same person, same source”) asks you to create a new person or keep the source.
  • Limits. In production, each team can have 10 test runs alive at once and each account can create 30 a day (counted by calendar day in UTC). Past either limit DevLab answers playground.limit with a Retry-After. The team limit (10 alive) is freed by deleting: delete one of yours (Delete now), or ask your organization admin to delete others of your team. The daily limit (30) counts every run created today, deleted ones included, so deleting does not help: wait until the Retry-After says (the next UTC midnight). The test people are deleted in Engine after 24 hours. Test environments may allow more runs than production. A run gathers up to 5 sessions (playground.enrol_limit); then choose Person → New.
  • Deferred. Record needs a session, a team with an active key, your organization with deferred processing turned on (Deferred processing) and a processing service that responds, with a protocol whose kit has a context (Measurement always has one). Deferred processing is on for a new organization unless Neurologyca turned it off when creating it; Neurologyca turns it on or off. In a DevLab with recording, with your organization’s deferred processing off, Deferred says “Your organization does not have deferred processing”, explains what it is and shows the recorded example, with no record button. Otherwise you see Preview and the recorded example, with no record button: “The processing service is not responding right now” means try again later; if the page shows no record button at all, this DevLab does not offer recording (an upload then answers uploads.unavailable).
  • Results and downloads. Results shows the counts, one small chart per indicator and a table of the session it shows (by default the latest; see Going back and forth, and your sessions of the last 24 h), with downloads made in your browser; from Measure you get there with Explore the N indicators (HCIs) and their series or with See the indicators in the bar. Results does not show the text of the interpretation. With several steps, you choose the range: Whole session (where it starts), one question, or one step; the tiles, the series, the table and the downloads follow it. Each mean says who gives it: Engine’s for one step, Engine’s session value for the relevant indicators in the whole session, and otherwise the mean of the frames, computed by DevLab. With a question or a step, it also shows the question and What they said. The interpretation is in the result card of Measure and of Deferred: it starts with its summary and, under it, on one line, who the reading was written for and the primary emotion (the Engine catalogue term, in English). The chip of the Measure card says where it stands: Interpreting… while it comes, Interpreted, No interpretation or, with Measurement, Indicators only. If Engine takes longer than the SDK waits for it (E_INTERPRETATION_TIMEOUT, also through the HTTP API when POST /analyze keeps answering 202), the chip says Engine is still interpreting and the card offers Ask for the interpretation again: it asks POST /analyze once; if it is ready it is shown, and if Engine is still on it, the status bar says so and you can ask again in a minute. When it carries a 0 to 100 index (for example wellness_index), the card shows it after that line, with its sentence as it comes; when it does not, Technical data of the response says so. The calls of a run can be downloaded as JSON or as a cURL script. Next to each value, Results and the cards of Measure and Deferred show the Engine key it comes from, with the Response keys switch (on by default); turn it off to hide them. In DevLab’s stable environment, What they said does not appear while speech exists only in the test environment’s Engine.
  • The code. SDK and API shows the code behind each piece (the SDK first), and Download the live starter gives you the whole Measure flow as a zip, without your key (Your kit): it includes the camera view, reading later from your backend and loading the models; the chart, the result tiles and checking the device are copied from Code.

With a protocol that has questions or voice steps, the controls bar of Measure and of Deferred adds up to three controls. Each choice is per protocol, kept only in this browser tab and shared by both sections; none goes in the URL.

  • Questions appears when some step has a question. It opens Questions of each step, with a row per step: a step with one question shows it as is, and in a step with several you choose one, each step a different one (by default, the first not chosen yet; Reset goes back to that). An answer step says which question it answers, and a silent reading step says which step’s question it shows. While you measure or record, the stage shows the question of the open step, in the spoken language: Question on a question step, Answer on an answer step (the question stays, with the step’s own line under it) and Read in silence on a step where the person reads without speaking. On a narrow screen it goes under the stage. If the protocol has more steps than different questions, the playground says “There are more steps than different questions: this protocol cannot be measured this way”. The same choice goes to Engine in each way of integrating: with the SDK, session.step(n).start({ mediaPid }); through the HTTP API, mediaId in each batch; in Deferred, the mediaPid of each step in the manifest. The playground keeps your choice to itself: your kit writes the default choice as media in neuro.config.json and KIT.md lists the options, so you edit it there (Your kit).
  • Spoken language (EN | ES; for screen readers, “Language spoken in the session”) appears when some step has questions or when Transcribe is on. It is the language that is spoken, declared and never detected: it sets the language of the transcription and of the questions the playground shows. The interpretation comes in the language of the page. With the Sample video, which speaks English, it is fixed to EN and disabled (“The sample video speaks English”); with the Camera it starts in the language of the page and you choose it. A wrong language gives a wrong transcript (Known pitfalls).
  • Transcribe is in the menu Capture settings (⚙) of Measure, and is a switch next to Record in Deferred. It is on by default with voice steps; with Measurement you can turn it on, but it starts off because its step is not a voice step. Live, the SDK transcribes on your device (it opens the microphone; with the Sample video it uses the audio of the video) and only the text goes to Engine. In Deferred, the processing service transcribes all the audio of the recording on the server. Engine never transcribes. If an answer step ends without speech (for example, closed right after it opened), Engine can skip the interpretation, and Deferred shows interpretation: not-requested.

With a protocol whose context has audiences, the controls bar of Measure and of Deferred also shows Audience: who the interpretation is written for. The list is the one in your kit for that protocol (the audiences of its context and of its target indicator); the default one is marked “default”, and those set for your organization, “set for your organization”. It starts on the one set for your organization; if there is none, on the default; if the context marks no default, on Not set (no audience is sent: Engine applies its own). With a single audience that is the default, it is shown fixed; without audiences, or with Measurement, it does not appear. Like the other controls, the choice is per protocol, kept only in this tab, shared by both sections and never in the URL.

The playground sets the choice on the test person when enrolling them, with PATCH /users/{externalId} and audience when it differs from the one the person already has (a row in the calls panel, Set the person’s audience); with the default or Not set, it sends audience: null. That is the same field you send in your integration, on POST /users or PATCH /users/{externalId}. The result card then says who the reading was written for: Reading for the audience Engine applied (audience_applied), or Default reading when none was sent. An audience outside your kit answers playground.bad_audience; changing it while a deferred recording of the same person is still being processed answers playground.audience_busy (wait for it, or cancel it in Deferred). The options depend on the target indicator of the kit (taxonomy.hciId): without it, only the audiences of the context are offered.

Going back and forth, and your sessions of the last 24 h

Section titled “Going back and forth, and your sessions of the last 24 h”
  • From Measure to Baseline, and back. If you reach Baseline from Measure (for example, from the dialog that offers to capture the baseline before measuring), a strip says You came from Measure: «Capture the baseline and go back: your Measure setup stays as it is.». While it captures, it says you can go back when the capture ends. When it ends, it says how it went: Baseline ready, Insufficient quality (Engine will still apply it; Measure with this one), Pending or that the capture failed (Measure without baseline). Go back and measure leaves you in Measure with the focus on its Measure button and never starts measuring: you press Measure. If you change the person, how you integrate or the Source, the strip goes away, because Measure is no longer as you left it.
  • From Results to Measure. If you reached Results from Measure, Back to Measure takes you back (with the browser’s Back when the previous entry is Measure).
  • Where what you see comes from. Results opens with a strip that says it: Recorded example (not your session), Your session (running, or ended at a time, with its person and when it is deleted), 13:10 session, for example (one you chose, with Back to the latest) or Restored session.
  • Your sessions of the last 24 h. Signed in and with a team that has an active key, the Session selector of Results opens Your sessions · last 24 h: those of your account, grouped by test person, each with its time, whether it was live (through the SDK or the HTTP API) or deferred, its steps and duration, the baseline, who the reading was written for and whether it was interpreted. The latest is what Results shows without choosing anything: what you last measured in this tab, the session restored on reload or, without either, the recorded example; it follows Measure. With no sessions, or with only one that is already the latest, the selector does not open: it is fixed text. The i explains that playground people are deleted after 24 h, and their sessions with them. If the session you are looking at is deleted (after 24 h, or with Delete now), the status bar says so and Results goes back to the latest or to the recorded example. Only the sessions of your current team appear: if you change teams, the earlier ones do not appear, and they are still deleted after 24 h. A deferred recording still being processed appears as Processing and cannot be chosen until it finishes.
  • What is read again. Choosing a session asks Engine for it again (GET /results), and keeps it only in the tab’s memory: nothing is stored when you close it. DevLab’s server only keeps, per session, the time, the audience, how you integrated and how it ended, with no text (Your DevLab account). The interpretation is only read again if it finished complete or if Engine was still interpreting it when the SDK (or the playground, through the HTTP API) stopped waiting (a 202 shows as «interpreting»), and always with the audience it was written for (audience in the body of POST /analyze, never reAnalyze): that way it comes from Engine’s cache and no new one is generated or charged. Measurement has no interpretation. If the session did not finish complete, or it is not known which audience it was read for (for example, because the person now has another one), Results says the interpretation is not read again here. The counts that come from the calls are only known for the current session, and show as «—» for the others.
  • After a reload. If you reload the page while your test person is still alive, the Measure card says Restoring… and then Restored session: the latest session of that person that can be chosen, read again from Engine, with What they said when Engine returns it. If Engine does not answer, it says Not restored, with Retry. Starting to measure, Person → New or Delete now replace it. A more recent deferred recording still being processed does not count as The latest: the restored one is the latest that already has results, and when that deferred recording finishes it is not restored by itself (choose it in the selector).
  • A protocol replaced by a new version. When a protocol gets a new version, the previous one is archived and leaves your catalogue. If the playground still had it selected, Measure, Deferred and SDK and API say that there may be a new version and that you should reload the page.

The playground limits how long a capture can last, so that a test never runs on forever (with several steps, the Sample video loops while a step stays open):

  • 1 min per step without its own maximum. A step for which the protocol sets no maximum closes by itself at 1 min (or at its minimum, if that is longer), in Measure (through the SDK and through the HTTP API) and in Deferred. While it is open, the foot of the stage says “Closes itself in 18 s · playground limit”, for example. A step with its own maximum keeps it, even when it is longer than 1 min, and shows no notice. Next step (or Stop on the last one) still closes it earlier.
  • 10 min per session. If a protocol can last more than 10 min (adding up the maximum of each step, or 1 min for those without one), Measure and Record are disabled with “In the playground a session can’t go past 10 min; this protocol can last up to 12 min.”, for example. If a session still reaches 10 min with a step open, it is stopped: “The session reached 10 min, the playground’s maximum: it was stopped.” In Deferred, “The recording reached 10 min, the playground’s maximum: it was stopped and not uploaded.” The wait for the results after the last step does not count. Through the SDK, stopping cancels the session in Engine; through the HTTP API it stays open until Engine abandons it.

With the tab in the background, the browser slows down its timers, so a step or a session can close up to about a minute late.

These are rules of the playground, not of Engine or of the SDK: in your integration you decide the durations. The code that SDK and API shows, and the starters, have no such limit.

No camera needed: a <video> of a person who agreed to it is a full source. Give it its src before capturing:

JavaScript
const video = document.querySelector('video')
video.muted = true
video.playsInline = true
video.src = '/fixtures/face.mp4'
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'video', el: video }, onStarted: () => video.play() })

To use the same video across several steps, set loop on the <video> (or rewind it before each step.start()); if the video ends while a step is open, the step closes and the source.ended warning arrives.

Over the HTTP API you can send frames without any browser. The sample capture is synthetic: a generic face mesh, nobody’s face, ten batches for one step. The Quickstart cURL path sends it.

Chrome can feed a video file as the camera. With Playwright:

JavaScript
import { chromium } from 'playwright'
const browser = await chromium.launch({ channel: 'chrome', args: ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream', '--use-file-for-fake-video-capture=face.y4m'] })

The .y4m is yours, of a person who agreed to it; keep it out of git. Use channel: 'chrome', as our own E2E does: a Chromium build without proprietary codecs cannot record H.264, and the deferred mode would fail with E_RECORDER_UNSUPPORTED.

409 PROTOCOL_NOT_ANALYSED: ask POST /analyze for a Measurement capture. E_RESULTS_TIMEOUT: lower outcomeDeadlineMs in the client. E_STEP_DURATION: stepDurations: 'enforce' and a step shorter than its minimum. E_RECORDER_UNSUPPORTED: record in Firefox, which does not record MP4/H.264. Upload errors: stop your receiver (E_UPLOAD_NETWORK) or return false from checkManifest (the receiver answers 403; E_UPLOAD_REJECTED).

Sign a synthetic event with your webhook secret and post it to your route (the contract). The signature format is documented there.