Como eu criei um CLI para transformar um trajeto de GPS num vídeo de sobrevoo

E aí essa galera, tudo bem com vocês?

Voltei pra publicar um projeto pessoal que desenvolvi nos últimos meses pra não deixar minhas skills de coding morrerem.

A ideia pra esse projeto veio do uso e da minha frustração com apps como Strava e Relive. Esses dois apps que registram atividade física têm a capacidade de gerar vídeos de flyover dos trajetos que você faz durante uma atividade, como corrida ou ciclismo. O problema é que não é de graça: pra gerar um videozinho mequetrefe no Strava, você tem que assinar o plano premium, e o Relive até te deixa gerar um vídeo grátis, mas a qualidade é horrível, então acaba sendo bem frustrante.

Diante disso, eu resolvi criar o Sobrevoo, um CLI que me permite gerar esses videozinhos de maneira offline a partir do trajeto GPS exportado num arquivo *.gpx, que é o formato que o Samsung Health, Garmin Connect, o próprio Strava e outros apps de atividade física exportam.

Tudo roda no seu computador, sem conta, sem servidor e sem internet: o mapa e o relevo são arquivos que você mesmo baixa e apresenta ao Sobrevoo uma vez.

Como o Sobrevoo foi feito?

Eu usei Golang pra escrever a ferramenta. Apliquei arquitetura hexagonal para deixar os componentes fáceis de trocar e as regras de negócio bem encapsuladas. Na camada de infraestrutura está a lib Cobra pra implementação dos comandos.

Quem acompanhou a série sobre princípios SOLID em Go vai reconhecer aqui o Dependency Inversion Principle: o domínio define interfaces como VideoEncoder e ElevationReader, e a infraestrutura implementa, com o ffmpeg e a leitura do GeoTIFF. Trocar o ffmpeg por outro codificador, por exemplo, não muda nada nas regras de negócio.

Também usei bastante o Spec Kit pra padronizar meu fluxo de desenvolvimento agêntico com o Claude Code.

Como usar o Sobrevoo?

Você precisa do Go 1.26 ou mais novo e do ffmpeg com o codificador libx264, no PATH. Pra instalar o ffmpeg no macOS:

brew install ffmpeg

No Debian e no Ubuntu:

sudo apt install ffmpeg

No Windows:

winget install Gyan.FFmpeg

Você pode instalar o Sobrevoo com o comando go install, que compila o código-fonte e coloca o arquivo executável binário gerado na pasta bin do seu ambiente Go (GOPATH/bin), permitindo que você o execute de qualquer lugar pelo terminal (desde que essa pasta esteja no seu PATH).

go install github.com/waliqueiroz/sobrevoo/cmd/sobrevoo@latest

Se preferir, também dá pra só compilar a partir do código-fonte e usar diretamente o binário gerado em ./bin/sobrevoo:

git clone https://github.com/waliqueiroz/sobrevoo.git
cd sobrevoo
make build

Pra usá-lo, você vai precisar do trajeto num arquivo *.gpx. No Samsung Health, o caminho para exportar um é indo até o registro da atividade física > menu do canto superior direito da tela > Compartilhar rota como arquivo GPX.

O Sobrevoo não embute nem baixa dados geográficos. Para desenhar o voo, ele precisa de dois arquivos que cubram a região do trajeto:

• O relevo é a altitude do terreno, ponto a ponto: o que dá forma às montanhas e aos vales do vídeo. Formato: GeoTIFF.
• O mapa base é a imagem que veste o relevo: ruas, imagem de satélite, um mapa topográfico. Formato: MBTiles de imagem.

Ambos os arquivos podem ser baixados da internet. O GeoTIFF pode ser obtido do Copernicus DEM GLO-30 ou do SRTM, ambos gratuitos e distribuídos por fontes como o OpenTopography. E o MBTiles pode ser gerado com softwares como o QGIS, a partir de dados do OpenStreetMap ou de outras fontes, desde que você respeite os termos de uso de quem fornece o mapa (os servidores de mapa do próprio OpenStreetMap, por exemplo, não permitem baixar uma região inteira de uma vez).

Os dois arquivos precisam cobrir com folga o entorno do trajeto, não só o traçado: a câmera voa afastada e enxerga longe, sobretudo na abertura e no fechamento do vídeo, quando mostra o trajeto inteiro de cima. Uma área de vários quilômetros em volta é o normal; num passeio de 3 km de lado, a área vista pode passar de 15 km de lado.

Se quiserem, posso trazer um artigo dedicado a como obter dados geográficos da sua região. Não vou me estender muito nesse tema porque não é o objetivo de hoje.

Depois de obter os arquivos, você precisa registrá-los no Sobrevoo:

sobrevoo geodata register ~/mapas/regiao.mbtiles --name regiao-mapa
sobrevoo geodata register ~/mapas/regiao.tif --name regiao-relevo

Esse registro só precisa ser feito uma única vez para cada região, e você não diz se o arquivo é mapa ou relevo, nem a área: o Sobrevoo descobre as duas coisas pelo conteúdo. Com os arquivos registrados, podemos executar o primeiro fly:

sobrevoo fly pedalada.gpx --output pedalada.mp4

A ferramenta vai mostrar o progresso no terminal. O resultado final te entrega um vídeo em Full HD com proporção 9:16. Abaixo um exemplo, com mapa do OpenStreetMap (© colaboradores do OpenStreetMap):

Eu deixei esse formato como padrão porque uso o vídeo pra publicar nos stories do Instagram, mas a proporção, resolução, qualidade, informações exibidas na tela e outras propriedades podem ser alteradas ao seu gosto.

Resolução e qualidade, inclusive, ajudam bastante na hora de testar. A etapa mais demorada é o desenho dos quadros, e ela demora mais quanto maior a resolução. Se você quiser só conferir o resultado antes do vídeo definitivo, dá pra gerar uma versão menor e com qualidade mais baixa, que fica pronta numa fração do tempo:

sobrevoo fly pedalada.gpx --output teste.mp4 --resolution 540x960 --quality low

O código-fonte do Sobrevoo tá publicado no GitHub sob a licença MIT. Lá eu deixei um README com a documentação completa da ferramenta e como usar cada comando extra para personalização do vídeo.

https://github.com/waliqueiroz/sobrevoo

Próximos passos?

Gerar uma versão que dê pra ser usada no celular? Publicar uma versão web pra acesso pelo navegador? Não sei.

Sinto que dá pra usar a codebase do Sobrevoo como exemplo pra explorar mais artigos aqui no blog. Penso em escrever sobre arquitetura hexagonal. Até lá, instalem, usem, tragam feedback nos comentários e, se quiserem mandar PRs com melhorias, fiquem à vontade.

Até a próxima!