> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/sdks/backend-sdk/voice/technical_documentation/technical_specifications.md).

# Especificaciones técnicas

## 1. Introducción

**Facephi Voice Service** es un servicio API REST en C++ al que se pueden enviar archivos de audio para su procesamiento y obtener el resultado del proceso de reconocimiento de voz. El servicio ofrece un endpoint para registrar (enroll) una nueva voz, y otro para autenticar una voz.

## 2. Requisitos de hardware

|       | Requisito mínimo                                                   | Requisito recomendado               |
| ----- | ------------------------------------------------------------------ | ----------------------------------- |
| CPU   | 2 núcleos con soporte del conjunto de instrucciones SSE4.2, >=2GHz | 16 núcleos, con soporte de AVX2 ISA |
| RAM   | 4 Gb                                                               | 8 Gb                                |
| Disco | 4 Gb                                                               | SSD 4 Gb                            |
| Red   | 100 Mbps                                                           | 1 Gbps                              |

## 3. Requisitos de software

* Linux x86\_64 (Ubuntu 24.04 o superior) con Docker 24.0 o superior.

o bien

* Windows 10 x64 con Docker 24.0 o superior.

## 4. Requisitos de enrolamiento

Se requieren tres grabaciones del mismo usuario pronunciando una frase secreta, que deben cumplir los siguientes requisitos mínimos:

| Requisitos mínimos para el enrolamiento | Valores  |
| --------------------------------------- | -------- |
| Duración del audio                      | > 700 ms |
| Longitud relativa del habla (\*)        | > 0.55   |
| Relación señal-ruido (SNR) (\*\*)       | > 8 dB   |

*(\*) Longitud relativa del habla = Duración del habla / Duración del audio* *(\*\*) La distancia recomendada al hablante es de 30 cm, una distancia natural al usar un dispositivo de mano*

Durante la grabación solo debe hablar una persona. Para verificar que el enrolamiento fue realizado por una única persona, se comparan las plantillas biométricas individuales generadas a partir de las tres grabaciones.

| Requisitos mínimos para el enrolamiento                                                                                          | Umbral |
| -------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Si la probabilidad de coincidencia es inferior al umbral de similitud, el registro se rechaza y se solicita una nueva grabación. | 0.55   |

## 5. Requisitos de autenticación

| Requisitos mínimos para la autenticación | Valores  |
| ---------------------------------------- | -------- |
| Duración del audio                       | > 700 ms |
| Longitud relativa del habla              | > 0.55   |
| Relación señal-ruido (SNR)               | > 3 dB   |

## 6. Métricas

Existen dos canales habituales en los que se aplica la validación biométrica de voz: a través de micrófonos o de líneas telefónicas.

**Métricas extraídas para el caso de uso de micrófono (nueva versión noctua).**

| Umbral | FAR (%) | FRR (%) |
| ------ | ------- | ------- |
| 0.5    | 0.17    | 3.32    |

## 7. Recomendaciones de seguridad

* Mantén `auth_jwt_secret` en un almacén de secretos o en una variable de entorno inyectada, en lugar de incluirlo directamente en las imágenes del contenedor.
* La autenticación JWT opcional se configura en el arranque desde `config.json` o mediante las variables de entorno `FACEPHI_VOICE_REST_AUTH_*`.
* Los endpoints públicos que permanecen sin autenticación son `GET /api/v1/health`, `GET /api/v1/version` y las peticiones de preflight `OPTIONS`.
* `GET /api/v1/config` nunca expone los ajustes de arranque del JWT y `POST /api/v1/config` no puede modificarlos.

**Métricas extraídas para el caso de uso telefónico.**

| Umbral | FAR (%) | FRR (%) |
| ------ | ------- | ------- |
| 0.5    | 1       | 9.12    |

**FAR** (False Acceptance Rate, tasa de falsa aceptación) es la probabilidad de que el sistema acepte incorrectamente a un impostor como usuario legítimo.

**FRR** (False Rejection Rate, tasa de falso rechazo) es la probabilidad de que el sistema rechace incorrectamente a un usuario legítimo.

## 7. Detección de vida (liveness)

| Requisitos mínimos para la detección de vida                                             | Valores   |
| ---------------------------------------------------------------------------------------- | --------- |
| Longitud del habla para la detección de ataques de repetición (Replay Attack)            | > 1000 ms |
| Longitud del habla para la detección de ataques de clonación de voz (Voice Clone Attack) | > 3000 ms |
| Relación señal-ruido (SNR)                                                               | > 10 dB   |

| Umbrales recomendados para la detección de vida                                      | Umbral |
| ------------------------------------------------------------------------------------ | ------ |
| La validación de vida se considerará exitosa cuando el valor sea superior al umbral. | 0.5    |