Add vision subpackage with MediaPipe HeadTracker

docs/source/API/openapi.json

@@ -1400,6 +1400,114 @@
         }
       }
     },
+    "/api/media/tracking/enable": {
+      "post": {
+        "summary": "Enable Tracking",
+        "description": "Enable daemon-side visual head tracking.",
+        "operationId": "enable_tracking_api_media_tracking_enable_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "anyOf": [
+                  {
+                    "$ref": "#/components/schemas/EnableTrackingRequest"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "title": "Body"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "boolean"
+                      }
+                    ]
+                  },
+                  "type": "object",
+                  "title": "Response Enable Tracking Api Media Tracking Enable Post"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/media/tracking/disable": {
+      "post": {
+        "summary": "Disable Tracking",
+        "description": "Disable daemon-side visual head tracking.",
+        "operationId": "disable_tracking_api_media_tracking_disable_post",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": {
+                    "anyOf": [
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "boolean"
+                      }
+                    ]
+                  },
+                  "type": "object",
+                  "title": "Response Disable Tracking Api Media Tracking Disable Post"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/media/tracking/face": {
+      "get": {
+        "summary": "Get Tracked Face",
+        "description": "Return the latest face observed by daemon-side head tracking.",
+        "operationId": "get_tracked_face_api_media_tracking_face_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Get Tracked Face Api Media Tracking Face Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/media/sounds/upload": {
       "post": {
         "summary": "Upload Sound",
@@ -2686,6 +2794,9 @@
               }
             ],
             "title": "Hardware Id"
+          },
+          "face_target": {
+            "$ref": "#/components/schemas/FaceTarget"
           }
         },
         "type": "object",
@@ -2720,6 +2831,76 @@
         "title": "DoAInfo",
         "description": "Direction of Arrival info from the microphone array."
       },
+      "EnableTrackingRequest": {
+        "properties": {
+          "weight": {
+            "type": "number",
+            "maximum": 1.0,
+            "minimum": 0.0,
+            "title": "Weight",
+            "default": 1.0
+          }
+        },
+        "type": "object",
+        "title": "EnableTrackingRequest",
+        "description": "Request body for enabling daemon-side head tracking."
+      },
+      "FaceTarget": {
+        "properties": {
+          "detected": {
+            "type": "boolean",
+            "title": "Detected",
+            "default": false
+          },
+          "x": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "X"
+          },
+          "y": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Y"
+          },
+          "roll": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Roll"
+          },
+          "ts": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Ts"
+          }
+        },
+        "type": "object",
+        "title": "FaceTarget",
+        "description": "Latest daemon-side face target used for head tracking."
+      },
       "FullBodyTarget": {
         "properties": {
           "target_head_pose": {

src/reachy_mini/daemon/app/routers/media.py

@@ -14,7 +14,7 @@
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from ....media.gstreamer_utils import is_valid_audio_file
 from ...daemon import Daemon
@@ -68,6 +68,12 @@ class PlaySoundRequest(BaseModel):
     file: str
 
 
+class EnableTrackingRequest(BaseModel):
+    """Request body for enabling daemon-side head tracking."""
+
+    weight: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
 @router.post("/play_sound")
 async def play_sound(
     body: PlaySoundRequest,
@@ -158,6 +164,46 @@ async def disable_wobbling(
     return {"status": "ok"}
 
 
+@router.post("/tracking/enable")
+async def enable_tracking(
+    body: EnableTrackingRequest | None = None,
+    daemon: Daemon = Depends(get_daemon),
+) -> dict[str, str | bool]:
+    """Enable daemon-side visual head tracking."""
+    backend = daemon.backend
+    if backend is None or not backend.ready.is_set():
+        raise HTTPException(status_code=503, detail="Backend not running")
+
+    weight = body.weight if body is not None else 1.0
+    enabled = backend.enable_head_tracking(weight=weight)
+    return {"status": "ok" if enabled else "unavailable", "enabled": enabled}
+
+
+@router.post("/tracking/disable")
+async def disable_tracking(
+    daemon: Daemon = Depends(get_daemon),
+) -> dict[str, str | bool]:
+    """Disable daemon-side visual head tracking."""
+    backend = daemon.backend
+    if backend is None or not backend.ready.is_set():
+        raise HTTPException(status_code=503, detail="Backend not running")
+
+    backend.disable_head_tracking()
+    return {"status": "ok", "enabled": False}
+
+
+@router.get("/tracking/face")
+async def get_tracked_face(
+    daemon: Daemon = Depends(get_daemon),
+) -> dict[str, object]:
+    """Return the latest face observed by daemon-side head tracking."""
+    backend = daemon.backend
+    if backend is None or not backend.ready.is_set():
+        raise HTTPException(status_code=503, detail="Backend not running")
+
+    return {"status": "ok", "face_target": backend.get_tracked_face().model_dump()}
+
+
 @router.post("/sounds/upload")
 async def upload_sound(
     file: UploadFile = File(...),