✨(backend) add metadata collection of VAD, connection and chat events

Introduce MetadataCollector and MetadataCollectorService classes to
centralize the collection and storage of user connections, VAD events,
and chat messages. This creates a structured foundation for future speaker
assignment logic based on voice activity detection. Add tests for this new
feature.

src/backend/core/api/viewsets.py

@@ -45,6 +45,10 @@ from core.recording.event.exceptions import (
 )
 from core.recording.event.notification import notification_service
 from core.recording.event.parsers import get_parser
+from core.recording.services.metadata_collector import (
+    MetadataCollectorException,
+    MetadataCollectorService,
+)
 from core.recording.worker.exceptions import (
     RecordingStartError,
     RecordingStopError,
@@ -338,6 +342,15 @@ class RoomViewSet(
                 status=drf_status.HTTP_500_INTERNAL_SERVER_ERROR,
             )
 
+        if settings.METADATA_COLLECTOR_ENABLED and (
+            recording.mode == models.RecordingModeChoices.TRANSCRIPT
+            or recording.options.get("transcribe", False)
+        ):
+            try:
+                MetadataCollectorService().start(recording)
+            except MetadataCollectorException:
+                logger.warning("Failed to start MetadataCollectorService")
+
         return drf_response.Response(
             {"message": f"Recording successfully started for room {room.slug}"},
             status=drf_status.HTTP_201_CREATED,

src/backend/core/recording/services/metadata_collector.py

@@ -0,0 +1,91 @@
+"""Meeting metadata collection service."""
+
+from logging import getLogger
+
+from django.conf import settings
+
+from asgiref.sync import async_to_sync, sync_to_async
+from livekit.protocol.agent_dispatch import (
+    CreateAgentDispatchRequest,
+)
+
+from core import utils
+from core.models import Recording
+
+logger = getLogger(__name__)
+
+
+class MetadataCollectorException(Exception):
+    """Generic exception in the metadata collector."""
+
+
+class MetadataCollectorService:
+    """Service for dispatching and managing the metadata collector agent."""
+
+    @async_to_sync
+    async def start(self, recording: Recording):
+        """Explicitly dispatch the metadata collector agent to a room."""
+
+        lkapi = utils.create_livekit_client()
+        room_id = str(recording.room.id)
+
+        try:
+            response = await lkapi.agent_dispatch.create_dispatch(
+                CreateAgentDispatchRequest(
+                    agent_name=settings.METADATA_COLLECTOR_AGENT_NAME,
+                    room=room_id,
+                    metadata=str(recording.id),
+                )
+            )
+        except Exception as e:
+            logger.exception(
+                "Failed to create metadata collector agent for room %s", room_id
+            )
+            raise MetadataCollectorException(
+                "Failed to create metadata collector agent"
+            ) from e
+        finally:
+            await lkapi.aclose()
+
+        dispatch_id = getattr(response, "id", None)
+
+        if not dispatch_id:
+            logger.error("LiveKit response missing dispatch ID for room %s", room_id)
+            raise MetadataCollectorException(
+                f"LiveKit did not return a dispatch_id for room {room_id}"
+            )
+
+        recording.options["metadata_collector_dispatch_id"] = dispatch_id
+        await sync_to_async(recording.save)(update_fields=["options"])
+
+        return dispatch_id
+
+    @async_to_sync
+    async def stop(self, recording: Recording):
+        """Stop and delete the agent dispatch associated to the room."""
+
+        room_id = str(recording.room.id)
+        dispatch_id = recording.options.get("metadata_collector_dispatch_id")
+        lkapi = utils.create_livekit_client()
+
+        try:
+            if not dispatch_id:
+                logger.warning(
+                    "No metadata collector dispatch ID stored for room %s", room_id
+                )
+                return None
+
+            await lkapi.agent_dispatch.delete_dispatch(
+                dispatch_id=str(dispatch_id), room_name=room_id
+            )
+
+        except Exception as e:
+            logger.exception(
+                "Failed to stop metadata collector agent dispatch for room %s",
+                room_id,
+            )
+            raise MetadataCollectorException(
+                f"Failed to stop metadata collector agent for room {room_id}"
+            ) from e
+        finally:
+            await lkapi.aclose()

src/backend/core/recording/services/recording_events.py

@@ -7,6 +7,7 @@ from logging import getLogger
 from livekit import api
 
 from core import models, utils
+from core.models import Recording
 
 logger = getLogger(__name__)
 
@@ -19,7 +20,7 @@ class RecordingEventsService:
     """Handles recording-related LiveKit webhook events."""
 
     @staticmethod
-    def handle_update(recording, egress_status):
+    def handle_update(recording: Recording, egress_status):
         """Handle egress status updates and sync recording state to room metadata."""
 
         room_name = str(recording.room.id)
@@ -40,7 +41,7 @@ class RecordingEventsService:
                 logger.exception("Failed to update room's metadata: %s", e)
 
     @staticmethod
-    def handle_limit_reached(recording):
+    def handle_limit_reached(recording: Recording):
         """Stop recording and notify participants when limit is reached."""
 
         recording.status = models.RecordingStatusChoices.STOPPED

src/backend/core/services/livekit_events.py

@@ -12,6 +12,10 @@ from django.conf import settings
 from livekit import api
 
 from core import models, utils
+from core.recording.services.metadata_collector import (
+    MetadataCollectorException,
+    MetadataCollectorService,
+)
 from core.recording.services.recording_events import (
     RecordingEventsError,
     RecordingEventsService,
@@ -158,7 +162,7 @@ class LiveKitEventsService:
         """Handle 'egress_ended' event."""
 
         try:
-            recording = models.Recording.objects.get(
+            recording = models.Recording.objects.select_related("room").get(
                 worker_id=data.egress_info.egress_id
             )
         except models.Recording.DoesNotExist as err:
@@ -174,6 +178,14 @@ class LiveKitEventsService:
         except utils.MetadataUpdateException as e:
             logger.exception("Failed to update room's metadata: %s", e)
 
+        if settings.METADATA_COLLECTOR_ENABLED and recording.options.get(
+            "metadata_collector_dispatch_id"
+        ):
+            try:
+                MetadataCollectorService().stop(recording)
+            except MetadataCollectorException:
+                logger.warning("Failed to stop the MetadataCollectorService")
+
         if (
             data.egress_info.status == api.EgressStatus.EGRESS_LIMIT_REACHED
             and recording.status == models.RecordingStatusChoices.ACTIVE

src/backend/core/tests/rooms/test_api_rooms_start_recording.py

@@ -277,6 +277,7 @@ def test_start_recording_options_transcribe_valid_true(
 ):
     """Should accept transcribe with any valid pydantic true values."""
     settings.RECORDING_ENABLE = True
+    settings.METADATA_COLLECTOR_ENABLED = False
     room = RoomFactory()
     user = UserFactory()
     room.accesses.create(user=user, role="owner")
@@ -487,6 +488,93 @@ def test_start_recording_options_original_mode_omitted(
     assert recording.options == {}
 
 
+def test_start_recording_calls_metadata_collector_start(
+    settings, mock_worker_service_factory, mock_worker_manager
+):
+    """Should call MetadataCollectorService.start when conditions are met."""
+    settings.RECORDING_ENABLE = True
+    settings.METADATA_COLLECTOR_ENABLED = True
+
+    room = RoomFactory()
+    user = UserFactory()
+    room.accesses.create(user=user, role="owner")
+
+    client = APIClient()
+    client.force_login(user)
+
+    with mock.patch(
+        "core.api.viewsets.MetadataCollectorService"
+    ) as mock_collector_class:
+        mock_collector = mock.Mock()
+        mock_collector_class.return_value = mock_collector
+
+        response = client.post(
+            f"/api/v1.0/rooms/{room.id}/start-recording/",
+            {
+                "mode": "screen_recording",
+                "options": {"transcribe": True, "collect_metadata": True},
+            },
+            format="json",
+        )
+
+    assert response.status_code == 201
+
+    recording = Recording.objects.get(room=room)
+    mock_collector.start.assert_called_once_with(recording)
+
+
+@pytest.mark.parametrize(
+    "metadata_enabled,options",
+    [
+        # Metadata collector disabled, regardless of transcribe option
+        (False, {"transcribe": True}),
+        (False, {"transcribe": False}),
+        (False, None),
+        # Metadata collector enabled, but transcribe is False or missing
+        (True, {"transcribe": False}),
+        (True, None),
+        # Metadata collector enabled, transcribe True, but collect_metadata explicitly False
+        (True, {"transcribe": True, "collect_metadata": False}),
+    ],
+)
+def test_start_recording_does_not_call_metadata_collector_start_when_conditions_not_met(
+    settings,
+    mock_worker_service_factory,
+    mock_worker_manager,
+    metadata_enabled,
+    options,
+):
+    """Should not call MetadataCollectorService.start when conditions are not met."""
+    settings.RECORDING_ENABLE = True
+    settings.METADATA_COLLECTOR_ENABLED = metadata_enabled
+
+    room = RoomFactory()
+    user = UserFactory()
+    room.accesses.create(user=user, role="owner")
+
+    client = APIClient()
+    client.force_login(user)
+
+    payload = {"mode": "screen_recording"}
+    if options is not None:
+        payload["options"] = options
+
+    with mock.patch(
+        "core.api.viewsets.MetadataCollectorService"
+    ) as mock_collector_class:
+        mock_collector = mock.Mock()
+        mock_collector_class.return_value = mock_collector
+
+        response = client.post(
+            f"/api/v1.0/rooms/{room.id}/start-recording/",
+            payload,
+            format="json",
+        )
+
+    assert response.status_code == 201
+    mock_collector.start.assert_not_called()
+
+
 @pytest.mark.parametrize("value", ["invalid_mode", "foo", 123, "SCREEN_RECORDING"])
 def test_start_recording_options_original_mode_invalid(settings, value):
     """Should reject invalid recording mode values for original_mode."""

src/backend/core/tests/services/test_livekit_events.py

@@ -269,6 +269,63 @@ def test_handle_egress_ended_recording_not_limit_reached(
     assert recording.status == "stopped"
 
 
+@mock.patch("core.services.livekit_events.MetadataCollectorService")
+@mock.patch("core.utils.update_room_metadata")
+def test_handle_egress_ended_calls_metadata_collector_stop_when_conditions_are_met(
+    mock_update_room_metadata, mock_collector_class, service, settings
+):
+    """Should call MetadataCollectorService.stop when it exists."""
+    settings.METADATA_COLLECTOR_ENABLED = True
+
+    recording = RecordingFactory(
+        worker_id="worker-1",
+        status="active",
+        options={"metadata_collector_dispatch_id": "dispatch-123"},
+    )
+    mock_data = mock.MagicMock()
+    mock_data.egress_info.egress_id = recording.worker_id
+    mock_data.egress_info.status = EgressStatus.EGRESS_COMPLETE
+
+    mock_collector = mock.Mock()
+    mock_collector_class.return_value = mock_collector
+
+    service._handle_egress_ended(mock_data)
+
+    mock_collector.stop.assert_called_once_with(recording)
+
+
+@pytest.mark.parametrize(
+    "metadata_enabled,options",
+    [
+        (True, {}),
+        (False, {}),
+    ],
+)
+@mock.patch("core.services.livekit_events.MetadataCollectorService")
+@mock.patch("core.utils.update_room_metadata")
+def test_handle_egress_ended_does_not_call_metadata_collector_stop_when_conditions_not_met(
+    _, mock_collector_class, metadata_enabled, options, service, settings
+):  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    """Should not call MetadataCollectorService.stop when it does not exist."""
+    settings.METADATA_COLLECTOR_ENABLED = metadata_enabled
+
+    recording = RecordingFactory(
+        worker_id="worker-1",
+        status="active",
+        options=options,
+    )
+    mock_data = mock.MagicMock()
+    mock_data.egress_info.egress_id = recording.worker_id
+    mock_data.egress_info.status = EgressStatus.EGRESS_COMPLETE
+
+    mock_collector = mock.Mock()
+    mock_collector_class.return_value = mock_collector
+
+    service._handle_egress_ended(mock_data)
+
+    mock_collector.stop.assert_not_called()
+
+
 @mock.patch.object(LobbyService, "clear_room_cache")
 @mock.patch.object(TelephonyService, "delete_dispatch_rule")
 def test_handle_room_finished_clears_cache_and_deletes_dispatch_rule(

src/backend/meet/settings.py

@@ -808,6 +808,16 @@ class Base(Configuration):
         environ_prefix=None,
     )
 
+    # Metadata collector settings
+    METADATA_COLLECTOR_ENABLED = values.BooleanValue(
+        False, environ_name="METADATA_COLLECTOR_ENABLED", environ_prefix=None
+    )
+    METADATA_COLLECTOR_AGENT_NAME = values.Value(
+        "metadata-collector",
+        environ_name="METADATA_COLLECTOR_AGENT_NAME",
+        environ_prefix=None,
+    )
+
     # External Applications
     APPLICATION_CLIENT_ID_LENGTH = values.PositiveIntegerValue(
         40,