Instale
O pacote baixa as dependências principais.
Guia de instalação e operação
Do primeiro comando ao primeiro gesto.
Um guia direto para instalar o projeto, liberar as permissões necessárias e começar a controlar o computador com a mão.
Início rápido
A forma mais curta de começar.
Se o Python já está instalado, use o pacote publicado no PyPI. A webcam será solicitada quando o aplicativo iniciar.
terminal
pip install ai-virtual-mouse-controller
avmcAutorize
Libere câmera e acessibilidade quando solicitado.
Posicione
Mantenha a mão a aproximadamente 50 cm da webcam.
Pré-requisitos
Confira o ambiente antes de instalar.
O processamento roda no computador. Uma GPU dedicada não é necessária.
Windows, macOS ou Linux
Linux funciona melhor em sessões X11.
Python 3.11, 3.12 ou 3.13
O projeto aceita Python abaixo da versão 3.14.
Webcam integrada ou USB
Iluminação frontal melhora a estabilidade.
MediaPipe: o projeto fixa uma versão compatível abaixo
de 0.10.30. Não é necessário instalar essa dependência manualmente.
Windows
Instalação pelo PowerShell.
Use o pacote do PyPI para uso normal. Clone o repositório apenas se quiser estudar ou modificar o código.
Confirme a versão do Python
Abra o PowerShell e execute:
powershell
py -3.11 --versionSe o comando não existir, instale o Python 3.11 pelo site oficial e marque a opção para adicionar o Python ao PATH.
Crie um ambiente virtual
O ambiente isola as bibliotecas deste projeto.
powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1Instale e execute
powershell · ambiente ativo
pip install ai-virtual-mouse-controller
avmc
Se o PowerShell bloquear
Activate.ps1, execute uma vez:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned.
macOS e Linux
Instalação pelo terminal.
Crie o ambiente e instale
zsh
python3.11 -m venv .venv
source .venv/bin/activate
pip install ai-virtual-mouse-controller
avmcNa primeira execução, libere Câmera e Acessibilidade em Ajustes do Sistema → Privacidade e Segurança.
Instale os pacotes do sistema
ubuntu / debian · X11
sudo apt install scrot python3-tk python3-dev
python3.11 -m venv .venv
source .venv/bin/activate
pip install ai-virtual-mouse-controller
avmcO PyAutoGUI possui suporte limitado em Wayland. Use uma sessão X11 quando possível.
Primeira execução
Prepare a câmera e teste o movimento.
Posicione a mão
Fique a aproximadamente 50 cm da webcam, com luz vindo da frente. Mantenha mão, punho e dedos dentro do enquadramento.
Abra a mão
O cursor deve acompanhar o centro da mão. Faça movimentos amplos e lentos na primeira tentativa.
Encerre corretamente
Pressione ESC com a janela da câmera ativa. Isso libera a webcam e encerra os recursos do aplicativo.
Gestos
O vocabulário básico da interação.
Os cliques são disparados quando os dedos se encostam, reproduzindo a resposta imediata de um botão físico.
Mão aberta · mover
Quatro dedos para cima movimentam o cursor. Use o punho para conduzir o gesto sem cansar os dedos.
Pinça · clicar ou arrastar
Encoste indicador e polegar para clicar. Sustente a pinça por cerca de 1,5 segundo para iniciar um arrasto.
Pinça com o médio · clique direito
Encoste o dedo médio no polegar e mantenha o indicador afastado para abrir o menu de contexto.
Sinal de paz · duplo clique
Mostre indicador e médio e conclua o gesto para disparar um duplo clique.
Punho fechado · pausa
Congele o cursor enquanto reposiciona a mão. Retire a mão do quadro para uma pausa automática.
Uso diário
Atalhos disponíveis durante a execução.
H
Liga ou desliga o overlay holográfico 3D.
S
Abre ou fecha o painel de configurações em tempo real.
T
Alterna a janela da câmera sempre no topo.
Z
Ativa o modo apresentação; gestos direcionais avançam ou voltam slides.
ESC
Encerra o aplicativo e libera a câmera.
Configuração
Ajuste o comportamento sem alterar a arquitetura.
As configurações permanentes ficam em config.py. Durante a
execução, pressione S para abrir os controles mais usados.
CAMERA_*
Seleciona a câmera, resolução e FPS alvo.
CURSOR_ANCHOR
Define qual ponto anatômico conduz o cursor.
PINCH_*
Controla a sensibilidade e os limites dos gestos de pinça.
SMOOTHING_*
Ajusta o One Euro Filter entre estabilidade e resposta.
SCREEN_MARGIN_*
Calibra o alcance das bordas e dos cantos da tela.
HOLOGRAM_*
Configura backend, cor, opacidade e FPS do overlay opcional.
Soluções rápidas
Problemas comuns.
A câmera não abre
Feche aplicativos que estejam usando a webcam e confira as permissões de câmera do sistema.
Se houver mais de uma câmera, altere o índice em CAMERA_INDEX.
A mão aparece, mas o cursor não se move
No macOS, libere Acessibilidade para o terminal ou aplicativo usado. Em Linux, confirme que a sessão é X11.
O cursor está tremendo
Melhore a iluminação, afaste um pouco a mão e selecione o perfil stable ou smooth no painel aberto pela tecla S.
O MediaPipe falha ao importar
Confirme que o ambiente virtual está ativo e reinstale as versões declaradas pelo projeto:
terminal
pip install --force-reinstall "mediapipe>=0.10.18,<0.10.30"Não encontrou a solução? Abra uma issue com a saída completa do terminal.
Abrir uma issue