> For the complete documentation index, see [llms.txt](https://portal-integracao.intelbras.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://portal-integracao.intelbras.com.br/defense-ia-and-lite/dicas-de-implementacao/guia-de-implementacao-rtsp-para-web-front-end-arquitetura.md).

# Guia de Implementação: RTSP para Web Front-End (arquitetura)

Arquitetura para exibir RTSP no navegador sem expor credenciais, com baixa latência e entrega via HTTPS. Compara WebRTC e HTTP-FLV/MPEG-TS e cobre requisitos, segurança e operação.

**Objetivo:** Exibir vídeo de câmeras RTSP em aplicação web **sem expor credenciais/URL RTSP no front**, com **baixa latência** e **entrega via HTTPS**.

***

## Visão geral da arquitetura <a href="#visao-geral-da-arquitetura" id="visao-geral-da-arquitetura"></a>

#### **Opção A — RTSP → WebRTC (recomendada quando latência < 1–2s)**

**Prós:** latência muito baixa (sub-segundos a \~1–2s), browsers modernos, sem playlists/segmentos. **Contras:** precisa de sinalização/ICE (STUN/TURN), um pouco mais complexo na infra.

```mermaid
---
config:
  look: neo
  theme: neo
  layout: dagre
---
flowchart TB
    A["Câmera RTSP"] L_A_B_0@-- RTSP (rede interna) --> B["MediaMTX<br>Gateway de mídia"]
    B L_B_C_0@-- WHEP / WebRTC --> C["Back-end Java<br>Autenticação / Tokenização / Proxy"]
    C L_C_D_0@-- URL temporária / token --> D["App Angular<br>Player WebRTC"]
    D L_D_E_0@--> E["Usuário Navegador"]

    A@{ shape: rect}
    B@{ shape: rect}
    C@{ shape: rect}
    D@{ shape: rect}
    E@{ shape: tag-proc}
    style A stroke:#00C853
    style B stroke:#00C853
    style C stroke:#00C853
    style D stroke:#00C853
    style E stroke:#00C853,stroke-width:1px,stroke-dasharray: 0

    L_A_B_0@{ animation: slow } 
    L_B_C_0@{ animation: slow } 
    L_C_D_0@{ animation: slow } 
    L_D_E_0@{ animation: slow }
```

#### Opção B — RTSP → HTTP-FLV ou MPEG-TS (via MSE)

```mermaid
---
config:
  look: neo
  theme: neo
  layout: dagre
---
flowchart TB
    A["Câmera/Defense RTSP"] L_A_B_0@-- RTSP (rede interna) --> B["Servidor de mídia para codificação 
    (SRS / Nginx-RTMP/ etc)"]
    B L_B_C_0@-- "Https://Live/..." --> C["Back-end Java<br>Autenticação / Tokenização / Proxy"]
    C L_C_D_0@-- <br> --> D["App Angular
    (player MSE: FLV ou TS via WS/HTTP)<br>"]
    D L_D_E_0@--> E["Usuário Navegador"]

    A@{ shape: rect}
    B@{ shape: rect}
    C@{ shape: rect}
    D@{ shape: rect}
    E@{ shape: tag-proc}
    style A stroke:#00C853
    style B stroke:#00C853
    style C stroke:#00C853
    style D stroke:#00C853
    style E stroke:#00C853,stroke-width:1px,stroke-dasharray: 0

    L_A_B_0@{ animation: slow } 
    L_B_C_0@{ animation: slow } 
    L_C_D_0@{ animation: slow } 
    L_D_E_0@{ animation: slow }
```

**Prós:** arquitetura simples, latência baixa–moderada (1–3s), sem sinalização WebRTC. **Contras:** compatibilidade mobile pode variar conforme player MSE.

{% hint style="info" %}
**Dica de segunça:** RTSP **sempre interno** (LAN/VPN). O navegador só enxerga **WebRTC** ou **HTTP-FLV/MPEG-TS** por **HTTPS**. Não utilize error codes para evitar ataques como Banner Grab.
{% endhint %}

***

### Requisitos & pré-condições

* Acesso às câmeras ou canal Defense via RTSP (rede, credenciais, portas).
* **Vídeo:** preferir **H.264 (8-bit)** (evita transcode).
* **Áudio:** navegadores preferem **AAC** (se vier G.711/PCM, alterar no dispositivo.).
* **Substream** (baixa resolução/bitrate) recomendado para web.
* Servidor/VM/contêiner para o **gateway de mídia**.
* **HTTPS** em toda a entrega ao front (mesma origem se possível).

***

#### Decisões de design (baseline) <a href="#decisoes-de-design-baseline" id="decisoes-de-design-baseline"></a>

* **Entrega:** WebRTC (WHEP) **ou** HTTP-FLV / MPEG-TS (via MSE).
* **Latência alvo:** WebRTC < 1–2s; HTTP-FLV/TS \~1–3s (ajuste de buffer).
* **Transcodificação:** **evitar**; usar **copy** de H.264/AAC (transmux).
* **Isolamento:** RTSP nunca no front; só endpoints HTTPS com **tokens temporários**.
* **Escala:** 1 ingest por câmera; evitar recodificação; se necessário, **VAAPI/NVENC**.

***

## Implantação do gateway de mídia <a href="#implantacao-do-gateway-de-midia" id="implantacao-do-gateway-de-midia"></a>

**WebRTC (WHEP/WHIP)**

* Provisionar **MediaMTX / Janus / SRS** com ingest **pull RTSP** por câmera (path dedicado).
* Ativar **TLS** no gateway (preferir mesmo domínio do app).
* Configurar **ICE**: **STUN** público e **TURN** para NATs restritivas.
* **Câmera:** H.264; **GOP** \~1–2s; bitrate adequado ao público.

**HTTP-FLV / MPEG-TS**

* Ingest RTSP e saída **HTTP-FLV** ou **MPEG-TS via WebSocket/HTTP**.
* **Transmux** (H.264 + AAC) quando possível (evita transcode).
* Publicar sob **HTTPS** (idealmente mesma origem do app).

**Operação comum**

* Supervisor (systemd/supervisord/Docker) com **restart automático**.
* **Health-check**: queda RTSP → reconectar.
* Logs e métricas (conexões, bitrate, quedas).

***

## Back-end Java — responsabilidades <a href="#back-end-java-responsabilidades" id="back-end-java-responsabilidades"></a>

* **Não expor RTSP/credenciais**.
* Emitir **URLs assinadas/temporárias** para play (**WHEP** ou **/live/flv** etc.) com expiração curta.
* **Autorização por câmera/perfil**; auditar **quem/quando/qual câmera/duração**.
* **Opcional:** proxy reverso do endpoint de mídia pelo Spring (mesma origem e auditoria).
* **Proteções:** rate limit, throttling por usuário/sessão, conferência de Referer/IP.
* **Headers:** `Content-Type` correto (ex.: `video/x-flv`, `video/mp2t`); cache **curto**.
* **Observabilidade:** sessões ativas, erros 4xx/5xx, tempo de sessão, falhas de handshake (WebRTC).

***

## Front-end Angular — responsabilidades <a href="#front-end-angular-responsabilidades" id="front-end-angular-responsabilidades"></a>

* **Player WebRTC:** APIs nativas (WHEP) ou lib leve para offer/answer.
* **Player MSE (HTTP-FLV/TS):** cliente que demultiplexe **FLV/TS** → MSE `SourceBuffer`.
* **Autoplay:** iniciar **muted** (regras do navegador).
* **Estados de UI:** carregando → reproduzindo → reconectando → erro (com **retry**).
* **Erros comuns:** CORS, MIME incorreto, mixed content, bloqueio de autoplay, falha ICE (WebRTC).
* **Acessibilidade:** foco/teclado; opção de áudio quando aplicável.

***

## Segurança e conformidade <a href="#seguranca-e-conformidade" id="seguranca-e-conformidade"></a>

* Segredos RTSP fora do código (cofre/variáveis de ambiente).
* RTSP **bloqueado na internet**; acesso só via LAN/VPN.
* **TLS** ponta a ponta (inclusive no gateway).
* Autorização por câmera; **revogação imediata** de tokens.
* Auditoria: **logs** de acesso às streams e correlação com usuário/sessão.
* Extras: WAF/CDN (se aplicável), rate limit, restrição por IP.

***

## Observabilidade e operação <a href="#observabilidade-e-operacao" id="observabilidade-e-operacao"></a>

* **Logs:** gateway (ingest/play), servidor web/proxy, back-end (tokens/sessões).
* **Métricas:** viewers simultâneos, bitrate efetivo, quedas de frames, falhas ICE, reconexões.
* **Alertas:** queda de ingest, erro de publicação, disco/CPU altos.
* **NTP:** câmera e servers sincronizados.
* **Limpeza:** rotação de logs; evitar retenção desnecessária.

***

## Performance & dimensionamento <a href="#performance-and-dimensionamento" id="performance-and-dimensionamento"></a>

* **Bitrate web:** 800 kbps – 3 Mbps por câmera (prefira **substream H.264**).
* **CPU:** transmux/cópia consome pouco; **transcode** é caro (usar **VAAPI/NVENC** se inevitável).
* **Escala:** distribuir por zonas de rede; isolar câmeras problemáticas; limitar viewers por instância.
* **Rede:** observar jitter/packet loss; gateways próximos às câmeras.

***

## Testes e critérios de aceite (DoR/DoD) <a href="#testes-e-criterios-de-aceite-dor-dod" id="testes-e-criterios-de-aceite-dor-dod"></a>

**Funcionais**

* Reproduz nos browsers alvo (Chrome/Firefox/Edge/Safari — desktop e mobile).
* **Latência** na meta (WebRTC < 2s; HTTP-FLV/TS \~1–3s).
* **Recuperação automática** após queda RTSP.
* **Sem vazamento** de RTSP/credenciais no front/rede externa.

**Não funcionais**

* **HTTPS** end-to-end.
* **Logs e métricas** visíveis (Grafana/ELK/Cloud).
* **Carga:** N espectadores simultâneos sem degradação perceptível.
* **Runbook** e alarmes configurados.

**Definition of Done (resumo)**

* ✅ Play protegido por **tokens temporários**.
* ✅ Player Angular com estados e tratativas de erro.
* ✅ Latência/estabilidade validadas.
* ✅ Observabilidade e alertas ativos.
* ✅ Documentação operacional publicada.

***

### Runbooks <a href="#runbooks" id="runbooks"></a>

**Adicionar nova câmera**

1. Validar RTSP e **codecs** (H.264/AAC).
2. Ajustar **substream**, **GOP** e bitrate na câmera.
3. Criar **path** no gateway (WebRTC ou HTTP-FLV/TS).
4. Publicar endpoint sob **HTTPS** e emitir **URL assinada**.
5. Cadastrar no back-end (catálogo/perfis) e no player Angular.
6. Testar latência/estabilidade e liberar.

**Incidentes comuns**

* **Vídeo não abre:** checar HTTPS/CORS/MIME, token, origem, firewall.
* **Compatibilidade parcial:** validar player MSE/WebRTC e políticas de autoplay.
* **Sem áudio:** origem é G.711 → converter para **AAC** no gateway.
* **Travamentos:** reduzir bitrate/resolução; ajustar GOP; checar rede/NTP; perdas de pacote.
* **Falha ICE (WebRTC):** configurar **TURN** e checar portas/roteamento.

***

### Roadmap evolutivo <a href="#roadmap-evolutivo" id="roadmap-evolutivo"></a>

* **ABR em WebRTC** (simulcast/SVC).
* **Gravação/time-shift** (NVR/storage de objetos).
* **CDN/edge relays** para escalar viewers globalmente.
* **PTZ/talkback** via DataChannel/áudio no WebRTC.
* **QoS dinâmica** (bitrate adaptativo no gateway).

***

**Notas finais**

* **WebRTC**: escolha quando **latência** for crítica e você aceitar a sinalização/ICE.
* **HTTP-FLV/MPEG-TS (MSE)**: escolha pela simplicidade via HTTP(s) e latência \~1–3s.
* Em ambos os casos, **não exponha RTSP**, mantenha **TLS**, **tokens com expiração curta** e **observabilidade** desde o início.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://portal-integracao.intelbras.com.br/defense-ia-and-lite/dicas-de-implementacao/guia-de-implementacao-rtsp-para-web-front-end-arquitetura.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.