# Steps y marcado

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

`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

`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

`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

`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 a `end()` cuando `stepTiming().minReached` sea `true`;
- 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

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](/docs/es/resources/pitfalls/#pf-media-undeclared)). 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

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_from` dice 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 declares `mediaPid` en él.
- **Un step de respuesta** (`category: 'answer'` o `expectsSpeech: '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.instructions` ni `delivery.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](/docs/es/resources/pitfalls/#pf-question-shown-as-answer) 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

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

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

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

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](#steps-sin-reloj-o-sin-texto) 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:

```js
// 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:

```js
// 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:

```js
// 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
}
```
