> 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/docs.facephi-pt-br/sdks/backend-sdk/voice/technical_documentation/technical_specifications.md).

# Especificações técnicas

## 1. Introdução

**Facephi Voice Service** é um serviço API Rest em C++ ao qual podem ser enviados arquivos de áudio para seu processamento e obter o resultado do processo de reconhecimento de voz. O serviço oferece um Endpoint para registrar (enroll) uma nova voz, e outro para autenticar uma voz.

## 2. Requisitos de hardware

|       | Requisito mínimo                                               | Requisito recomendado              |
| ----- | -------------------------------------------------------------- | ---------------------------------- |
| CPU   | 2 núcleos com suporte ao conjunto de instruções SSE4.2, >=2GHz | 16 núcleos, com suporte a AVX2 ISA |
| RAM   | 4 Gb                                                           | 8 Gb                               |
| Disco | 4 Gb                                                           | SSD 4 Gb                           |
| Rede  | 100 Mbps                                                       | 1 Gbps                             |

## 3. Requisitos de software

* Linux x86\_64 (Ubuntu 24.04 ou superior) com Docker 24.0 ou superior.

ou bem

* Windows 10 x64 com Docker 24.0 ou superior.

## 4. Requisitos de enrolamento

São necessárias três gravações do mesmo usuário pronunciando uma frase secreta, que devem cumprir os seguintes Requisitos mínimos:

| Requisitos mínimos para o enrolamento | Valores  |
| ------------------------------------- | -------- |
| Duração do áudio                      | > 700 ms |
| Comprimento relativo da fala (\*)     | > 0.55   |
| Relação sinal-ruído (SNR) (\*\*)      | > 8 dB   |

*(\*) Comprimento relativo da fala = Duração da fala / Duração do áudio* *(\*\*) A distância recomendada ao falante é de 30 cm, uma distância natural ao usar um dispositivo de mão*

Durante a gravação, apenas uma pessoa deve falar. Para verificar que o enrolamento foi realizado por uma única pessoa, as templates biométricos individuais gerados a partir das três gravações são comparadas.

| Requisitos mínimos para o enrolamento                                                                                                  | Limiar |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Se a probabilidade de correspondência for inferior ao limiar de similaridade, o registro é rejeitado e uma nova gravação é solicitada. | 0.55   |

## 5. Requisitos de autenticação

| Requisitos mínimos para a autenticação | Valores  |
| -------------------------------------- | -------- |
| Duração do áudio                       | > 700 ms |
| Comprimento relativo da fala           | > 0.55   |
| Relação sinal-ruído (SNR)              | > 3 dB   |

## 6. Métricas

Existem dois canais habituais nos quais a validação biométrica de voz é aplicada: por meio de microfones ou de linhas telefônicas.

**Métricas extraídas para o caso de uso de microfone (nova Versão noctua).**

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

## 7. Recomendações de segurança

* Mantenha `auth_jwt_secret` em um cofre de segredos ou em uma variável de ambiente injetada, em vez de incluí-lo diretamente nas imagens do contêiner.
* A autenticação JWT opcional é configurada na inicialização a partir de `config.json` ou por meio das variáveis de ambiente `FACEPHI_VOICE_REST_AUTH_*`.
* Os endpoints públicos que permanecem sem autenticação são `GET /api/v1/health`, `GET /api/v1/version` e as solicitações de preflight `OPTIONS`.
* `GET /api/v1/config` nunca expõe as configurações de inicialização do JWT e `POST /api/v1/config` não pode modificá-las.

**Métricas extraídas para o caso de uso telefônico.**

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

**FAR** (False Acceptance Rate, taxa de falsa aceitação) é a probabilidade de que o sistema aceite incorretamente um impostor como usuário legítimo.

**FRR** (False Rejection Rate, taxa de falso rejeição) é a probabilidade de que o sistema rejeite incorretamente um usuário legítimo.

## 7. detecção de vida (Liveness)

| Requisitos mínimos para a detecção de vida                                             | Valores   |
| -------------------------------------------------------------------------------------- | --------- |
| Comprimento da fala para a detecção de ataques de repetição (Replay Attack)            | > 1000 ms |
| Comprimento da fala para a detecção de ataques de clonagem de voz (Voice Clone Attack) | > 3000 ms |
| Relação sinal-ruído (SNR)                                                              | > 10 dB   |

| Limires recomendados para a detecção de vida                                             | Limiar |
| ---------------------------------------------------------------------------------------- | ------ |
| A validação de vida será considerada bem-sucedida quando o valor for superior ao limiar. | 0.5    |