livekit 1.1.20__tar.gz → 1.2.0__tar.gz

livekit-1.2.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: livekit
+Version: 1.2.0
+Summary: Python Real-time SDK for LiveKit
+Author-email: LiveKit <support@livekit.io>
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://docs.livekit.io
+Project-URL: Website, https://livekit.io/
+Project-URL: Source, https://github.com/livekit/python-sdks/
+Keywords: webrtc,realtime,audio,video,livekit
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9.0
+Description-Content-Type: text/markdown
+Requires-Dist: protobuf>=5
+Requires-Dist: types-protobuf>=5
+Requires-Dist: aiofiles>=24
+Requires-Dist: numpy>=1.26
+
+# LiveKit SDK for Python
+
+Python SDK to integrate LiveKit's real-time video, audio, and data capabilities into your Python applications using WebRTC. Designed for use with [LiveKit Agents](https://github.com/livekit/agents) to build powerful voice AI apps.
+
+See https://docs.livekit.io/ for more information.
+
+## Publishing pre-encoded video
+
+Use `EncodedVideoSource` when an upstream encoder already provides compressed
+frames. The source uses the same native passthrough encoder as the Rust SDK;
+Python does not decode or re-encode the video.
+
+```python
+from livekit import rtc
+
+source = rtc.EncodedVideoSource(width=640, height=360)
+track = rtc.LocalVideoTrack.create_video_track("camera", source)
+await room.local_participant.publish_track(
+    track,
+    rtc.TrackPublishOptions(
+        video_codec=rtc.VideoCodec.VP9,
+        video_encoder=rtc.VideoEncoderBackend.ENCODER_BACKEND_PRE_ENCODED,
+        simulcast=False,
+    ),
+)
+# Supply each complete encoded frame at its playback time.
+source.capture_frame(rtc.EncodedVideoFrame(
+    data=encoded_vp9_frame,
+    width=640,
+    height=360,
+    codec=rtc.VideoCodec.VP9,
+    frame_type=rtc.EncodedFrameType.ENCODED_FRAME_KEY,
+    timestamp_us=capture_timestamp_us,
+))
+feedback = source.take_feedback()
+# Forward feedback.keyframe_requested and feedback.rate_control to your encoder.
+# At shutdown, unpublish the track and release the source:
+await room.local_participant.unpublish_track(track.sid)
+await source.aclose()
+```
+
+Supported codecs are H.264, H.265, VP8, VP9 and AV1, subject to receiver support.
+Submit complete access units (Annex B for H.264/H.265), not WebM/MP4 container
+bytes or RTP packets. A container must first be demuxed; demuxing extracts
+compressed frames and does not reconstruct pixels. The codec must match the
+publication and stay fixed, and simulcast must be disabled.
+
+The caller controls pacing and handles keyframe and bitrate feedback. In
+particular, a prerecorded file cannot generate a new keyframe on demand for a
+late subscriber or after packet loss. WebM's auxiliary alpha data is not part of
+the VP9 color access unit and is not transported by this API.

livekit-1.2.0/README.md

@@ -0,0 +1,51 @@
+# LiveKit SDK for Python
+
+Python SDK to integrate LiveKit's real-time video, audio, and data capabilities into your Python applications using WebRTC. Designed for use with [LiveKit Agents](https://github.com/livekit/agents) to build powerful voice AI apps.
+
+See https://docs.livekit.io/ for more information.
+
+## Publishing pre-encoded video
+
+Use `EncodedVideoSource` when an upstream encoder already provides compressed
+frames. The source uses the same native passthrough encoder as the Rust SDK;
+Python does not decode or re-encode the video.
+
+```python
+from livekit import rtc
+
+source = rtc.EncodedVideoSource(width=640, height=360)
+track = rtc.LocalVideoTrack.create_video_track("camera", source)
+await room.local_participant.publish_track(
+    track,
+    rtc.TrackPublishOptions(
+        video_codec=rtc.VideoCodec.VP9,
+        video_encoder=rtc.VideoEncoderBackend.ENCODER_BACKEND_PRE_ENCODED,
+        simulcast=False,
+    ),
+)
+# Supply each complete encoded frame at its playback time.
+source.capture_frame(rtc.EncodedVideoFrame(
+    data=encoded_vp9_frame,
+    width=640,
+    height=360,
+    codec=rtc.VideoCodec.VP9,
+    frame_type=rtc.EncodedFrameType.ENCODED_FRAME_KEY,
+    timestamp_us=capture_timestamp_us,
+))
+feedback = source.take_feedback()
+# Forward feedback.keyframe_requested and feedback.rate_control to your encoder.
+# At shutdown, unpublish the track and release the source:
+await room.local_participant.unpublish_track(track.sid)
+await source.aclose()
+```
+
+Supported codecs are H.264, H.265, VP8, VP9 and AV1, subject to receiver support.
+Submit complete access units (Annex B for H.264/H.265), not WebM/MP4 container
+bytes or RTP packets. A container must first be demuxed; demuxing extracts
+compressed frames and does not reconstruct pixels. The codec must match the
+publication and stay fixed, and simulcast must be disabled.
+
+The caller controls pacing and handles keyframe and bitrate feedback. In
+particular, a prerecorded file cannot generate a new keyframe on demand for a
+late subscriber or after packet loss. WebM's auxiliary alpha data is not part of
+the VP9 color access unit and is not transported by this API.

{livekit-1.1.20 → livekit-1.2.0}/livekit/rtc/__init__.py

@@ -35,6 +35,7 @@ from ._proto.room_pb2 import (
     SimulateScenarioKind,
     TrackPublishOptions,
     VideoEncoding,
+    VideoEncoderBackend,
 )
 from ._proto.track_pb2 import (
     FrameMetadataFeature,
@@ -43,7 +44,13 @@ from ._proto.track_pb2 import (
     TrackSource,
     ParticipantTrackPermission,
 )
-from ._proto.video_frame_pb2 import FrameMetadata, VideoBufferType, VideoCodec, VideoRotation
+from ._proto.video_frame_pb2 import (
+    EncodedFrameType,
+    FrameMetadata,
+    VideoBufferType,
+    VideoCodec,
+    VideoRotation,
+)
 from ._proto.track_publication_pb2 import VideoQuality
 from .audio_frame import AudioFrame
 from .audio_source import AudioSource
@@ -95,6 +102,12 @@ from .version import __version__
 from .video_frame import (
     VideoFrame,
 )
+from .encoded_video import (
+    EncodedVideoFrame,
+    EncodedVideoSource,
+    EncodedVideoSourceFeedback,
+    EncodedRateControl,
+)
 from .video_source import VideoSource
 from .video_stream import VideoFrameEvent, VideoStream
 from .audio_resampler import AudioResampler, AudioResamplerQuality
@@ -138,6 +151,12 @@ from .data_track import (
 from .frame_processor import FrameProcessor
 
 __all__ = [
+    "EncodedFrameType",
+    "EncodedVideoFrame",
+    "EncodedVideoSource",
+    "EncodedVideoSourceFeedback",
+    "EncodedRateControl",
+    "VideoEncoderBackend",
     "ConnectionQuality",
     "ConnectionState",
     "DataPacketKind",

{livekit-1.1.20 → livekit-1.2.0}/livekit/rtc/_ffi_client.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import signal
 import asyncio
 import sys
@@ -24,6 +26,7 @@ import os
 import platform
 import atexit
 import threading
+import weakref
 from typing import Callable, Generic, List, Optional, TypeVar
 
 from ._proto import ffi_pb2 as proto_ffi
@@ -68,10 +71,14 @@ ffi_cb_fnc = ctypes.CFUNCTYPE(None, ctypes.POINTER(ctypes.c_uint8), ctypes.c_siz
 INVALID_HANDLE = 0
 
 
+_live_handles: weakref.WeakSet[FfiHandle] = weakref.WeakSet()
+
+
 class FfiHandle:
     def __init__(self, handle: int) -> None:
         self.handle = handle
         self._disposed = False
+        _live_handles.add(self)
 
     def __del__(self) -> None:
         self.dispose()
@@ -93,7 +100,7 @@ class FfiHandle:
         if self.handle != INVALID_HANDLE and not self._disposed:
             self._disposed = True
             ffi = FfiClient._instance
-            if ffi is None or ffi._pid != os.getpid():
+            if ffi is None or ffi._pid != os.getpid() or getattr(FfiClient, "_ffi_disposed", False):
                 return
             dropped = ffi._ffi_lib.livekit_ffi_drop_handle(ctypes.c_uint64(self.handle))
             assert dropped
@@ -223,6 +230,7 @@ def to_python_level(level: proto_ffi.LogLevel.ValueType) -> Optional[int]:
 
 class FfiClient:
     _instance: Optional["FfiClient"] = None
+    _ffi_disposed: bool = False
 
     @classproperty
     def instance(cls) -> "FfiClient":
@@ -231,6 +239,7 @@ class FfiClient:
         return cls._instance
 
     def __init__(self) -> None:
+        FfiClient._ffi_disposed = False
         self._pid = os.getpid()
         self._lock = threading.RLock()
         self._queue = FfiQueue[proto_ffi.FfiEvent]()
@@ -266,14 +275,17 @@ class FfiClient:
             ffi_event_callback, True, b"python", __version__.encode("ascii")
         )
 
-        ffi_lib = self._ffi_lib
-        init_pid = self._pid
-
         @atexit.register
         def _dispose_lk_ffi() -> None:
-            if os.getpid() != init_pid:
-                return
-            ffi_lib.livekit_ffi_dispose()
+            self._dispose()
+
+    def _dispose(self) -> None:
+        if self._pid != os.getpid() or FfiClient._ffi_disposed:
+            return
+        FfiClient._ffi_disposed = True
+        for handle in list(_live_handles):
+            handle.mark_consumed()
+        self._ffi_lib.livekit_ffi_dispose()
 
     @property
     def queue(self) -> FfiQueue[proto_ffi.FfiEvent]:
@@ -288,7 +300,7 @@ class FfiClient:
             )
         proto_data = req.SerializeToString()
         proto_len = len(proto_data)
-        data = (ctypes.c_ubyte * proto_len)(*proto_data)
+        data = ctypes.cast(ctypes.c_char_p(proto_data), ctypes.POINTER(ctypes.c_ubyte))
 
         resp_ptr = ctypes.POINTER(ctypes.c_ubyte)()
         resp_len = ctypes.c_size_t()

livekit-1.2.0/livekit/rtc/_proto/capture_pb2.py

@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: capture.proto
+# Protobuf Python Version: 4.25.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import handle_pb2 as handle__pb2
+from . import room_pb2 as room__pb2
+from . import video_frame_pb2 as video__frame__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rcapture.proto\x12\rlivekit.proto\x1a\x0chandle.proto\x1a\nroom.proto\x1a\x11video_frame.proto\"l\n\x14GstreamerRateControl\x12\x0f\n\x07\x65lement\x18\x01 \x02(\t\x12\x10\n\x08property\x18\x02 \x02(\t\x12\x31\n\x04unit\x18\x03 \x02(\x0e\x32#.livekit.proto.GstreamerBitrateUnit\"\xcd\x01\n\x1aGstreamerVideoSourceConfig\x12\x10\n\x08pipeline\x18\x01 \x02(\t\x12(\n\x05\x63odec\x18\x02 \x01(\x0e\x32\x19.livekit.proto.VideoCodec\x12\x38\n\nresolution\x18\x03 \x01(\x0b\x32$.livekit.proto.VideoSourceResolution\x12\x39\n\x0crate_control\x18\x04 \x01(\x0b\x32#.livekit.proto.GstreamerRateControl\"\x94\x01\n\x18PatternVideoSourceConfig\x12\x38\n\nresolution\x18\x01 \x02(\x0b\x32$.livekit.proto.VideoSourceResolution\x12\x15\n\rframerate_fps\x18\x02 \x02(\r\x12\'\n\x07pattern\x18\x03 \x02(\x0e\x32\x16.livekit.proto.Pattern\"i\n\x16\x43lockVideoSourceConfig\x12\x38\n\nresolution\x18\x01 \x02(\x0b\x32$.livekit.proto.VideoSourceResolution\x12\x15\n\rframerate_fps\x18\x02 \x02(\r\"\xa7\x02\n\x11\x43\x61ptureSourceInfo\x12.\n\x04kind\x18\x01 \x02(\x0e\x32 .livekit.proto.CaptureSourceKind\x12\x38\n\nresolution\x18\x02 \x02(\x0b\x32$.livekit.proto.VideoSourceResolution\x12(\n\x05\x63odec\x18\x03 \x01(\x0e\x32\x19.livekit.proto.VideoCodec\x12G\n\x1brecommended_publish_options\x18\x04 \x02(\x0b\x32\".livekit.proto.TrackPublishOptions\x12\x35\n\x0cvideo_source\x18\x05 \x02(\x0b\x32\x1f.livekit.proto.OwnedVideoSource\"s\n\x12OwnedCaptureSource\x12-\n\x06handle\x18\x01 \x02(\x0b\x32\x1d.livekit.proto.FfiOwnedHandle\x12.\n\x04info\x18\x02 \x02(\x0b\x32 .livekit.proto.CaptureSourceInfo\"\xf1\x01\n\x17NewCaptureSourceRequest\x12>\n\tgstreamer\x18\x01 \x01(\x0b\x32).livekit.proto.GstreamerVideoSourceConfigH\x00\x12:\n\x07pattern\x18\x02 \x01(\x0b\x32\'.livekit.proto.PatternVideoSourceConfigH\x00\x12\x36\n\x05\x63lock\x18\x05 \x01(\x0b\x32%.livekit.proto.ClockVideoSourceConfigH\x00\x12\x18\n\x10request_async_id\x18\x03 \x01(\x04\x42\x08\n\x06\x63onfig\",\n\x18NewCaptureSourceResponse\x12\x10\n\x08\x61sync_id\x18\x01 \x02(\x04\"}\n\x18NewCaptureSourceCallback\x12\x10\n\x08\x61sync_id\x18\x01 \x02(\x04\x12\x0f\n\x05\x65rror\x18\x02 \x01(\tH\x00\x12\x33\n\x06source\x18\x03 \x01(\x0b\x32!.livekit.proto.OwnedCaptureSourceH\x00\x42\t\n\x07message\"-\n\x13StartCaptureRequest\x12\x16\n\x0e\x63\x61pture_handle\x18\x01 \x02(\x04\"%\n\x14StartCaptureResponse\x12\r\n\x05\x65rror\x18\x01 \x01(\t\",\n\x12StopCaptureRequest\x12\x16\n\x0e\x63\x61pture_handle\x18\x01 \x02(\x04\"$\n\x13StopCaptureResponse\x12\r\n\x05\x65rror\x18\x01 \x01(\t\"T\n\x0f\x43\x61ptureFinished\x12\x17\n\x0f\x66rames_captured\x18\x01 \x02(\x04\x12(\n\x04\x65xit\x18\x02 \x02(\x0e\x32\x1a.livekit.proto.CaptureExit\"L\n\x0c\x43\x61ptureError\x12\r\n\x05\x65rror\x18\x01 \x02(\t\x12-\n\x04kind\x18\x02 \x02(\x0e\x32\x1f.livekit.proto.CaptureErrorKind\"\x99\x01\n\x12\x43\x61ptureSourceEvent\x12\x16\n\x0e\x63\x61pture_handle\x18\x01 \x02(\x04\x12\x32\n\x08\x66inished\x18\x02 \x01(\x0b\x32\x1e.livekit.proto.CaptureFinishedH\x00\x12,\n\x05\x65rror\x18\x03 \x01(\x0b\x32\x1b.livekit.proto.CaptureErrorH\x00\x42\t\n\x07message*W\n\x14GstreamerBitrateUnit\x12\x1e\n\x1aGSTREAMER_BITRATE_UNIT_BPS\x10\x00\x12\x1f\n\x1bGSTREAMER_BITRATE_UNIT_KBPS\x10\x01*1\n\x07Pattern\x12\x14\n\x10PATTERN_GRADIENT\x10\x00\x12\x10\n\x0cPATTERN_LOGO\x10\x01*I\n\x11\x43\x61ptureSourceKind\x12\x18\n\x14\x43\x41PTURE_SOURCE_PIXEL\x10\x00\x12\x1a\n\x16\x43\x41PTURE_SOURCE_ENCODED\x10\x01*G\n\x0b\x43\x61ptureExit\x12\x18\n\x14\x43\x41PTURE_EXIT_STOPPED\x10\x00\x12\x1e\n\x1a\x43\x41PTURE_EXIT_END_OF_STREAM\x10\x01*n\n\x10\x43\x61ptureErrorKind\x12\x1d\n\x19\x43\x41PTURE_ERROR_KIND_SOURCE\x10\x00\x12\x1a\n\x16\x43\x41PTURE_ERROR_KIND_RTC\x10\x01\x12\x1f\n\x1b\x43\x41PTURE_ERROR_KIND_PANICKED\x10\x02\x42\x10\xaa\x02\rLiveKit.Proto')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'capture_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  _globals['DESCRIPTOR']._options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\252\002\rLiveKit.Proto'
+  _globals['_GSTREAMERBITRATEUNIT']._serialized_start=1975
+  _globals['_GSTREAMERBITRATEUNIT']._serialized_end=2062
+  _globals['_PATTERN']._serialized_start=2064
+  _globals['_PATTERN']._serialized_end=2113
+  _globals['_CAPTURESOURCEKIND']._serialized_start=2115
+  _globals['_CAPTURESOURCEKIND']._serialized_end=2188
+  _globals['_CAPTUREEXIT']._serialized_start=2190
+  _globals['_CAPTUREEXIT']._serialized_end=2261
+  _globals['_CAPTUREERRORKIND']._serialized_start=2263
+  _globals['_CAPTUREERRORKIND']._serialized_end=2373
+  _globals['_GSTREAMERRATECONTROL']._serialized_start=77
+  _globals['_GSTREAMERRATECONTROL']._serialized_end=185
+  _globals['_GSTREAMERVIDEOSOURCECONFIG']._serialized_start=188
+  _globals['_GSTREAMERVIDEOSOURCECONFIG']._serialized_end=393
+  _globals['_PATTERNVIDEOSOURCECONFIG']._serialized_start=396
+  _globals['_PATTERNVIDEOSOURCECONFIG']._serialized_end=544
+  _globals['_CLOCKVIDEOSOURCECONFIG']._serialized_start=546
+  _globals['_CLOCKVIDEOSOURCECONFIG']._serialized_end=651
+  _globals['_CAPTURESOURCEINFO']._serialized_start=654
+  _globals['_CAPTURESOURCEINFO']._serialized_end=949
+  _globals['_OWNEDCAPTURESOURCE']._serialized_start=951
+  _globals['_OWNEDCAPTURESOURCE']._serialized_end=1066
+  _globals['_NEWCAPTURESOURCEREQUEST']._serialized_start=1069
+  _globals['_NEWCAPTURESOURCEREQUEST']._serialized_end=1310
+  _globals['_NEWCAPTURESOURCERESPONSE']._serialized_start=1312
+  _globals['_NEWCAPTURESOURCERESPONSE']._serialized_end=1356
+  _globals['_NEWCAPTURESOURCECALLBACK']._serialized_start=1358
+  _globals['_NEWCAPTURESOURCECALLBACK']._serialized_end=1483
+  _globals['_STARTCAPTUREREQUEST']._serialized_start=1485
+  _globals['_STARTCAPTUREREQUEST']._serialized_end=1530
+  _globals['_STARTCAPTURERESPONSE']._serialized_start=1532
+  _globals['_STARTCAPTURERESPONSE']._serialized_end=1569
+  _globals['_STOPCAPTUREREQUEST']._serialized_start=1571
+  _globals['_STOPCAPTUREREQUEST']._serialized_end=1615
+  _globals['_STOPCAPTURERESPONSE']._serialized_start=1617
+  _globals['_STOPCAPTURERESPONSE']._serialized_end=1653
+  _globals['_CAPTUREFINISHED']._serialized_start=1655
+  _globals['_CAPTUREFINISHED']._serialized_end=1739
+  _globals['_CAPTUREERROR']._serialized_start=1741
+  _globals['_CAPTUREERROR']._serialized_end=1817
+  _globals['_CAPTURESOURCEEVENT']._serialized_start=1820
+  _globals['_CAPTURESOURCEEVENT']._serialized_end=1973
+# @@protoc_insertion_point(module_scope)

{livekit-1.1.20 → livekit-1.2.0}/livekit/rtc/_proto/capture_pb2.pyi

@@ -33,18 +33,16 @@ else:
 
 DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
 
-class _Pattern:
+class _GstreamerBitrateUnit:
     ValueType = typing.NewType("ValueType", builtins.int)
     V: typing_extensions.TypeAlias = ValueType
 
-class _PatternEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_Pattern.ValueType], builtins.type):
+class _GstreamerBitrateUnitEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_GstreamerBitrateUnit.ValueType], builtins.type):
     DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
-    PATTERN_GRADIENT: _Pattern.ValueType  # 0
-    """Animated color gradient."""
-    PATTERN_LOGO: _Pattern.ValueType  # 1
-    """Bouncing LiveKit logo."""
+    GSTREAMER_BITRATE_UNIT_BPS: _GstreamerBitrateUnit.ValueType  # 0
+    GSTREAMER_BITRATE_UNIT_KBPS: _GstreamerBitrateUnit.ValueType  # 1
 
-class Pattern(_Pattern, metaclass=_PatternEnumTypeWrapper):
+class GstreamerBitrateUnit(_GstreamerBitrateUnit, metaclass=_GstreamerBitrateUnitEnumTypeWrapper):
     """Capture sources (livekit-capture)
 
     A capture source owns a media producer (e.g. a GStreamer pipeline) and the
@@ -61,9 +59,27 @@ class Pattern(_Pattern, metaclass=_PatternEnumTypeWrapper):
     3. The capture runs until StopCaptureRequest, end of stream, or an error;
        a CaptureSourceEvent is delivered exactly once when it ends.
 
-    Test patterns built into livekit-capture.
+    Bitrate unit expected by a GStreamer encoder property.
     """
 
+GSTREAMER_BITRATE_UNIT_BPS: GstreamerBitrateUnit.ValueType  # 0
+GSTREAMER_BITRATE_UNIT_KBPS: GstreamerBitrateUnit.ValueType  # 1
+global___GstreamerBitrateUnit = GstreamerBitrateUnit
+
+class _Pattern:
+    ValueType = typing.NewType("ValueType", builtins.int)
+    V: typing_extensions.TypeAlias = ValueType
+
+class _PatternEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_Pattern.ValueType], builtins.type):
+    DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
+    PATTERN_GRADIENT: _Pattern.ValueType  # 0
+    """Animated color gradient."""
+    PATTERN_LOGO: _Pattern.ValueType  # 1
+    """Bouncing LiveKit logo."""
+
+class Pattern(_Pattern, metaclass=_PatternEnumTypeWrapper):
+    """Test patterns built into livekit-capture."""
+
 PATTERN_GRADIENT: Pattern.ValueType  # 0
 """Animated color gradient."""
 PATTERN_LOGO: Pattern.ValueType  # 1
@@ -110,6 +126,104 @@ CAPTURE_EXIT_END_OF_STREAM: CaptureExit.ValueType  # 1
 """The producer reached the end of its stream."""
 global___CaptureExit = CaptureExit
 
+class _CaptureErrorKind:
+    ValueType = typing.NewType("ValueType", builtins.int)
+    V: typing_extensions.TypeAlias = ValueType
+
+class _CaptureErrorKindEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_CaptureErrorKind.ValueType], builtins.type):
+    DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
+    CAPTURE_ERROR_KIND_SOURCE: _CaptureErrorKind.ValueType  # 0
+    """The capture source failed or violated its contract."""
+    CAPTURE_ERROR_KIND_RTC: _CaptureErrorKind.ValueType  # 1
+    """The RTC video source rejected a frame."""
+    CAPTURE_ERROR_KIND_PANICKED: _CaptureErrorKind.ValueType  # 2
+    """The pump thread panicked."""
+
+class CaptureErrorKind(_CaptureErrorKind, metaclass=_CaptureErrorKindEnumTypeWrapper):
+    """Why a capture ended with an error."""
+
+CAPTURE_ERROR_KIND_SOURCE: CaptureErrorKind.ValueType  # 0
+"""The capture source failed or violated its contract."""
+CAPTURE_ERROR_KIND_RTC: CaptureErrorKind.ValueType  # 1
+"""The RTC video source rejected a frame."""
+CAPTURE_ERROR_KIND_PANICKED: CaptureErrorKind.ValueType  # 2
+"""The pump thread panicked."""
+global___CaptureErrorKind = CaptureErrorKind
+
+@typing.final
+class GstreamerRateControl(google.protobuf.message.Message):
+    """Binding from WebRTC rate-control targets to a GStreamer encoder property."""
+
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    ELEMENT_FIELD_NUMBER: builtins.int
+    PROPERTY_FIELD_NUMBER: builtins.int
+    UNIT_FIELD_NUMBER: builtins.int
+    element: builtins.str
+    """Name of the encoder element in the pipeline (e.g. `lk_encoder`)."""
+    property: builtins.str
+    """Bitrate property to set on the element (e.g. `bitrate` for x264enc,
+    `target-bitrate` for vp8enc/vp9enc).
+    """
+    unit: global___GstreamerBitrateUnit.ValueType
+    """Unit the property expects."""
+    def __init__(
+        self,
+        *,
+        element: builtins.str | None = ...,
+        property: builtins.str | None = ...,
+        unit: global___GstreamerBitrateUnit.ValueType | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["element", b"element", "property", b"property", "unit", b"unit"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["element", b"element", "property", b"property", "unit", b"unit"]) -> None: ...
+
+global___GstreamerRateControl = GstreamerRateControl
+
+@typing.final
+class GstreamerVideoSourceConfig(google.protobuf.message.Message):
+    """Encoded ingest from a GStreamer pipeline."""
+
+    DESCRIPTOR: google.protobuf.descriptor.Descriptor
+
+    PIPELINE_FIELD_NUMBER: builtins.int
+    CODEC_FIELD_NUMBER: builtins.int
+    RESOLUTION_FIELD_NUMBER: builtins.int
+    RATE_CONTROL_FIELD_NUMBER: builtins.int
+    pipeline: builtins.str
+    """GStreamer launch description for the encoded producer pipeline.
+    Must contain `appsink name=lk_appsink`, or leave exactly one encoded
+    video source pad unlinked for the source to attach one to.
+    """
+    codec: video_frame_pb2.VideoCodec.ValueType
+    """Codec expected from the pipeline; inferred from pipeline caps when
+    omitted.
+    """
+    @property
+    def resolution(self) -> video_frame_pb2.VideoSourceResolution:
+        """Encoded frame resolution. When omitted, it is discovered from the
+        pipeline's negotiated caps; when set, the pipeline output is verified
+        against it.
+        """
+
+    @property
+    def rate_control(self) -> global___GstreamerRateControl:
+        """Forwards WebRTC rate-control targets to an encoder element's bitrate
+        property. Without this, the pipeline encodes at a fixed bitrate.
+        """
+
+    def __init__(
+        self,
+        *,
+        pipeline: builtins.str | None = ...,
+        codec: video_frame_pb2.VideoCodec.ValueType | None = ...,
+        resolution: video_frame_pb2.VideoSourceResolution | None = ...,
+        rate_control: global___GstreamerRateControl | None = ...,
+    ) -> None: ...
+    def HasField(self, field_name: typing.Literal["codec", b"codec", "pipeline", b"pipeline", "rate_control", b"rate_control", "resolution", b"resolution"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["codec", b"codec", "pipeline", b"pipeline", "rate_control", b"rate_control", "resolution", b"resolution"]) -> None: ...
+
+global___GstreamerVideoSourceConfig = GstreamerVideoSourceConfig
+
 @typing.final
 class PatternVideoSourceConfig(google.protobuf.message.Message):
     """Test pattern rendered on the GPU."""
@@ -241,24 +355,28 @@ class NewCaptureSourceRequest(google.protobuf.message.Message):
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
+    GSTREAMER_FIELD_NUMBER: builtins.int
     PATTERN_FIELD_NUMBER: builtins.int
     CLOCK_FIELD_NUMBER: builtins.int
     REQUEST_ASYNC_ID_FIELD_NUMBER: builtins.int
     request_async_id: builtins.int
     @property
+    def gstreamer(self) -> global___GstreamerVideoSourceConfig: ...
+    @property
     def pattern(self) -> global___PatternVideoSourceConfig: ...
     @property
     def clock(self) -> global___ClockVideoSourceConfig: ...
     def __init__(
         self,
         *,
+        gstreamer: global___GstreamerVideoSourceConfig | None = ...,
         pattern: global___PatternVideoSourceConfig | None = ...,
         clock: global___ClockVideoSourceConfig | None = ...,
         request_async_id: builtins.int | None = ...,
     ) -> None: ...
-    def HasField(self, field_name: typing.Literal["clock", b"clock", "config", b"config", "pattern", b"pattern", "request_async_id", b"request_async_id"]) -> builtins.bool: ...
-    def ClearField(self, field_name: typing.Literal["clock", b"clock", "config", b"config", "pattern", b"pattern", "request_async_id", b"request_async_id"]) -> None: ...
-    def WhichOneof(self, oneof_group: typing.Literal["config", b"config"]) -> typing.Literal["pattern", "clock"] | None: ...
+    def HasField(self, field_name: typing.Literal["clock", b"clock", "config", b"config", "gstreamer", b"gstreamer", "pattern", b"pattern", "request_async_id", b"request_async_id"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["clock", b"clock", "config", b"config", "gstreamer", b"gstreamer", "pattern", b"pattern", "request_async_id", b"request_async_id"]) -> None: ...
+    def WhichOneof(self, oneof_group: typing.Literal["config", b"config"]) -> typing.Literal["gstreamer", "pattern", "clock"] | None: ...
 
 global___NewCaptureSourceRequest = NewCaptureSourceRequest
 
@@ -397,14 +515,17 @@ class CaptureError(google.protobuf.message.Message):
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
     ERROR_FIELD_NUMBER: builtins.int
+    KIND_FIELD_NUMBER: builtins.int
     error: builtins.str
+    kind: global___CaptureErrorKind.ValueType
     def __init__(
         self,
         *,
         error: builtins.str | None = ...,
+        kind: global___CaptureErrorKind.ValueType | None = ...,
     ) -> None: ...
-    def HasField(self, field_name: typing.Literal["error", b"error"]) -> builtins.bool: ...
-    def ClearField(self, field_name: typing.Literal["error", b"error"]) -> None: ...
+    def HasField(self, field_name: typing.Literal["error", b"error", "kind", b"kind"]) -> builtins.bool: ...
+    def ClearField(self, field_name: typing.Literal["error", b"error", "kind", b"kind"]) -> None: ...
 
 global___CaptureError = CaptureError
 

{livekit-1.1.20 → livekit-1.2.0}/livekit/rtc/_utils.py

@@ -113,6 +113,19 @@ class Queue(asyncio.Queue[T]):
 
             self.task_done()
 
+    def release(self) -> None:
+        """Mark every unfinished item as done.
+
+        Lets a ``join()`` that is already waiting on this queue return once there
+        is no consumer left for it.
+        """
+        while True:
+            try:
+                self.task_done()
+            except ValueError:
+                # task_done() raises once every item is accounted for
+                return
+
 
 class BroadcastQueue(Generic[T]):
     """Queue with multiple subscribers."""
@@ -135,6 +148,10 @@ class BroadcastQueue(Generic[T]):
 
     def unsubscribe(self, queue: Queue[T]) -> None:
         self._subscribers.remove(queue)
+        # A join() may already hold this queue. Events that are still queued, or that
+        # the subscriber took but never finished, have no consumer anymore, so
+        # release them instead of leaving the joiner waiting forever.
+        queue.release()
 
     async def join(self) -> None:
         async with self._lock: