✨(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")
 

src/backend/core/tests/recording/worker/test_factories.py

@@ -2,7 +2,7 @@
 Test worker service factories.
 """
 
-# pylint: disable=protected-access,redefined-outer-name,unused-argument
+# pylint: disable=protected-access,redefined-outer-name,unused-argument,no-member
 
 from dataclasses import FrozenInstanceError
 from unittest.mock import Mock
@@ -10,6 +10,9 @@ from unittest.mock import Mock
 from django.test import override_settings
 
 import pytest
+from livekit import (
+    api as livekit_api_codec,
+)
 
 from core.recording.worker.factories import (
     WorkerService,
@@ -63,6 +66,8 @@ def test_config_initialization(default_config):
         "bucket": "test-bucket",
         "force_path_style": True,
     }
+    # Encoding override is opt-in; disabled by default.
+    assert default_config.encoding_options is None
 
 
 def test_config_immutability(default_config):
@@ -71,6 +76,45 @@ def test_config_immutability(default_config):
         default_config.output_folder = "new/path"
 
 
+@override_settings(
+    RECORDING_OUTPUT_FOLDER="/test/output",
+    LIVEKIT_CONFIGURATION={"server": "test.example.com"},
+    AWS_S3_ENDPOINT_URL="https://s3.test.com",
+    AWS_S3_ACCESS_KEY_ID="test_key",
+    AWS_S3_SECRET_ACCESS_KEY="test_secret",
+    AWS_S3_REGION_NAME="test-region",
+    AWS_STORAGE_BUCKET_NAME="test-bucket",
+    RECORDING_ENCODING_ENABLED=True,
+    RECORDING_ENCODING_WIDTH=1280,
+    RECORDING_ENCODING_HEIGHT=720,
+    RECORDING_ENCODING_FRAMERATE=15,
+    RECORDING_ENCODING_VIDEO_BITRATE_KBPS=600,
+    RECORDING_ENCODING_AUDIO_BITRATE_KBPS=64,
+    RECORDING_ENCODING_KEY_FRAME_INTERVAL_S=10.0,
+)
+def test_config_encoding_options_enabled():
+    """When RECORDING_ENCODING_ENABLED is True, encoding options are populated.
+
+    The dict mixes operator-tunable values from settings with pinned codec /
+    frequency constants, so the services layer can simply unpack it.
+    """
+
+    WorkerServiceConfig.from_settings.cache_clear()
+    config = WorkerServiceConfig.from_settings()
+
+    assert config.encoding_options == {
+        "width": 1280,
+        "height": 720,
+        "framerate": 15,
+        "video_bitrate": 600,
+        "audio_bitrate": 64,
+        "key_frame_interval": 10.0,
+        "video_codec": livekit_api_codec.VideoCodec.H264_MAIN,
+        "audio_codec": livekit_api_codec.AudioCodec.AAC,
+        "audio_frequency": 48000,
+    }
+
+
 @override_settings(
     RECORDING_OUTPUT_FOLDER="/test/output",
     LIVEKIT_CONFIGURATION={"server": "test.example.com"},

src/backend/core/tests/recording/worker/test_services.py

@@ -39,6 +39,31 @@ def config():
     )
 
 
+@pytest.fixture
+def config_with_encoding(config):
+    """Fixture for a config carrying custom encoding options.
+
+    Mirrors the dict shape produced by `WorkerServiceConfig.from_settings()`
+    (operator-tunable values + pinned codec / frequency constants).
+    """
+    return WorkerServiceConfig(
+        output_folder=config.output_folder,
+        server_configurations=config.server_configurations,
+        bucket_args=config.bucket_args,
+        encoding_options={
+            "width": 1280,
+            "height": 720,
+            "framerate": 15,
+            "video_bitrate": 600,
+            "audio_bitrate": 64,
+            "key_frame_interval": 10.0,
+            "video_codec": livekit_api.VideoCodec.H264_MAIN,
+            "audio_codec": livekit_api.AudioCodec.AAC,
+            "audio_frequency": 48000,
+        },
+    )
+
+
 @pytest.fixture
 def mock_s3_upload():
     """Fixture for mocked S3Upload"""
@@ -224,6 +249,41 @@ def test_video_composite_egress_start_missing_egress_id(video_service):
     assert "Egress ID not found" in str(exc_info.value)
 
 
+def test_video_composite_egress_start_without_encoding_options(video_service):
+    """When no encoding options are configured, no `advanced` field is set.
+
+    LiveKit then falls back to its built-in preset (H264_720P_30).
+    """
+    video_service._handle_request.return_value = Mock(egress_id="eg-1")
+    video_service.start("test-room", "rec-1")
+
+    request = video_service._handle_request.call_args[0][0]
+    # Proto oneof `options` must be unset when no advanced encoding is provided.
+    assert request.WhichOneof("options") is None
+
+
+def test_video_composite_egress_start_with_encoding_options(config_with_encoding):
+    """Custom encoding options are forwarded as `advanced` EncodingOptions."""
+    service = VideoCompositeEgressService(config_with_encoding)
+    service._handle_request = Mock(return_value=Mock(egress_id="eg-2"))
+
+    service.start("test-room", "rec-2")
+
+    request = service._handle_request.call_args[0][0]
+    assert request.WhichOneof("options") == "advanced"
+
+    advanced = request.advanced
+    assert advanced.width == 1280
+    assert advanced.height == 720
+    assert advanced.framerate == 15
+    assert advanced.video_bitrate == 600
+    assert advanced.audio_bitrate == 64
+    assert advanced.key_frame_interval == pytest.approx(10.0)
+    assert advanced.video_codec == livekit_api.VideoCodec.H264_MAIN
+    assert advanced.audio_codec == livekit_api.AudioCodec.AAC
+    assert advanced.audio_frequency == 48000
+
+
 def test_audio_composite_egress_hrid(audio_service):
     """Test HRID is correct"""
     assert audio_service.hrid == "audio-recording-composite-livekit-egress"

src/backend/meet/settings.py

@@ -700,6 +700,44 @@ class Base(Configuration):
     RECORDING_MAX_DURATION = values.IntegerValue(
         None, environ_name="RECORDING_MAX_DURATION", environ_prefix=None
     )
+
+    # Recording encoding options for LiveKit Egress (video composite egress only).
+    # These settings affect screen recordings handled by VideoCompositeEgressService;
+    # they are silently ignored by AudioCompositeEgressService (audio-only transcript
+    # recordings), whose request never carries advanced EncodingOptions.
+    # When disabled, LiveKit falls back to its built-in H264_720P_30 preset
+    # (1280x720, 30 fps, 3000 kbps H.264 MAIN video, 128 kbps AAC audio).
+    # When enabled, the values below are passed to LiveKit as EncodingOptions
+    # (advanced) and replace the preset. Lowering framerate and bitrate reduces
+    # output file size and CPU load on the egress worker.
+    RECORDING_ENCODING_ENABLED = values.BooleanValue(
+        False, environ_name="RECORDING_ENCODING_ENABLED", environ_prefix=None
+    )
+    RECORDING_ENCODING_WIDTH = values.PositiveIntegerValue(
+        1280, environ_name="RECORDING_ENCODING_WIDTH", environ_prefix=None
+    )
+    RECORDING_ENCODING_HEIGHT = values.PositiveIntegerValue(
+        720, environ_name="RECORDING_ENCODING_HEIGHT", environ_prefix=None
+    )
+    RECORDING_ENCODING_FRAMERATE = values.PositiveIntegerValue(
+        30, environ_name="RECORDING_ENCODING_FRAMERATE", environ_prefix=None
+    )
+    RECORDING_ENCODING_VIDEO_BITRATE_KBPS = values.PositiveIntegerValue(
+        3000,
+        environ_name="RECORDING_ENCODING_VIDEO_BITRATE_KBPS",
+        environ_prefix=None,
+    )
+    RECORDING_ENCODING_AUDIO_BITRATE_KBPS = values.PositiveIntegerValue(
+        128,
+        environ_name="RECORDING_ENCODING_AUDIO_BITRATE_KBPS",
+        environ_prefix=None,
+    )
+    RECORDING_ENCODING_KEY_FRAME_INTERVAL_S = values.FloatValue(
+        4.0,
+        environ_name="RECORDING_ENCODING_KEY_FRAME_INTERVAL_S",
+        environ_prefix=None,
+    )
+
     SUMMARY_SERVICE_ENDPOINT = values.Value(
         None, environ_name="SUMMARY_SERVICE_ENDPOINT", environ_prefix=None
     )