Steps y marcado
Cómo conducir cada step sin componente: sus datos, quién lo cierra, el reloj, la comprobación de duraciones, el media que enseñaste y el manifiesto de una grabación.
No hay componente de captura: tu página dibuja cada step y decide cuándo termina. El SDK te da los datos y comprueba las duraciones.
Los datos de un step
Sección titulada «Los datos de un step»describeStep(step, { lang }) lee un step del plan sin reglas por tipo.
| Campo | Qué es |
|---|---|
StepFacts.minSeconds |
La duración mínima del step, o null si el catálogo no la dice |
StepFacts.maxSeconds |
La duración máxima del step, o null |
StepFacts.responseClock |
El valor del catálogo, que el SDK no interpreta ('paused', 'running', otro valor o null; es null en muchos tipos de step). Decide qué significa por protocolo |
StepFacts.expectsSpeech |
Si el step espera que la persona hable: 'yes', 'no', 'any' o null; 'yes' marca un step de respuesta (abajo) |
StepFacts.text |
El texto que mostrar, { value, lang, mediaPid }, o null |
StepFacts.texts |
Todos los textos del step, con su mediaPid y un cuerpo por idioma |
StepFacts.phases |
Las fases del step, si las tiene |
StepFacts.rounds |
El número de rondas, o null |
StepFacts.bands |
Las bandas de tiempo del step, si las tiene |
StepFacts.unknown |
Lo que el catálogo no dijo: 'duration', 'text', 'responseClock', 'bands' |
El idioma: el que pidas y, si no, el del plan por defecto.
Quién cierra un step
Sección titulada «Quién cierra un step»run({ durationMs }) lo cierra pasado ese tiempo (un tope). start() y end() te dejan cerrarlo a ti: empieza el step y llama a end() con lo primero que ocurra entre tu botón, maxSeconds o el final de tu vídeo (el aviso source.ended). El orden es estricto: un step cada vez, en el orden del plan (E_STEP_SEQUENCE). start() devuelve una promesa: espérala con await. En vivo se resuelve al instante (o rechaza al llamarla); al grabar también puede rechazar más tarde. Solo un orden incorrecto (StepSequenceError) se lanza de forma síncrona; lo demás llega como una promesa rechazada, que un try/catch sin await no atrapa.
El reloj
Sección titulada «El reloj»session.stepTiming() devuelve null fuera de un step, o un StepTiming:
| Campo | Qué es |
|---|---|
StepTiming.elapsedMs |
Milisegundos desde que empezó el step |
StepTiming.minMs |
El mínimo, en milisegundos, o null |
StepTiming.maxMs |
El máximo, en milisegundos, o null |
StepTiming.minReached |
Si el mínimo ya pasó; null si no hay mínimo |
StepTiming.maxReached |
Si el máximo ya pasó; null si no hay máximo |
StepTiming.remainingMs |
Milisegundos que quedan hasta el máximo, o null |
Habilita tu botón cuando minReached no sea false, y pinta remainingMs como cuenta atrás.
La comprobación de las duraciones
Sección titulada «La comprobación de las duraciones»stepDurations en el cliente: 'warn' (por defecto) avisa cuando un step termina fuera de su ventana (step.duration-below-min, step.duration-above-max); 'enforce' lo rechaza con E_STEP_DURATION; 'off' no comprueba nada. Con 'enforce':
- un
run({ durationMs })fuera de rango se rechaza antes de abrir el step; - un
end()antes del mínimo se rechaza y el step sigue abierto: vuelve a llamar aend()cuandostepTiming().minReachedseatrue; - pasado el máximo,
end()solo avisa: cerrar el step es cosa tuya; - con una fuente
<video>o stream que ya terminó,'enforce'baja a'warn', porque ya no queda nada que esperar.
Los avisos tienen 250 ms de tolerancia. Sin mínimo ni máximo no se comprueba nada.
El media que enseñaste
Sección titulada «El media que enseñaste»Declara el texto que mostraste con mediaPid, una vez por step: start({ mediaPid }) o run({ durationMs, mediaPid }). Cuando el step tiene un texto, facts.text.mediaPid es ese. Cuando tiene varios (preguntas alternativas), elige uno de describeStep(step).texts, que lista cada media de texto como { mediaPid, body }: facts.text es solo el primero que casa con el idioma, así que tomarlo sin mirar es adivinar. Un step con varias medias y sin mediaPid avisa step.media-undeclared, y a la interpretación le falta la pregunta (metadata.missing_inputs incluye question_text; mira la trampa). El aviso solo salta en steps sin fases: en un step con fases las medias de texto son las pautas de cada fase, no preguntas alternativas, y no hay nada que elegir. Un mediaPid que no es del step lanza E_MEDIA_UNKNOWN.
Steps sin reloj o sin texto
Sección titulada «Steps sin reloj o sin texto»Un step sin reloj o sin texto propio no es un step de respuesta por defecto. Nunca decidas su papel por el nombre del tipo de step ni por responseClock: lo dice el catálogo. Qué enseña cada step:
- Su media: el texto que declaras con
mediaPid(arriba). - Sin media propia:
delivery.media_fromdice de dónde sale su texto.'previous_step': mantén en pantalla la pregunta del step anterior.'next_step': un step de lectura en silencio enseña la pregunta elegida para el step siguiente; presta el texto, nunca la media, así que no declaresmediaPiden él. - Un step de respuesta (
category: 'answer'oexpectsSpeech: 'yes') mantiene en pantalla la pregunta anterior y enseña su propia media como la línea de debajo (salvo que el step anterior sea una lectura en silencio de la pregunta de este mismo step: entonces su propia media, una vez). Cualquier otro step no es de respuesta: no lo enseñes como «responde ahora». - Enseña solo los cuerpos de las medias, nunca
delivery.instructionsnidelivery.prompt.
StepFacts lleva expectsSpeech, pero hoy no category ni media_from: léelos del step del plan en session.plan.steps (PlanStep.category, y media_from dentro de PlanStep.delivery, que StepDelivery no tipa). Está pedido al SDK. La trampa da el síntoma.
Cuando el catálogo no da duración (unknown incluye 'duration'), cuánto dura el step es decisión tuya: ciérralo con tu botón y anota la decisión por protocolo.
El marcado en diferido: el manifiesto
Sección titulada «El marcado en diferido: el manifiesto»Al grabar, el SDK escribe un manifiesto junto al vídeo. Cada ManifestStep dice dónde empieza y termina el step en el vídeo y quién lo terminó:
| Campo | Qué es |
|---|---|
ManifestStep.startMediaMs |
Dónde empieza el step en el vídeo, en milisegundos |
ManifestStep.endMediaMs |
Dónde termina el step en el vídeo, en milisegundos |
ManifestStep.mediaPid |
El media que declaraste para el step |
ManifestStep.endedBy |
Cómo se cerró: 'timer' (run()), 'gesture' (end()) o, desde 0.28.0, 'source' (lo cerró el fin de la fuente: un fichero o un stream que terminó, esperara run() o end()). El tipo admite también 'media' y 'cap', que la Guía no documenta. El procesador no lo lee |
Y el resto del manifiesto:
| Campo | Qué es |
|---|---|
RecordingManifest.prerollMs |
El pre-roll grabado antes del primer step |
RecordingManifest.stopMediaMs |
Dónde termina la grabación en el vídeo |
RecordingManifest.hidden |
Cuándo estuvo oculta la pestaña durante la grabación |
RecordingManifest.orientationChanges |
Los cambios de orientación del dispositivo |
RecordingManifest.audioGaps |
Los huecos del audio |
RecordingManifest.videoGaps |
Los huecos del vídeo |
RecordingManifest.stimulus |
El tiempo del estímulo de vídeo, si lo seguiste |
RecordingManifest.interpreted |
Desde 0.29.0: false cuando Engine dijo que el protocolo no se interpreta (Measurement), y ausente en otro caso. Solo va con triggerAnalysis: false, y el replay del servicio de procesado tampoco envía taxonomía ni pide análisis |
El pre-roll y el post-roll son opciones de grabación (prerollMs, postrollMs), no campos del manifiesto. Si muestras un estímulo de vídeo, session.trackStimulus(order, el) registra su tiempo. El manifiesto aún no está congelado: lee solo estos campos.
Ayudantes
Sección titulada «Ayudantes»Desde @neurologyca/capture/helpers: keepScreenOn (la pantalla sigue encendida), guardUnload (pregunta antes de cerrar la pestaña mientras corre una captura o una subida), classifyMediaError (convierte un error de cámara en un motivo que puedes mostrar), waitForPortraitOrientation y startOrAsk (ante un POSITION_RESERVED pregunta a la persona, y repite con discardPending: true solo con su sí; desde 0.29.0, si quien tiene la posición ya está recibiendo frames, holder.receivingPackets: true, no pregunta: Engine rechazaría el descarte, así que vuelve a lanzar el POSITION_RESERVED, y lo intentas más tarde). keepScreenOn y classifyMediaError siguen la documentación pública de los navegadores. guardUnload depende del navegador: en Chrome para Android, al cerrar la pestaña no sale el diálogo, así que no cuentes con él para retener una captura en el móvil. Al grabar, lo que te protege ahí es la copia local: en la visita siguiente, listPendingRecordings() devuelve las grabaciones que no se subieron (como RecordingResult); sube cada una con uploadRecording o descártala con su release(). En vivo, una pestaña cerrada acaba la captura: vuelve a capturar.
Lo que el SDK no hace con un plan
Sección titulada «Lo que el SDK no hace con un plan»Las mecánicas con flowMode: 'free' (microintervenciones) no están soportadas (E_FLOW_UNSUPPORTED), las fases no se conducen y no hay interrupciones: las gestiona tu página.
El mismo bucle, en vivo y grabado
Sección titulada «El mismo bucle, en vivo y grabado»Los bloques de esta página se publican tal cual se ejecutan, así que sus comentarios están en inglés. Qué enseña cada step sale de stepPrompt, la regla de la sección de arriba y del playground: la pregunta (text), la línea de debajo en un step de respuesta (cue), kind ('question', 'answer' o 'silent') y el mediaPid que declarar. Enseña «responde ahora» solo cuando kind es 'answer'. Lee category y media_from del step del plan, porque StepFacts no los lleva:
// What each step shows, from the plan: its own question; without one, the previous step's (media_from 'previous_step')// or the next step's text (media_from 'next_step', a silent reading step: it lends the text, never the media).// An answer step (category 'answer' or expectsSpeech 'yes') keeps the previous question on screen, its own media under it.// Only media bodies, never delivery.instructions or delivery.prompt.import { describeStep } from '@neurologyca/capture/record' // the light entry: it does not download kodec
/** * @typedef {{ kind: 'question' | 'answer' | 'silent', text: string | null, cue: string | null, mediaPid: string | null }} StepPrompt * @param {import('@neurologyca/capture/record').PlanStep[]} steps session.plan.steps * @param {number} order the step to show * @param {Record<string, string>} choice the mediaPid you chose per step order; absent, the step's first text * @param {string} lang the spoken language * @returns {StepPrompt | null} mediaPid: what to declare in start({ mediaPid }), null when the step has no media of its own */export function stepPrompt(steps, order, choice, lang) { const sorted = [...steps].sort((a, b) => a.order - b.order) const at = sorted.findIndex((s) => s.order === order) if (at < 0) return null const step = sorted[at], prev = sorted[at - 1], next = sorted[at + 1] /** @param {import('@neurologyca/capture/record').PlanStep} s */ const pidOf = (s) => choice[String(s.order)] ?? describeStep(s).texts[0]?.mediaPid ?? null /** @param {import('@neurologyca/capture/record').PlanStep} s */ const own = (s) => { const body = describeStep(s).texts.find((t) => t.mediaPid === pidOf(s))?.body return body ? (body[lang] ?? body.en ?? Object.values(body)[0] ?? null) : null } /** @param {import('@neurologyca/capture/record').PlanStep} s */ const isAnswer = (s) => s.category === 'answer' || s.expectsSpeech === 'yes' const from = step.delivery?.media_from // not in StepFacts today: read it from the plan step /** @type {StepPrompt['kind']} */ const kind = isAnswer(step) ? 'answer' : from === 'next_step' && step.expectsSpeech === 'no' ? 'silent' : 'question' const mine = own(step) if (mine === null) { const lent = from === 'previous_step' && prev ? stepPrompt(steps, prev.order, choice, lang)?.text ?? null : from === 'next_step' && next ? own(next) : null return lent === null ? null : { kind, text: lent, cue: null, mediaPid: null } } // Not after a next_step reading step: that one already showed this step's own question. if (isAnswer(step) && prev && !isAnswer(prev) && prev.delivery?.media_from !== 'next_step') { const question = stepPrompt(steps, prev.order, choice, lang)?.text ?? null if (question !== null) return { kind, text: question, cue: mine, mediaPid: pidOf(step) } } return { kind, text: mine, cue: null, mediaPid: pidOf(step) }}En vivo, un botón cierra cada step cuando alcanza su mínimo, y su máximo lo cierra solo:
// The step loop, live: a button closes each step once its minimum is reached, and its maximum closes it on its own.// stepPrompt (step-prompt.js) says what each step shows: the question, and on an answer step the question kept on screen.import { stepPrompt } from './step-prompt.js'
/** * @param {import('@neurologyca/capture').ProtocolClientHandle} client * @param {{ userProtocolId: string, protocolMechanicId: string }} pair from your backend * @param {HTMLButtonElement} next your "Next" button * @param {(p: import('./step-prompt.js').StepPrompt | null, remainingMs: number | null) => void} show your screen * @param {{ choice?: Record<string, string>, lang?: string }} [o] the question chosen per step, the spoken language */export async function captureSteps(client, pair, next, show, { choice = {}, lang = 'en' } = {}) { const session = await client.captureProtocol({ ...pair, source: { type: 'webcam' } }) const steps = session.plan.steps for (const step of steps) { const prompt = stepPrompt(steps, step.order, choice, lang) await session.step(step.order).start({ mediaPid: prompt?.mediaPid ?? null }) // settles at once when live await new Promise((/** @type {(v?: unknown) => void} */ done) => { const tick = setInterval(() => { const t = session.stepTiming() next.disabled = t?.minReached === false // enabled once the minimum is reached show(prompt, t?.remainingMs ?? null) // "answer now" only when prompt.kind is 'answer' if (t?.maxReached) finish() }, 250) const finish = () => { clearInterval(tick); next.onclick = null; done() } next.onclick = finish }) await session.step(step.order).end() } return session.stop() // CaptureOutcome}Grabado, los steps se marcan en el vídeo y el manifiesto dice dónde empieza y termina cada uno:
// The same loop, recorded: the steps are marked in the video, and the manifest says where each one starts and ends.import { createRecordingClient, uploadRecording } from '@neurologyca/capture/record'import { stepPrompt } from './step-prompt.js'
/** * @param {{ userProtocolId: string, protocolMechanicId: string }} pair from your backend * @param {HTMLButtonElement} next your "Next" button * @param {(p: import('./step-prompt.js').StepPrompt | null) => void} show your screen */export async function recordSteps(pair, next, show) { const recorder = createRecordingClient({ baseUrl: '/engine', taxonomy: { contextId: 'measurement' }, stepDurations: 'warn' }) const session = await recorder.captureProtocol({ ...pair, source: { type: 'webcam' }, triggerAnalysis: false }) const steps = session.plan.steps for (const step of steps) { const prompt = stepPrompt(steps, step.order, {}, 'en') show(prompt) await session.step(step.order).start({ mediaPid: prompt?.mediaPid ?? null }) // can reject when recording await new Promise((done) => { next.onclick = () => { next.onclick = null; done(undefined) } }) await session.step(step.order).end() } const recording = await session.stop() // the video and its manifest, kept in this browser until uploaded console.log(recording.manifest.steps.map((s) => [s.order, s.startMediaMs, s.endMediaMs, s.endedBy])) return uploadRecording(recording, { url: '/uploads' }) // your receiver}