keep Packet Trailer names as deprecated aliases

Mirror livekit/client-sdk-js#1982: keep the old "Packet Trailer" SDK
surface as backwards-compatible deprecated aliases that point at the new
Frame Metadata names, so existing code keeps working.

  - rtc.PacketTrailerFeature -> alias of rtc.FrameMetadataFeature
  - TrackPublication.packet_trailer_features -> deprecated property that
    warns and returns frame_metadata_features

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: chenghao-mou

livekit-rtc/livekit/rtc/__init__.py

@@ -134,6 +134,10 @@
 )
 from .frame_processor import FrameProcessor
 
+# Deprecated alias: "Packet Trailer" was renamed to "Frame Metadata" upstream.
+# Prefer FrameMetadataFeature; this alias will be removed in a future release.
+PacketTrailerFeature = FrameMetadataFeature
+
 __all__ = [
     "ConnectionQuality",
     "ConnectionState",
@@ -149,6 +153,7 @@
     "TrackKind",
     "TrackSource",
     "FrameMetadataFeature",
+    "PacketTrailerFeature",
     "ParticipantTrackPermission",
     "VideoBufferType",
     "VideoRotation",

livekit-rtc/livekit/rtc/track_publication.py

@@ -14,6 +14,7 @@
 
 from typing import List, Optional, cast
 import asyncio
+import warnings
 
 from ._ffi_client import FfiHandle, FfiClient
 from ._proto import e2ee_pb2 as proto_e2ee
@@ -83,6 +84,16 @@ def audio_features(self) -> List[proto_track.AudioTrackFeature.ValueType]:
     def frame_metadata_features(self) -> List[proto_track.FrameMetadataFeature.ValueType]:
         return list(self._info.frame_metadata_features)
 
+    @property
+    def packet_trailer_features(self) -> List[proto_track.FrameMetadataFeature.ValueType]:
+        """Deprecated: renamed to :attr:`frame_metadata_features`."""
+        warnings.warn(
+            "packet_trailer_features is deprecated, use frame_metadata_features instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.frame_metadata_features
+
 
 class LocalTrackPublication(TrackPublication):
     def __init__(self, owned_info: proto_track.OwnedTrackPublication):

tests/rtc/test_frame_metadata.py

@@ -78,6 +78,24 @@ async def test_track_publication_exposes_frame_metadata_features() -> None:
     ]
 
 
+def test_packet_trailer_names_remain_as_deprecated_aliases() -> None:
+    # The old "Packet Trailer" names are kept as backwards-compatible aliases.
+    assert rtc.PacketTrailerFeature is rtc.FrameMetadataFeature
+
+
+@pytest.mark.asyncio
+async def test_packet_trailer_features_property_is_deprecated_alias() -> None:
+    publication = rtc.LocalTrackPublication(
+        _owned_publication(
+            "TR_OLD",
+            frame_metadata_features=[proto_track.FMF_USER_TIMESTAMP],
+        )
+    )
+
+    with pytest.deprecated_call():
+        assert publication.packet_trailer_features == publication.frame_metadata_features
+
+
 def test_video_source_capture_frame_copies_metadata(monkeypatch: pytest.MonkeyPatch) -> None:
     captured_requests: list[proto_ffi.FfiRequest] = []