✨(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.

Author: damienlaine

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- ✨(backend) make LiveKit Egress recording encoding configurable #1288
+
 ## [1.15.0] - 2026-04-30
 
 ### Added

docs/features/recording.md

@@ -100,6 +100,13 @@ sequenceDiagram
 | **RECORDING_STORAGE_EVENT_TOKEN**       | Secret/File | `None`                                                                                                                                                             | Token used to authenticate storage webhook requests, if `RECORDING_ENABLE_STORAGE_EVENT_AUTH` is enabled.                                                                                                                                                                                          |
 | **RECORDING_EXPIRATION_DAYS**           | Integer     | `None`                                                                                                                                                             | Number of days before recordings expire. Should match bucket lifecycle policy. Set to `None` for no expiration.                                                                                                                                                                                    |
 | **RECORDING_MAX_DURATION**              | Integer     | `None`                                                                                                                                                             | Maximum duration of a recording in milliseconds. Must be synced with the LiveKit Egress configuration. Set to None for unlimited duration. When the maximum duration is reached, the recording is automatically stopped and saved, and the user is prompted in the frontend with an alert message. |
+| **RECORDING_ENCODING_ENABLED**          | Boolean     | `False`                                                                                                                                                            | When `False`, LiveKit Egress uses its built-in `H264_720P_30` preset. When `True`, the `RECORDING_ENCODING_*` values below are sent to LiveKit as advanced `EncodingOptions`. See [Tuning recording encoding](#tuning-recording-encoding).                                                          |
+| **RECORDING_ENCODING_WIDTH**            | Integer     | `1280`                                                                                                                                                             | Recording video width in pixels. Only applied when `RECORDING_ENCODING_ENABLED` is `True`.                                                                                                                                                                                                         |
+| **RECORDING_ENCODING_HEIGHT**           | Integer     | `720`                                                                                                                                                              | Recording video height in pixels. Only applied when `RECORDING_ENCODING_ENABLED` is `True`.                                                                                                                                                                                                        |
+| **RECORDING_ENCODING_FRAMERATE**        | Integer     | `30`                                                                                                                                                               | Recording video framerate (fps). Directly impacts egress worker CPU (roughly linear). Only applied when `RECORDING_ENCODING_ENABLED` is `True`.                                                                                                                                                    |
+| **RECORDING_ENCODING_VIDEO_BITRATE_KBPS** | Integer   | `3000`                                                                                                                                                             | H.264 MAIN video bitrate in kbps. Only applied when `RECORDING_ENCODING_ENABLED` is `True`.                                                                                                                                                                                                        |
+| **RECORDING_ENCODING_AUDIO_BITRATE_KBPS** | Integer   | `128`                                                                                                                                                              | AAC audio bitrate in kbps. Only applied when `RECORDING_ENCODING_ENABLED` is `True`.                                                                                                                                                                                                               |
+| **RECORDING_ENCODING_KEY_FRAME_INTERVAL_S** | Float   | `4.0`                                                                                                                                                              | Keyframe interval in seconds. Drives seek granularity in the recorded MP4 (a player can only seek to keyframe boundaries). Larger values give the encoder slightly more bits for non-keyframe content at a fixed bitrate. `4.0` is a standard VOD value. Only applied when `RECORDING_ENCODING_ENABLED` is `True`. |
 
 
 ### Manual Storage Webhook
@@ -141,3 +148,54 @@ Using default project meet
 
 This allows you to verify which recordings are in progress, troubleshoot egress issues, and confirm that recordings are being processed correctly.
 
+## Tuning recording encoding
+
+By default, LiveKit Egress records with the built-in `H264_720P_30` preset: 1280×720 at 30 fps, 3000 kbps H.264 MAIN video and 128 kbps AAC audio. For a one-hour meeting this produces a file of roughly **1.4 GB**, which is often heavier than necessary for talking-head content and screen sharing.
+
+The `RECORDING_ENCODING_*` settings let operators override this preset without modifying the source. Values are passed straight through LiveKit's `EncodingOptions.advanced` to the GStreamer pipeline (`x264enc` for video, `faac` for audio), so there are no hidden conversions — what you set is what the encoder receives.
+
+### How values map to GStreamer
+
+| Setting                               | GStreamer element | Property                           |
+| ------------------------------------- | ----------------- | ---------------------------------- |
+| `RECORDING_ENCODING_WIDTH/HEIGHT`     | capsfilter        | `video/x-raw,width=W,height=H`     |
+| `RECORDING_ENCODING_FRAMERATE`        | capsfilter        | `framerate=F/1`                    |
+| `RECORDING_ENCODING_VIDEO_BITRATE_KBPS` | `x264enc`       | `bitrate=kbps` (kilobits)          |
+| `RECORDING_ENCODING_KEY_FRAME_INTERVAL_S` | `x264enc`     | `key-int-max = interval × fps`     |
+| `RECORDING_ENCODING_AUDIO_BITRATE_KBPS` | `faac`          | `bitrate = kbps × 1000` (bits)     |
+
+The H.264 profile is fixed to MAIN and the x264 `speed-preset` to `veryfast` by LiveKit (real-time constraint) — lowering the framerate is therefore the main lever to save CPU, while lowering the bitrate is the main lever to shrink the output file.
+
+### Reference profiles
+
+Rough 30-minute file-size estimates assume video + audio bitrate multiplied by duration. Actual sizes vary with content (static talking heads compress better than heavy screen motion). Egress CPU figures are indicative, measured on a single Ryzen laptop core saturated by the default preset (= 100 %); scaling is roughly linear with `framerate × bitrate` but the absolute numbers depend on the host hardware.
+
+| Profile                | Resolution | FPS | Video (kbps) | Audio (kbps) | Keyframe (s) | ~ size / 30 min | Egress CPU (vs. default) | Suitable for                                        |
+| ---------------------- | ---------- | --- | ------------ | ------------ | ------------ | --------------- | ------------------------ | --------------------------------------------------- |
+| Default (preset)       | 1280×720   | 30  | 3000         | 128          | 4            | **~690 MB**     | 100 %                    | Unchanged LiveKit behaviour                         |
+| Balanced               | 1280×720   | 20  | 1000         | 96           | 4            | ~240 MB         | ~67 %                    | Mixed content, moderate motion                      |
+| **Low CPU / small file** | 1280×720 | 15  | 600          | 64           | 4            | **~150 MB**     | ~50 %                    | Talking-head dominant meetings + occasional slides ★ |
+| Slide-heavy            | 1280×720   | 15  | 900          | 64           | 4            | ~210 MB         | ~55 %                    | Frequent dense screen sharing (decks, IDE, docs)    |
+| Minimum CPU            | 960×540    | 15  | 500          | 64           | 4            | ~125 MB         | ~30 %                    | Voice-first meetings, readable text not required    |
+| Audio-heavy fallback   | 1280×720   | 10  | 400          | 96           | 4            | ~110 MB         | ~35 %                    | Long webinars, low motion                           |
+
+★ Recommended starting point for typical LaSuite Meet usage.
+
+Environment variables for the **Low CPU / small file** profile:
+
+```bash
+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=4.0
+```
+
+### Caveats
+
+- **Screen-share readability — think bits/frame, not bitrate**: at 720p, text legibility starts to break down below ~40 kbits/frame (= `bitrate ÷ framerate`). The recommended preset (600 kbps × 15 fps) sits at exactly that threshold, comfortable for talking heads with occasional slide sharing. The same 600 kbps at 30 fps would only deliver 20 kbits/frame and visibly blur dense slides — which is why **lowering framerate is a more screen-share-friendly lever than lowering bitrate**. For deck-heavy or IDE-share meetings, prefer the **Slide-heavy** profile (900 kbps × 15 fps ≈ 60 kbits/frame).
+- **Motion handling**: the `veryfast` x264 preset is set by LiveKit and cannot be overridden here. Low-bitrate settings will therefore show more artefacts on fast motion than an offline re-encode with a slower preset would. This is the other reason FPS reduction is the safer tuning lever for meeting recordings.
+- **Audio**: AAC at 64 kbps stereo is transparent for voice but starts to compress music noticeably. Keep 128 kbps if you expect music playback in meetings.
+- **Codec choice**: H.264 MAIN is hardcoded on purpose. Switching to HEVC or VP9 would increase egress CPU cost 2×–5×, defeating the goal of this tuning.

env.d/development/common.dist

@@ -68,6 +68,18 @@ SUMMARY_SERVICE_ENDPOINT=http://app-summary-dev:8000/api/v1/tasks/
 SUMMARY_SERVICE_API_TOKEN=password
 RECORDING_DOWNLOAD_BASE_URL=http://localhost:3000/recording
 
+# Recording encoding (LiveKit Egress advanced options).
+# When RECORDING_ENCODING_ENABLED is False (default), LiveKit uses its built-in
+# H264_720P_30 preset (1280x720, 30fps, 3000 kbps). Enable and tune to reduce
+# file size and CPU load on the egress worker.
+# RECORDING_ENCODING_ENABLED=False
+# RECORDING_ENCODING_WIDTH=1280
+# RECORDING_ENCODING_HEIGHT=720
+# RECORDING_ENCODING_FRAMERATE=30
+# RECORDING_ENCODING_VIDEO_BITRATE_KBPS=3000
+# RECORDING_ENCODING_AUDIO_BITRATE_KBPS=128
+# RECORDING_ENCODING_KEY_FRAME_INTERVAL_S=4.0
+
 # Telephony
 ROOM_TELEPHONY_ENABLED=True
 

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

@@ -8,8 +8,17 @@
 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,13 +27,32 @@ class WorkerServiceConfig:
     output_folder: str
     server_configurations: Dict[str, Any]
     bucket_args: Optional[dict]
+    encoding_options: Optional[Dict[str, Any]] = None
 
     @classmethod
     @lru_cache
     def from_settings(cls) -> "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 +64,7 @@ def from_settings(cls) -> "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 @@ def start(self, room_name, recording_id):
         """
         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 @@ def start(self, room_name, recording_id):
             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

@@ -63,6 +63,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 +73,46 @@ 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.
+    """
+    from livekit import api as livekit_api  # local import: avoid Django import order issues
+
+    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.VideoCodec.H264_MAIN,
+        "audio_codec": livekit_api.AudioCodec.AAC,
+        "audio_frequency": 48000,
+    }
+
+
 @override_settings(
     RECORDING_OUTPUT_FOLDER="/test/output",
     LIVEKIT_CONFIGURATION={"server": "test.example.com"},