✨(backend) make LiveKit Egress recording encoding configurable

Expose RECORDING_ENCODING_* settings to override the default LiveKit
Egress preset (H264_720P_30). When RECORDING_ENCODING_ENABLED is True,
the provided width/height/framerate/bitrate/keyframe values are passed
as advanced EncodingOptions. Lowering framerate and bitrate reduces
recording file size and egress worker CPU load.

Disabled by default, preserving current behaviour.

src/backend/core/recording/worker/factories.py

@@ -1,5 +1,7 @@
 """Factory, configurations and Protocol to create worker services"""
 
+# pylint: disable=no-member
+
 import logging
 from dataclasses import dataclass
 from functools import lru_cache
@@ -8,8 +10,17 @@ from typing import Any, ClassVar, Dict, Optional, Protocol, Type
 from django.conf import settings
 from django.utils.module_loading import import_string
 
+from livekit import api as livekit_api
+
 logger = logging.getLogger(__name__)
 
+# Codec / frequency constants matching LiveKit's H264_720P_30 preset.
+# Kept fixed because changing them would shift the goal-post away from the
+# "safe drop-in replacement for the default preset" contract of this feature.
+_RECORDING_VIDEO_CODEC = livekit_api.VideoCodec.H264_MAIN
+_RECORDING_AUDIO_CODEC = livekit_api.AudioCodec.AAC
+_RECORDING_AUDIO_FREQUENCY_HZ = 48000
+
 
 @dataclass(frozen=True)
 class WorkerServiceConfig:
@@ -18,6 +29,7 @@ class WorkerServiceConfig:
     output_folder: str
     server_configurations: Dict[str, Any]
     bucket_args: Optional[dict]
+    encoding_options: Optional[Dict[str, Any]] = None
 
     @classmethod
     @lru_cache
@@ -25,6 +37,24 @@ class WorkerServiceConfig:
         """Load configuration from Django settings with caching for efficiency."""
 
         logger.debug("Loading WorkerServiceConfig from settings.")
+
+        encoding_options: Optional[Dict[str, Any]] = None
+        if settings.RECORDING_ENCODING_ENABLED:
+            # Single source of truth for the EncodingOptions kwargs:
+            # operator-tunable values live in Django settings, codec / frequency
+            # are pinned constants. The services layer only unpacks this dict.
+            encoding_options = {
+                "width": settings.RECORDING_ENCODING_WIDTH,
+                "height": settings.RECORDING_ENCODING_HEIGHT,
+                "framerate": settings.RECORDING_ENCODING_FRAMERATE,
+                "video_bitrate": settings.RECORDING_ENCODING_VIDEO_BITRATE_KBPS,
+                "audio_bitrate": settings.RECORDING_ENCODING_AUDIO_BITRATE_KBPS,
+                "key_frame_interval": settings.RECORDING_ENCODING_KEY_FRAME_INTERVAL_S,
+                "video_codec": _RECORDING_VIDEO_CODEC,
+                "audio_codec": _RECORDING_AUDIO_CODEC,
+                "audio_frequency": _RECORDING_AUDIO_FREQUENCY_HZ,
+            }
+
         return cls(
             output_folder=settings.RECORDING_OUTPUT_FOLDER,
             server_configurations=settings.LIVEKIT_CONFIGURATION,
@@ -36,6 +66,7 @@ class WorkerServiceConfig:
                 "bucket": settings.AWS_STORAGE_BUCKET_NAME,
                 "force_path_style": True,
             },
+            encoding_options=encoding_options,
         )
 
 

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

@@ -83,6 +83,22 @@ class BaseEgressService:
         """
         raise NotImplementedError("Subclass must implement this method.")
 
+    def _build_encoding_options(self):
+        """Build a LiveKit EncodingOptions from the service config, or None.
+
+        When None is returned, the caller should omit the `advanced` field so
+        LiveKit Egress falls back to its built-in preset (H264_720P_30).
+
+        The full EncodingOptions kwargs (operator-tunable values + pinned
+        codec / frequency constants) are assembled in `WorkerServiceConfig`,
+        so this method is a thin protobuf adapter.
+        """
+        opts = self._config.encoding_options
+        if not opts:
+            return None
+
+        return livekit_api.EncodingOptions(**opts)
+
 
 class VideoCompositeEgressService(BaseEgressService):
     """Record multiple participant video and audio tracks into a single output '.mp4' file."""
@@ -104,9 +120,17 @@ class VideoCompositeEgressService(BaseEgressService):
             s3=self._s3,
         )
 
-        request = livekit_api.RoomCompositeEgressRequest(
-            room_name=room_name, file_outputs=[file_output], layout="speaker-light"
-        )
+        request_kwargs = {
+            "room_name": room_name,
+            "file_outputs": [file_output],
+            "layout": "speaker-light",
+        }
+
+        advanced = self._build_encoding_options()
+        if advanced is not None:
+            request_kwargs["advanced"] = advanced
+
+        request = livekit_api.RoomCompositeEgressRequest(**request_kwargs)
 
         response = self._handle_request(request, "start_room_composite_egress")