Add Backup Codec Support to Python SDK

[mc4future]

Overview

This PR adds support for backup codec configuration when publishing tracks, bringing the Python SDK to feature parity with the JavaScript SDK. This allows developers to specify codec fallback behavior for improved compatibility across different clients and network conditions.

Background

While investigating the Python SDK, I discovered that the BackupCodecPolicy enum exists at the protocol level, but the high-level TrackPublishOptions API doesn't expose it. The JavaScript SDK already has this feature via the backupCodec option in TrackPublishOptions.

Reference conversation with LiveKit team confirmed that:

• TrackInfo (protocol level) has backup_codec_policy field
• BackupCodecPolicy enum exists with values: PREFER_REGRESSION (0), SIMULCAST (1), REGRESSION (2)
• Python SDK hadn't exposed this feature in the high-level publishing API yet

Changes

Files Modified

1. livekit-rtc/livekit/rtc/__init__.py

   • Import BackupCodecPolicy enum from livekit.protocol.models
   • Export in __all__ for public API access
   • Graceful fallback if protocol package unavailable

2. livekit-rtc/livekit/rtc/participant.py

   • Extended LocalParticipant.publish_track() with two new keyword-only parameters:
     • backup_codec_policy: Optional[int] - Accepts BackupCodecPolicy enum values
     • backup_codec: Optional[str] - Accepts codec name (e.g., "vp8", "h264")
   • Dynamic field setting with try-except for forward compatibility
   • Warning logs if FFI protocol doesn't support fields
   • Updated docstring with parameter documentation

Usage

Basic Example

from livekit import rtc

# Create track and options
source = rtc.VideoSource(1280, 720)
track = rtc.LocalVideoTrack.create_video_track("my-track", source)
options = rtc.TrackPublishOptions(
    source=rtc.TrackSource.SOURCE_CAMERA,
    video_codec=rtc.VideoCodec.VP8,
)

# Publish with backup codec policy
publication = await room.local_participant.publish_track(
    track,
    options,
    backup_codec_policy=rtc.BackupCodecPolicy.PREFER_REGRESSION
)

Advanced Example

# Specify both policy and specific backup codec
publication = await room.local_participant.publish_track(
    track,
    options,
    backup_codec_policy=rtc.BackupCodecPolicy.SIMULCAST,
    backup_codec="h264"
)

BackupCodecPolicy Values

• PREFER_REGRESSION (0) - Prefer codec regression over simulcast for backup
• SIMULCAST (1) - Use simulcast for backup codec
• REGRESSION (2) - Use codec regression for backup

Compatibility

Backward Compatibility

✅ Fully backward compatible - All existing code continues to work without modifications. The new parameters are optional keyword-only arguments.

Forward Compatibility

✅ Graceful degradation - If FFI protocol doesn't support backup codec fields:

• Warnings are logged
• Publishing continues without backup codec
• No breaking changes or errors

JavaScript SDK Parity

JavaScript:

await room.localParticipant.publishTrack(track, {
  videoCodec: 'vp8',
  backupCodec: { codec: 'h264' },
});

Python (now):

await room.local_participant.publish_track(
    track, options,
    backup_codec_policy=rtc.BackupCodecPolicy.PREFER_REGRESSION,
    backup_codec="h264"
)

Implementation Details

The implementation attempts to set backup codec fields on the protobuf message dynamically:

if backup_codec_policy is not None:
    try:
        req.publish_track.options.backup_codec_policy = backup_codec_policy
    except AttributeError:
        logger.warning("backup_codec_policy field not available...")

This approach ensures that:

1. If the FFI protocol supports the fields, they are set correctly
2. If not, a warning is logged and publishing continues normally
3. No breaking changes occur in either scenario

Testing

• ✅ No linter errors introduced
• ✅ Backward compatibility maintained
• ✅ New parameters properly documented
• ⚠️ Runtime testing requires LiveKit server with backup codec support

Notes

FFI Protocol Dependency: The implementation assumes FFI protocol support for backup_codec_policy and backup_codec fields in TrackPublishOptions. If these fields aren't present in the current protocol version, warnings will be logged and publishing continues without backup codec support.

Checklist

• Code follows existing style and conventions
• Backward compatible with existing API
• No linter errors
• Graceful error handling implemented
• Parameters properly documented in docstring
• Runtime testing with LiveKit server (requires server setup)

[CLAassistant]

All committers have signed the CLA.