# Solo medir

## Qué obtienes

**Measurement** es un contexto sin taxonomía: envías datos de captura y recibes los [indicadores](/docs/es/concepts/results/), por frame y agregados, sin interpretación. Es la vía del [quickstart](/docs/es/start/quickstart/), que la recorre de punta a punta con el SDK, cURL o Python.

Measurement es un protocolo universal en el entorno de pruebas: todos las organizaciones lo tienen, sin asignación que pedir. El Engine de producción aún no lo ofrece ([Tus entornos](/docs/es/start/environments/)). Busca el protocolo Measurement en `GET /catalog/protocols`. Viene con `interpreted: false`, como todo protocolo que se mide pero nunca se interpreta. Si no está en tu lista, tu entorno aún no lo ofrece ([Tus entornos](/docs/es/start/environments/)).

`triggerAnalysis` son dos cosas distintas, y Measurement las trata distinto. En el SDK es una opción de `captureProtocol` (`true` por defecto): el SDK pide la interpretación y, con Measurement, Engine la rechaza con un `409`. Por HTTP es un campo del lote `Final` (ausente vale `false`): Engine lo ignora con Measurement. No hay que renombrar nada: con el SDK pasa `triggerAnalysis: false`, por HTTP puedes omitirlo.

Con el SDK, dos parámetros lo hacen funcionar hoy:

### SDK

```js
import { createProtocolClient } from '@neurologyca/capture'

const client = createProtocolClient({ baseUrl: '/engine', taxonomy: { contextId: 'measurement' } })
const session = await client.captureProtocol({ userProtocolId, protocolMechanicId, source: { type: 'webcam' }, triggerAnalysis: false })
```

`taxonomy: { contextId: 'measurement' }` (Measurement no tiene taxonomía, así que vale cualquier valor) y `triggerAnalysis: false` (no hay nada que interpretar). Desde la 0.29.0, el SDK lo decide solo cuando Engine dice que el protocolo no se interpreta (`interpreted: false`): no envía taxonomía, no pide análisis aunque pases `triggerAnalysis: true` y avisa una vez con `protocol.not-interpreted`. El Engine del entorno de pruebas devuelve `interpreted`; mantén `triggerAnalysis: false` con Measurement de todos modos, que lo mantiene funcionando con un Engine que no lo diga: sin él, el SDK pide un análisis que Engine rechaza con `409 PROTOCOL_NOT_ANALYSED`, y desde la 0.29.0 eso también acaba `complete`. El `contextId` sigue siendo obligatorio en la configuración, aunque Measurement no lo envía. El bucle completo: [Quickstart](/docs/es/start/quickstart/) y [En el dispositivo (tiempo real)](/docs/es/sdk/on-device/).

### HTTP

Por la API HTTP, envías tú los frames; el [Quickstart](/docs/es/start/quickstart/) lo recorre con cURL.

## El protocolo Measurement

Una posición, una mecánica y un step de tipo `measurement_free`, con un mínimo de 6 segundos y sin máximo:

| Posición | Cuándo | Mecánica | Steps |
| --- | --- | --- | --- |
| 1 | En cualquier momento | Measurement | measurement_free (mín 6 s · sin máximo) |

## Una medición, una inscripción

Cada medición es una inscripción y una captura. Una posición con una captura completada no se puede volver a capturar:

```json
{
  "status": 409,
  "body": {
    "code": 409,
    "reason": "POSITION_ALREADY_COMPLETED",
    "message": "This mechanic already has a completed session."
  }
}
```

Para volver a medir a la misma persona, inscríbela otra vez en el mismo protocolo:

### cURL

```bash
UP=$(curl -s -X POST "$ENGINE/user-protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId)
```

### JavaScript

```js
const res = await fetch(`${ENGINE_BASE}/user-protocols`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ user: EXT, protocol: PROTOCOL }),
});
const { userProtocolId } = await res.json();
```

### Python

```python
res = requests.post(
    f"{ENGINE_BASE}/user-protocols",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"user": EXT, "protocol": PROTOCOL},
)
up = res.json()["userProtocolId"]
```

`GET /users/{app_user}/user-protocols` lista las inscripciones de una persona, así encuentras sus mediciones anteriores.

## Cuánto capturar

- El catálogo declara **al menos 6 segundos**. Engine no hace cumplir las duraciones. El SDK avisa por defecto (`step.duration-below-min`) y, con `stepDurations: 'enforce'`, rechaza (`E_STEP_DURATION`): ver [Steps y marcado](/docs/es/sdk/steps/).
- Algunos indicadores necesitan una ventana de señal: solo aparecen pasados unos 5 segundos y, desde entonces, llegan por ventanas, no en todos los frames (uno de cada seis a 30 frames por segundo). Qué frame es el primero cambia de una ejecución a otra, así que nunca esperes un número de frame fijo. En la muestra del quickstart, workload va en pocos de los 300 frames:

```json
{ "framesWithWorkload": 21, "framesTotal": 300 }
```

- Las capturas largas tardan más en cerrarse: se midieron 128 segundos para un step de 5.888 frames. Sondea con una paciencia proporcional.

## Lee los indicadores

Cuando la captura de la posición está completa, el stream envía `results.ready`: con `reason: analysis_not_requested` si ningún lote pidió interpretación, y con `protocol_not_interpreted` si el lote `Final` envió `triggerAnalysis` (ver [Eventos en vivo](/docs/es/concepts/results/#eventos-en-vivo)). Úsalo como señal, y como respaldo sondea `GET /results/{userProtocolId}/{protocolMechanicId}` hasta que el step 1 tenga entradas, como en el paso 6 del quickstart. `aggResults` lleva la media de cada indicador en el step y `rawResults`, el valor por frame. Míralo en el [playground](/playground#flow).

## Sin interpretación

Measurement no tiene interpretación, así que no llames a `POST /analyze` en un flujo de Measurement. Si se llama, Engine responde `409` con `reason: PROTOCOL_NOT_ANALYSED`, antes o después de capturar:

```json
{
  "code": 409,
  "reason": "PROTOCOL_NOT_ANALYSED",
  "hint": "Its indicators are computed and available through GET /results. There is no narrative analysis for this protocol, and retrying will not produce one."
}
```

Engine ignora `triggerAnalysis` con Measurement: no hay interpretación que lanzar. Si lo envías en el lote `Final`, la captura se completa con los mismos indicadores y el stream envía `results.ready`:

```json
{
  "events": [
    "connected",
    "results.ready"
  ],
  "resultsReady": [
    {
      "stepOrder": 1,
      "analysis": false,
      "reason": "protocol_not_interpreted"
    }
  ]
}
```

Sin `triggerAnalysis`, la misma captura acaba con `analysis_not_requested`:

```json
{
  "events": [
    "connected",
    "hci.warning",
    "results.ready"
  ],
  "resultsReady": [
    {
      "stepOrder": 1,
      "analysis": false,
      "reason": "analysis_not_requested"
    }
  ]
}
```

La transcripción está apagada por defecto en Measurement: su único step (`measurement_free`) no es de voz. Si la persona habla y transcribes, Engine guarda el texto y `/results` lo devuelve como el `transcript` del step 1 en `speech` (medido el 2026-11-02; [`speech`](/docs/es/concepts/results/#speech), solo en el Engine del entorno de pruebas). Si no, activa la transcripción solo en protocolos con steps de voz ([En el dispositivo (tiempo real)](/docs/es/sdk/on-device/#transcripción)).

## Baseline

El baseline se recomienda para comparar personas o sesiones, pero no es obligatorio: la inscripción responde con `baselineWarning` y sigue. Ver [Baseline](/docs/es/concepts/baseline/).

## Lo que aún no está

- En diferido, Measurement funciona desde 0.27.0: `triggerAnalysis: false` viaja en el manifiesto y el servicio de procesado no llama a `/analyze`. Desde la 0.29.0, cuando Engine dice `interpreted: false`, el cliente de grabación lo escribe también en el manifiesto (`interpreted: false`, siempre con `triggerAnalysis: false`). Hoy puedes grabar, subir y procesar con el servicio de procesado de Neurologyca, sin desplegar nada ([Diferido (en servidor)](/docs/es/sdk/deferred/)).
- Un kit generado en tu backend: desde `capture-server` 0.20.0, `buildTenantKit` da a Measurement su propio kit, `kind: 'measurement'`, con `taxonomy.contextId: 'measurement'` y un aviso de capturar con `triggerAnalysis: false`; ramifica por `kit.kind` y resuélvelo antes de `admin.enrol` ([Tu backend](/docs/es/sdk/backend/#personas-e-inscripciones-createengineadmin)). `ProtocolSummary.interpreted` dice si un protocolo se interpreta (`false` con Measurement). Lo que no está: un Engine cuyo catálogo no publica `interpreted` sigue haciendo que `buildTenantKit` lance `E_KIT_NO_CONTEXT` con Measurement, como hacen siempre `capture-server` 0.19.0 y anteriores. Ahí, usa el kit de Measurement de la consola (Tu integración › Protocolos › un protocolo › Kit): su `neuro.config.json` lleva `taxonomy.contextId: 'measurement'` y `triggerAnalysis: false`.
