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