vision-live
Real-time visual perception running fully on-device: face, eyes, hands, pose and objects. No cloud, no APIs.
This README is only available in Spanish.
Verificar que funciona · Uso · iPhone como cámara · Modo Stark · Reconocimiento · Rendimiento · Instalación
Percepción visual en tiempo real, 100 % en tu PC: sin APIs, sin cuentas, sin límites de uso y sin que ninguna imagen salga del ordenador.
Reconoce a la vez:
| Qué | Cómo |
|---|---|
| Tu cara (quién eres, por nombre) | InsightFace / ArcFace, base local en data/faces/ |
| 478 puntos faciales + 52 expresiones | MediaPipe Face Landmarker |
| Ojos: iris, hacia dónde miras, parpadeos, guiños | iris + EAR geométrico |
| Orientación de la cabeza (giro, alzado, ladeo) | matriz de transformación facial |
| Emoción aproximada | combinación de unidades de acción facial |
| Gestos de mano | MediaPipe Gesture Recognizer + geometría propia (OK, cuernos, pellizco, dedos extendidos…) |
| Postura del cuerpo (33 puntos) | MediaPipe Pose (--pose) |
| Objetos del entorno (80 clases en español) | YOLO11 sobre CUDA |
Verificar que funciona (sin cámara ni GUI)
No hace falta webcam, iPhone ni pantalla para comprobar que la instalación
funciona de verdad: el repo trae vídeos de prueba en data/test/ y --benchmark
procesa frames sin abrir ninguna ventana — es la forma en que se verificó este
mismo README, ejecutándolo tal cual en una máquina sin cámara conectada:
./run --source data/test/demo.mp4 --benchmark 30 --pose
Salida real de esa ejecución:
→ abriendo fuente de vídeo…
data/test/demo.mp4
→ cargando YOLO…
yolo11n.pt en cuda:0
→ cargando reconocimiento facial…
0 persona(s) en la base: —
1280x720
30 frames · 16.6 FPS · cara+manos 36 ms · yolo 25 ms
cara=True expresión=feliz mirada=al frente identidad=desconocido
gestos=['sonriendo']
frames con cara 30/30, con manos 30/30, con objetos 27/30
entorno={'persona': 1, 'corbata': 1}
reconexiones de la cámara: 0
último frame -> data/capturas/benchmark.png
Cara, manos y objetos detectados en el 100 %, 90 % y 90 % de los frames
respectivamente, sobre GPU (cuda:0) — instalación y modelos correctos de
punta a punta. Si esto corre, ./run con una cámara real también correrá.
Uso
./run # primera webcam que encuentre
./run --source 192.168.1.40 # la cámara del iPhone por WiFi (ver abajo)
./run --probe 192.168.1.40 # ver qué URL de cámara responde en esa IP
./run --source data/test/demo.mp4 # un vídeo
./run --pose # añadir el esqueleto corporal
./run --list-cams # ver qué cámaras hay
./run --benchmark 100 # medir rendimiento sin abrir ventana
Teclas: q salir · e enrolar tu cara · m malla · o objetos · h manos ·
p pose · s foto · r grabar vídeo.
Todos los flags (./run --help)
| Flag | Qué hace |
|---|---|
--source |
'auto', índice de webcam (0), IP del móvil, URL http/rtsp o ruta de un vídeo |
--width / --height |
resolución de captura |
--no-mirror |
no voltear la imagen como un espejo |
--rotar {0,90,180,270} |
girar la imagen (el móvil suele llegar tumbado) |
--no-objects |
desactivar YOLO |
--no-identity |
desactivar el reconocimiento de quién eres |
--pose |
activar el esqueleto corporal |
--faces N |
cuántas caras seguir a la vez |
--yolo yolo11{n,s,m,l,x}.pt |
tamaño del modelo (n = más rápido) |
--yolo-conf |
confianza mínima de YOLO |
--yolo-cada N |
lanzar YOLO cada N frames |
--id-cada N |
reidentificar la cara cada N frames |
--umbral-id |
parecido mínimo para dar un nombre |
--detalle-malla {normal,completo} |
densidad de la malla facial dibujada |
--analisis PX |
lado mayor al que se reduce la imagen para analizarla (0 = sin reducir) |
--escenas [ARCHIVO] |
activar los gestos que lanzan apps |
--escenas-seco |
con --escenas: enseña qué lanzaría, sin lanzarlo |
--list-cams |
listar webcams y salir |
--probe IP |
probar las URLs típicas de cámara IP en esa IP y salir |
--benchmark N |
procesar N frames sin abrir ventana y medir el rendimiento |
Usar el iPhone como cámara
No hay ninguna webcam conectada al PC, así que la cámara es el iPhone.
Por WiFi (lo más rápido de montar)
- Instala IP Camera Lite en el iPhone (gratis en la App Store).
- Ábrela y pulsa «Turn on IP Camera Server». Arriba te muestra una
dirección tipo
http://192.168.1.40:8081. - Con el iPhone en el mismo WiFi que el PC:
./run --source 192.168.1.40 --rotar 270
El iPhone emite en la orientación del sensor, así que llega tumbado: --rotar 270
lo endereza cuando lo tienes en vertical (90 si lo giras al otro lado). La
imagen se endereza antes de analizarla, para que los modelos vean la cara derecha.
Basta con la IP: la app prueba sola las URLs conocidas (IP Camera Lite, IP Webcam de Android, DroidCam…) y usa la que responda. Para ver cuál funciona sin arrancar nada:
./run --probe 192.168.1.40
Si cambiaste el usuario o la contraseña en la app, pasa la URL entera:
--source 'http://usuario:[email protected]:8081/video'.
Por cable USB-C (menos retardo, sin depender del WiFi)
./scripts/iphone_usb.sh # instala lo que falte, monta /dev/video9
./run --source 9
./scripts/iphone_usb.sh --parar
El script usa usbmuxd + iproxy para tunelar el puerto de la app por el cable
y v4l2loopback para que el iPhone aparezca como una webcam normal del sistema
— también la verán OBS, Zoom o el navegador. Pide sudo para instalar paquetes y
cargar el módulo del kernel.
Modo Stark: un gesto abre tus apps
./run --source 172.20.10.1 --rotar 270 --escenas
Con --escenas la app vigila gestos de disparo y lanza lo que pongas en
escenas.toml. De fábrica vienen tres:
| Gesto | Qué hace |
|---|---|
| Palmada (juntar las dos manos de golpe) | Notificación + voz «Bienvenido de vuelta, señor», Spotify, Claude Code en kitty y Firefox, todo en el escritorio 7 de Hyprland |
| Puño sostenido 1,5 s | Modo foco: pausa la música y salta al escritorio 2 |
| Palma abierta sostenida 1 s | Play / pausa de la música |
Editar escenas.toml es todo lo que hace falta para cambiarlo: cada escena tiene
un disparador (palmada o cualquier gesto que la app reconozca) y una lista de
pasos con comandos. Para probar sin que se abra nada:
./run --source 172.20.10.1 --rotar 270 --escenas --escenas-seco
La palmada exige que las dos manos se acerquen rápido: acercarlas despacio no dispara, y hay un tiempo de enfriamiento para que una palmada no cuente dos veces.
Que te reconozca por tu nombre
Con la app abierta pulsa e, escribe tu nombre en la terminal y mueve
despacio la cabeza: guarda 12 muestras para aguantar giros y cambios de luz.
Desde fotos que ya tengas:
./.venv/bin/python scripts/enrolar_fotos.py m1ke ~/Pictures/yo/*.jpg
./.venv/bin/python scripts/gente.py # ver quién está guardado
./.venv/bin/python scripts/gente.py borrar m1ke # borrar a alguien
Los perfiles son vectores en data/faces/*.npy. No se guarda ninguna foto y
nada se sube a ningún sitio.
Robustez
- La cámara se cae y la app sigue viva: si el iPhone corta el vídeo (lo hace en cuanto se va el último cliente), la fuente se reabre sola, volviendo a buscar la URL que funcione. Probado matando el emisor a mitad de sesión: 200/200 frames procesados, 27 FPS, sin caerse.
- Espera a que empieces a emitir: al arrancar con una IP, busca la cámara durante 45 s en vez de fallar al instante.
- Los modelos analizan una copia reducida (
--analisis 640) y el HUD se dibuja a resolución completa: mismas detecciones, bastantes fps más en vertical. - El HUD se escala solo al tamaño de la imagen, así que se ve igual de bien en 720p apaisado que en 1080×1920 vertical.
Rendimiento medido
Con --benchmark N mide sin abrir ventana y dice cuántos frames detectaron cada cosa.
RTX 3050, 1280×720, todo activado:
| Escenario | FPS | Detección |
|---|---|---|
| 1280×720, todo activado | ~25 | cara 30/30, manos 30/30, objetos 27/30 |
| 1080×1920 vertical (el iPhone) | ~20 | cara 30/30, manos 30/30, objetos 27/30 |
Reparto: cara + manos ~26 ms (CPU), YOLO11n ~16 ms (CUDA), HUD ~10 ms, identidad ~90 ms en su propio hilo cada 15 frames.
Para ir más rápido: --yolo-cada 5, --no-objects o bajar a --width 960.
Para afinar más: --yolo yolo11s.pt (o m, l, x), que se descargan solos.
Estructura
vision/sources.py captura en hilo aparte (webcam / IP / archivo)
vision/face.py cara, ojos, mirada, expresión, orientación
vision/hands.py manos y gestos
vision/pose.py postura corporal
vision/objects.py YOLO en hilo aparte
vision/identity.py embeddings y base local de caras
vision/hud.py dibujo del HUD
vision/app.py bucle principal y CLI
models/ pesos: face/hand/gesture/pose landmarker + yolo11n.pt
data/test/ vídeos y fotos de prueba (para benchmark sin cámara)
scripts/ enrolar_fotos.py · gente.py · iphone_usb.sh
Instalación desde cero
Requiere Python 3.12 exacto (mediapipe 0.10.21 no soporta 3.13+ todavía)
y, para YOLO por GPU, un driver CUDA. Con uv
(recomendado — así es como está montado este repo):
uv venv --python 3.12 .venv
uv pip install -r requirements.txt
./run --source data/test/demo.mp4 --benchmark 30 # ver arriba: así se verifica sin cámara
Los modelos de MediaPipe (models/*.task) y yolo11n.pt ya vienen incluidos en
el repo (models/, unos 34 MB en total) — no hacen falta descargas aparte para
arrancar. Solo se descargan solos los tamaños de YOLO más grandes si pides
--yolo yolo11s.pt (o m/l/x).
Sin uv, con venv + pip normal funciona igual siempre que el intérprete sea
3.12:
python3.12 -m venv .venv
./.venv/bin/pip install -r requirements.txt
Notas de instalación
Python 3.12 (en el venv, vía uv): mediapipe todavía no funciona con 3.14.
La versión de mediapipe está fijada a 0.10.21 — la 1.0.1 aborta el proceso al
crear el detector facial.
onnxruntime-gpu corre en CPU porque el paquete espera CUDA 12 y aquí hay
CUDA 13 (la que usa torch). No merece la pena romper torch por ello: el
reconocimiento de identidad no necesita GPU tal como está montado.
Licencia
AGPL-3.0 © 2026 macorredor270. Es la licencia de Ultralytics YOLO, del que depende la detección de objetos. Los modelos preentrenados de InsightFace que descarga el reconocimiento de identidad son solo para uso no comercial.