Teste sem uma câmera real
Use este caminho quando quiser validar o primeiro ciclo de câmera e transmissão ao vivo sem depender de uma câmera IP real.
A receita padrão usa a imagem estática incluída no repositório. Este é o caminho de onboarding Alpha mais reprodutível. Depois que ele funcionar, use um vídeo em loop ou uma webcam local quando precisar de movimento, detecção, tracking ou entrada de desenvolvimento mais próxima de hardware real.
Este é um utilitário de desenvolvimento e onboarding. Ele não substitui uma instalação com câmera real. Ele fornece uma fonte RTSP previsível para confirmar Docker, streaming, publicação de fonte e playback no navegador antes de adicionar hardware real. Ele não é, sozinho, um teste de detecção de pessoas.
Inicie a câmera RTSP sintética
Em um terminal, na raiz do repositório:
npm run dev:rtsp-image -- --expose docker
O comando publica a imagem placeholder do repositório como RTSP H.264 e imprime uma URL como:
rtsp://host.docker.internal:8554/toposync-sample-image
Deixe esse comando rodando enquanto testa o Toposync.
Se quiser usar sua própria imagem:
npm run dev:rtsp-image -- /caminho/para/imagem.jpg --expose docker
Suba o Docker com streaming
Em outro terminal, na raiz do repositório:
docker compose up -d
O Compose atual usa a imagem Docker padrão do Toposync. Essa imagem já inclui suporte a streaming, então este caminho de onboarding não precisa de argumentos extras de build.
Abra o Toposync:
http://127.0.0.1:8000/
Conclua a criação do primeiro usuário se a pasta de dados estiver nova.
Avançado: build local
Use o caminho de build local somente quando estiver desenvolvendo o Toposync a partir de um checkout do repositório ou testando mudanças ainda não publicadas:
docker compose -f docker-compose.yml -f docker-compose.local-build.yml up -d --build
Não use as variáveis antigas de build de streaming neste guia. Elas pertenciam ao fluxo anterior de imagem local e não fazem parte do caminho normal com Compose.
Inicie o streaming
No Toposync:
- Abra Configurações.
- Abra Transmissões.
- Abra a aba Avançado.
- Clique em Iniciar em Engine (MediaMTX).
- Aguarde até o status da engine indicar que está rodando.
Adicione a fonte RTSP
No Toposync:
- Abra Configurações.
- Abra Câmeras.
- Selecione Adicionar manual.
- Nomeie a câmera, por exemplo
Câmera RTSP sintética. - Adicione uma fonte RTSP.
- Cole a URL RTSP impressa pelo script.
- Defina o papel da fonte como Principal.
- Rode Probe.
- Rode Snapshot.
- Confirme que Transmitir esta fonte está habilitado. Novas fontes de vídeo já vêm com essa opção ativa.
- Salve a câmera.
A fonte deve aparecer no probe como vídeo H.264 em 1280x720. O snapshot deve
mostrar a imagem de rua usada como placeholder.
Gere as publicações ao vivo
No Toposync:
- Abra Configurações.
- Abra Transmissões.
- Abra a aba Ao vivo.
- Se nenhuma publicação ao vivo aparecer, clique em Reconciliar transmissões.
- Confirme que a câmera sintética aparece na lista de publicações ao vivo.
Confirme a transmissão ao vivo
Abra o menu de modo de renderização e escolha Câmeras ao vivo.
Resultado esperado:
- o card da câmera aparece;
- o estado passa por aquecimento se necessário;
- o card chega a Live;
- o vídeo toca no navegador.
Um aquecimento curto é normal. Se o card ficar stale ou indicar que nenhum pipeline alimenta a transmissão, volte para Configurações > Transmissões, confirme que a engine está rodando e clique em Reconciliar transmissões na aba Ao vivo.
O que este teste prova
O caminho com imagem estática prova o ciclo de transporte da câmera:
- o Toposync consegue alcançar a URL RTSP a partir do runtime;
- probe e snapshot funcionam;
- a fonte pode ser publicada para transmissão ao vivo;
- o playback no navegador funciona;
- depois do mapeamento, calibração e projeção na Visão 360 podem ser conferidas contra um frame estável.
Ele não prova detecção real de pessoa, tracking, notificações ou pins. Uma imagem parada pode nunca passar por um pipeline com gate de movimento, e ela não prova que o modelo de detecção está preparado no servidor de processamento selecionado.
Use vídeo em loop, webcam ou câmera real quando precisar de movimento e detecção baseada em modelo. Para validação de produto ou lab de mapping -> tracking -> notify -> pin sem RF-DETR, use o smoke determinístico de detecção sintética em vez de inserir dados diretamente.
Outras fontes de câmera para desenvolvimento
Mantenha a imagem estática como o primeiro teste de onboarding. Use as alternativas abaixo depois que o primeiro ciclo de live view funcionar, ou quando precisar de uma fonte que se comporte mais como uma câmera real.
Imagem estática
Use este caminho para um teste determinístico de primeira câmera, Docker, streaming e playback no navegador:
npm run dev:rtsp-image -- --expose docker
O script usa a imagem placeholder incluída por padrão. Passe o caminho de uma imagem quando quiser outro quadro estático:
npm run dev:rtsp-image -- /caminho/para/imagem.jpg --expose docker
Arquivo de vídeo em loop
Use este caminho quando precisar de movimento para testar detecção, tracking, modelos ou pipelines:
npm run dev:rtsp-video -- --video /caminho/para/video.mp4 --expose docker
O arquivo de vídeo fica em loop até você parar o comando. Use arquivos que você tem permissão para usar e evite commitar imagens privadas ou sensíveis no repositório.
Webcam local
Use este caminho quando quiser uma câmera local real durante o desenvolvimento:
npm run dev:camera-rtsp -- --list-only
Depois selecione a câmera pelo índice impresso, identificador de backend, nome exato ou trecho único do nome:
npm run dev:camera-rtsp -- --camera 0
Para Toposync rodando no Docker Desktop, exponha o servidor RTSP da webcam no host e anuncie um endereço que o container consiga resolver:
npm run dev:camera-rtsp -- --camera 0 --expose network --host host.docker.internal
Para Docker Linux ou outro runtime na rede, use o endereço LAN do host:
npm run dev:camera-rtsp -- --camera 0 --expose network --host <ip-do-host>
O caminho por webcam é menos reprodutível que os scripts de imagem ou vídeo. Ele pode depender de permissões de câmera do sistema operacional, drivers disponíveis e modos de captura do dispositivo.
Qual modo de exposição devo usar?
Para os scripts de imagem e vídeo, use o modo que combina com o local onde o Toposync roda:
| Runtime do Toposync | Modo do script RTSP | Formato da URL |
|---|---|---|
| Toposync roda direto neste host | --expose local | rtsp://127.0.0.1:8554/... |
| Docker Desktop no macOS ou Windows | --expose docker | rtsp://host.docker.internal:8554/... |
| Docker Linux ou outra máquina na LAN | --expose network --host <ip-do-host> | rtsp://<ip-do-host>:8554/... |
Não use 127.0.0.1 dentro do Docker, a menos que o servidor RTSP esteja rodando
no mesmo container. Para um container Toposync, 127.0.0.1 significa o próprio
container do Toposync, não a máquina host.
A exposição de rede não tem senha de visualização. Use apenas em uma LAN de desenvolvimento confiável.
O script de webcam suporta --expose local e --expose network. Para Docker
Desktop, use exposição de rede com --host host.docker.internal; para Docker
Linux, use exposição de rede com o IP LAN do host.
Migre para uma câmera real
Depois que esse ciclo funcionar, substitua a URL sintética pela URL RTSP real da câmera, NVR, Frigate ou go2rtc.
Mantenha a mesma ordem de validação:
- Probe.
- Snapshot.
- Confirmar que Transmitir esta fonte está habilitado.
- Reconciliar as publicações ao vivo.
- Confirmar Câmeras ao vivo.
- Adicionar mapeamento e pipelines apenas depois que a transmissão estiver estável.