Cursor Emulador ADB
Extensão para o Cursor IDE que adiciona um painel chamado EMULADOR dentro do Explorer, permitindo visualizar e controlar um dispositivo Android diretamente dentro da IDE usando ADB.
O objetivo do projeto é oferecer uma experiência parecida com um emulador integrado, útil para desenvolvimento Flutter, Android e testes rápidos, sem depender da janela externa do scrcpy.
Conceito do projeto
Este projeto cria um painel interno no Cursor chamado EMULADOR.
Dentro desse painel é possível:
- visualizar a tela do Android;
- clicar na tela do dispositivo;
- fazer gestos de swipe;
- usar botões de navegação como Voltar, Home e Recentes;
- enviar texto simples para o celular;
- tirar print da tela;
- gravar a tela do Android;
- salvar prints e gravações automaticamente na pasta Downloads;
- fechar a visualização do painel limpando a imagem exibida;
- consultar logs da extensão diretamente pelo Cursor.
A extensão não embute a janela nativa do scrcpy.
Em vez disso, ela usa o ADB para:
- capturar a tela com
adb exec-out screencap -p | gzip -1;
- exibir a imagem dentro de uma Webview do Cursor;
- enviar comandos de toque com
adb shell input tap;
- enviar gestos com
adb shell input swipe;
- gravar a tela com
adb shell screenrecord;
- salvar prints e vídeos na máquina local.
Observação importante sobre o scrcpy
Mesmo que a extensão não use a janela do scrcpy, ela precisa do ADB.
Como o pacote do scrcpy já vem com o adb.exe, o caminho recomendado é colocar a pasta do scrcpy em:
C:\Scrcpy
A estrutura esperada é:
C:\Scrcpy
├── adb.exe
├── scrcpy.exe
├── scrcpy-server
└── outros arquivos do scrcpy
O arquivo mais importante para esta extensão é:
C:\Scrcpy\adb.exe
Se o scrcpy estiver em outro local, será necessário alterar a configuração:
"cursorEmulador.adbPath": "C:\\Scrcpy\\adb.exe"
Exemplo usando outro caminho:
"cursorEmulador.adbPath": "D:\\Ferramentas\\scrcpy\\adb.exe"
Requisitos
- Windows;
- Cursor IDE;
- Node.js instalado;
- Android com modo desenvolvedor ativado;
- Depuração USB ativada no Android;
- dispositivo autorizado no ADB;
adb.exe disponível em C:\Scrcpy\adb.exe.
Configuração recomendada no Cursor
No Cursor, abra:
Ctrl + Shift + P
Preferences: Open User Settings (JSON)
Adicione as configurações:
{
"cursorEmulador.adbPath": "C:\\Scrcpy\\adb.exe",
"cursorEmulador.refreshMs": 450,
"cursorEmulador.fallbackDeviceWidth": 1080,
"cursorEmulador.fallbackDeviceHeight": 2400,
"cursorEmulador.recordBitRate": 8000000,
"cursorEmulador.recordMaxSeconds": 180,
"cursorEmulador.useSession": true
}
Explicação das configurações
| Configuração |
Função |
cursorEmulador.adbPath |
Caminho do adb.exe usado pela extensão. |
cursorEmulador.refreshMs |
Intervalo entre atualizações da tela em milissegundos. Alterações são aplicadas sem reiniciar a extensão. |
cursorEmulador.fallbackDeviceWidth |
Largura usada caso a extensão não consiga detectar a resolução do Android. |
cursorEmulador.fallbackDeviceHeight |
Altura usada caso a extensão não consiga detectar a resolução do Android. |
cursorEmulador.recordBitRate |
Qualidade da gravação de tela em bits por segundo. |
cursorEmulador.recordMaxSeconds |
Tempo máximo da gravação em segundos. |
cursorEmulador.useSession |
Ativa a sessão shell persistente para eliminar o overhead de spawn por frame. Desative se o dispositivo não suportar o modo de sessão. |
Funcionalidades
Visualização da tela
O botão Iniciar começa a capturar a tela do Android e mostrar dentro do painel EMULADOR.
A imagem é atualizada automaticamente em intervalos definidos pela configuração:
"cursorEmulador.refreshMs": 450
Quanto menor o valor, mais rápida a atualização, porém maior o consumo de processamento.
O painel mantém a imagem e o estado ao ser ocultado e reaberto dentro do Cursor, sem necessidade de reiniciar a captura.
Se a conexão cair por instabilidade USB ou reinício do dispositivo, a extensão reconecta automaticamente sem intervenção do usuário.
Fechar
O botão Fechar para a captura contínua, encerra a sessão shell persistente e limpa a imagem do painel.
Atualizar
O botão Atualizar força uma nova captura da tela.
É útil quando a captura automática está parada ou quando você quer atualizar manualmente.
Print
O botão Print tira uma captura da tela atual do Android em qualidade máxima e salva automaticamente em:
C:\Users\SEU_USUARIO\Downloads
Exemplo de arquivo gerado:
android-print-2026-05-08_14-30-10.png
Gravação
O botão Gravar inicia uma gravação da tela do Android usando:
adb shell screenrecord
O botão Parar encerra a gravação e copia o vídeo automaticamente para:
C:\Users\SEU_USUARIO\Downloads
Exemplo de arquivo gerado:
android-gravacao-2026-05-08_14-30-10.mp4
A gravação só é removida do dispositivo após a cópia local ser concluída com sucesso. Se a cópia falhar, o arquivo permanece no celular.
A qualidade da gravação pode ser controlada por:
"cursorEmulador.recordBitRate": 8000000
O tempo máximo de gravação pode ser controlado por:
"cursorEmulador.recordMaxSeconds": 180
Navegação Android
A extensão possui botões para comandos básicos do Android:
Esses botões usam comandos ADB equivalentes a eventos de tecla do Android. Durante a execução de qualquer navegação, a captura de tela é pausada para que o canal ADB fique disponível exclusivamente para o comando, evitando conflito e lentidão.
Envio de texto
O campo de texto permite enviar textos simples para o Android usando ADB.
Apenas caracteres seguros são aceitos: letras, números, espaços e pontuação básica. Espaços são convertidos automaticamente para o formato aceito pelo comando:
adb shell input text
Logs
O botão Logs abre o canal de saída da extensão no Cursor.
Ele mostra informações como:
- status da sessão shell persistente;
- comandos ADB executados;
- erros de conexão e reconexão automática;
- erros ao capturar tela;
- erros ao gravar;
- caminhos de arquivos salvos;
- status da extensão.
Comandos disponíveis no painel
- Iniciar
- Fechar
- Atualizar
- Print
- Gravar
- Parar gravação
- Voltar
- Home
- Recentes
- Enviar texto
- Logs
Histórico de versões e melhorias
Versão 0.1.0
Primeira versão funcional do projeto.
Melhorias adicionadas:
- criação do painel EMULADOR dentro do Explorer do Cursor;
- exibição da tela do Android dentro da IDE usando Webview;
- captura de tela via
adb exec-out screencap -p;
- atualização contínua da imagem;
- suporte a clique na tela usando
adb shell input tap;
- suporte a gesto de arrastar usando
adb shell input swipe;
- botões de navegação Android: Voltar, Home e Recentes;
- campo para envio de texto simples;
- botão de logs;
- configuração de caminho do ADB;
- configuração de resolução fallback;
- configuração de intervalo de atualização.
Versão 0.1.1
Versão com recursos de captura e gravação.
Melhorias adicionadas:
- botão Print;
- salvamento automático de prints na pasta Downloads;
- geração de nome de arquivo com data e hora;
- botão Gravar e botão Parar gravação;
- gravação da tela usando
adb shell screenrecord;
- cópia automática do vídeo gravado para Downloads;
- remoção automática do vídeo temporário do dispositivo;
- configuração de qualidade com
recordBitRate;
- configuração de tempo máximo com
recordMaxSeconds;
- mensagens de confirmação ao salvar print ou vídeo;
- opção para abrir a pasta Downloads após salvar;
- melhoria nos logs da extensão.
Versão 0.1.2
Versão com melhoria de usabilidade no painel.
Melhorias adicionadas:
- alteração do botão Parar para Fechar;
- ao clicar em Fechar, a captura contínua é encerrada e a imagem é limpa;
- logs internos indicando encerramento da visualização;
- interface mais clara para o usuário final.
Versão 0.1.3
Versão de documentação e organização do projeto.
Melhorias adicionadas:
- README completo com conceito do projeto;
- documentação sobre onde colocar a pasta do
scrcpy;
- documentação das configurações, funcionalidades e comandos;
- histórico de versões e limitações conhecidas;
- instruções de compilação, empacotamento e instalação;
- instruções de teste manual do ADB.
Versão 0.1.4
Versão com correções de robustez, segurança e modernização da interface.
Correções críticas:
- processo de gravação e loop de captura encerrados corretamente na desativação da extensão, evitando processos órfãos;
- arquivo de gravação só é removido do dispositivo após a cópia local ser concluída com sucesso;
- lock de início de gravação adicionado para evitar múltiplas gravações simultâneas por clique rápido;
- sanitização do campo de texto alterada para lista branca, prevenindo injeção de comandos via ADB.
Melhorias de robustez:
refreshMs lido uma vez na inicialização e atualizado automaticamente por onDidChangeConfiguration;- interface notificada quando o loop para por erro, revertendo os botões ao estado correto;
- painel mantém imagem e estado ao ser ocultado e reaberto.
Melhorias de interface:
- redesign completo dos botões com variantes visuais: primário, fantasma, perigo e gravação;
- efeito de hover suave e animação de pressionar nos botões;
- botão Gravar pulsa em vermelho durante a gravação;
- barra de status com indicador colorido: verde, âmbar e vermelho;
- efeito de ripple ao tocar na tela do dispositivo;
- botões desabilitados automaticamente quando não há conexão;
- debounce por comando para evitar cliques duplicados.
Versão 0.1.5
Versão com otimizações de performance e redução de latência.
O gargalo identificado foi o spawn de um processo adb.exe por frame, que gerava 30–80ms de overhead de sistema operacional a cada captura, independente do tamanho da imagem. Esta versão elimina esse custo com uma arquitetura de sessão persistente.
Otimizações aplicadas:
- sessão shell persistente: um único processo
adb exec-out é aberto na inicialização e mantido vivo durante toda a sessão. O dispositivo executa um loop infinito de screencap | gzip -1 e os frames chegam continuamente pelo stdout, sem custo de spawn por frame;
- compressão gzip na pipeline do dispositivo: cada frame é comprimido com
gzip -1 antes de ser transferido, reduzindo em 2–3× o volume de dados transmitidos pelo USB;
- dois canais ADB independentes: o canal de captura (sessão persistente) e o canal de input (tap, swipe, navegação) são separados; comandos de interação não bloqueiam mais a atualização da tela;
- loop adaptativo: o loop de captura desconta o tempo gasto na captura do intervalo de espera, garantindo que o
refreshMs configurado seja o intervalo real entre frames, não a soma do intervalo com o tempo de captura;
- pausa inteligente durante interações: ao detectar um tap, swipe ou botão de navegação, o loop pausa por até 600ms para que o ADB processe o comando sem concorrência; após esse período, uma captura imediata é disparada para mostrar o resultado da interação;
- reconexão automática: se a sessão shell morrer por queda de USB ou reinício do dispositivo, a extensão reconecta automaticamente na próxima iteração do loop sem necessidade de clicar em Iniciar novamente;
- canvas no lugar de
<img>: os frames são desenhados via drawImage() em um <canvas>, eliminando o piscar branco que ocorria enquanto o browser recarregava o atributo src da imagem;
- badge de performance em tempo real: FPS e KB/s são exibidos no canto da tela durante a captura;
- logs de captura suprimidos: logs de screencap por frame foram removidos do canal de saída para reduzir pressão de I/O; apenas comandos relevantes são registrados.
Nova configuração:
"cursorEmulador.useSession": true
Desative se o dispositivo não suportar o modo de sessão persistente. A extensão retorna automaticamente para o modo de captura por spawn individual com gzip.
Estrutura do projeto
cursor-emulador-adb
├── package.json
├── tsconfig.json
├── README.md
├── LICENSE
├── icon.png
├── .vscodeignore
└── src
└── extension.ts
Como compilar o projeto
Na pasta do projeto execute:
npm install
npm run compile
Como gerar o pacote VSIX
npm run package
Será criado um arquivo parecido com:
cursor-emulador-adb-0.1.5.vsix
Como instalar no Cursor
No Cursor:
Ctrl + Shift + P
Extensions: Install from VSIX
Selecione o arquivo .vsix gerado e depois recarregue a janela:
Ctrl + Shift + P
Developer: Reload Window
Como testar o ADB manualmente
Abra o PowerShell e rode:
C:\Scrcpy\adb.exe devices
O retorno esperado deve ser parecido com:
List of devices attached
ZF524DZX59 device
Se aparecer unauthorized, verifique o celular e aceite a autorização de depuração USB.
Se não aparecer nenhum dispositivo, verifique:
- cabo USB;
- depuração USB ativada;
- drivers do Android instalados;
- celular desbloqueado;
- caminho
C:\Scrcpy\adb.exe existente.
Teste de print manual
C:\Scrcpy\adb.exe exec-out screencap -p > tela.png
Se o arquivo tela.png for criado corretamente, o ADB consegue capturar a tela do Android.
Teste de gravação manual
C:\Scrcpy\adb.exe shell screenrecord --time-limit 10 /sdcard/Download/teste.mp4
C:\Scrcpy\adb.exe pull /sdcard/Download/teste.mp4 "%USERPROFILE%\Downloads\teste.mp4"
C:\Scrcpy\adb.exe shell rm -f /sdcard/Download/teste.mp4
Limitações
Esta extensão usa capturas de tela contínuas via ADB, portanto não tem a mesma fluidez do scrcpy, que usa transmissão de vídeo otimizada com codec H.264.
O objetivo é ter uma visualização funcional e integrada dentro do Cursor, não substituir totalmente o desempenho do scrcpy.
O comando adb shell screenrecord possui limitações dependendo da versão do Android e do fabricante do dispositivo.
Solução de problemas
O painel EMULADOR não aparece
Recarregue o Cursor: Ctrl + Shift + P → Developer: Reload Window
A tela não atualiza
Verifique se o dispositivo aparece no ADB:
C:\Scrcpy\adb.exe devices
Se não aparecer como device, o Cursor não conseguirá capturar a tela.
Aparece unauthorized
Desbloqueie o celular e aceite a mensagem de autorização de depuração USB. Se a mensagem não aparecer, execute:
C:\Scrcpy\adb.exe kill-server
C:\Scrcpy\adb.exe start-server
C:\Scrcpy\adb.exe devices
Os botões aparecem desabilitados
Os botões ficam desabilitados até que a conexão seja estabelecida. Clique em Iniciar e aguarde o indicador verde na barra de status.
A sessão persistente não funciona no meu dispositivo
Alguns dispositivos mais antigos ou com shells restritas podem não suportar o loop de sessão. Desative a sessão persistente nas configurações:
"cursorEmulador.useSession": false
A extensão voltará a usar capturas individuais com gzip, que ainda são mais rápidas que a versão original.
A imagem fica lenta
Aumente o intervalo entre capturas:
"cursorEmulador.refreshMs": 700
Para tentar aumentar a velocidade, reduza:
"cursorEmulador.refreshMs": 200
Valores muito baixos aumentam o consumo de CPU e USB.
A gravação não salva
Abra os logs da extensão pelo botão Logs e verifique a mensagem de erro. Também teste manualmente:
C:\Scrcpy\adb.exe shell screenrecord --time-limit 10 /sdcard/Download/teste.mp4
Alguns aparelhos podem ter restrições no comando screenrecord.
Resumo
O projeto transforma o Cursor em um ambiente mais prático para desenvolvimento Android/Flutter, adicionando um painel EMULADOR dentro da própria IDE.
O scrcpy deve ficar preferencialmente em:
C:\Scrcpy
E o ADB usado pela extensão deve estar em:
C:\Scrcpy\adb.exe
