livekit 1.2.1__py3-none-win_arm64.whl

livekit/rtc/__init__.py

@@ -0,0 +1,264 @@
+# Copyright 2023 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LiveKit SDK for Python
+`pip install livekit`
+
+See https://docs.livekit.io/home/client/connect/#installing-the-livekit-sdk for more information.
+"""
+
+from ._proto import stats_pb2 as stats
+from ._proto.e2ee_pb2 import EncryptionState, EncryptionType, KeyDerivationFunction
+from ._proto.participant_pb2 import (
+    ParticipantKind,
+    ParticipantKindDetail,
+    ParticipantState,
+    DisconnectReason,
+)
+from ._proto.room_pb2 import (
+    ConnectionState,
+    ContinualGatheringPolicy,
+    DataPacketKind,
+    IceServer,
+    IceTransportType,
+    SimulateScenarioKind,
+    TrackPublishOptions,
+    VideoEncoding,
+    VideoEncoderBackend,
+)
+from ._proto.track_pb2 import (
+    FrameMetadataFeature,
+    StreamState,
+    TrackKind,
+    TrackSource,
+    ParticipantTrackPermission,
+)
+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
+from .audio_stream import AudioFrameEvent, AudioStream, NoiseCancellationOptions
+from .audio_filter import AudioFilter
+from .e2ee import (
+    E2EEManager,
+    E2EEOptions,
+    FrameCryptor,
+    KeyProvider,
+    KeyProviderOptions,
+)
+from .participant import (
+    ConnectionQuality,
+    DegradationPreference,
+    LocalParticipant,
+    Participant,
+    RemoteParticipant,
+)
+from .room import (
+    ConnectError,
+    DataPacket,
+    DataStreamOptions,
+    Room,
+    RoomOptions,
+    RtcConfiguration,
+    SipDTMF,
+    RtcStats,
+)
+from .track import (
+    AudioTrack,
+    LocalAudioTrack,
+    LocalTrack,
+    LocalVideoTrack,
+    RemoteAudioTrack,
+    RemoteTrack,
+    RemoteVideoTrack,
+    Track,
+    VideoTrack,
+)
+from .event_emitter import EventEmitter
+from .track_publication import (
+    LocalTrackPublication,
+    RemoteTrackPublication,
+    TrackPublication,
+)
+from .transcription import Transcription, TranscriptionSegment
+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
+from .audio_mixer import AudioMixer
+from .apm import AudioProcessingModule
+from .platform_audio import (
+    PlatformAudio,
+    PlatformAudioSource,
+    PlatformAudioOptions,
+    PlatformAudioError,
+    AudioDeviceInfo,
+)
+
+try:
+    from .media_devices import MediaDevices as MediaDevices
+
+    _HAS_MEDIA_DEVICES = True
+except Exception:  # pragma: no cover - optional dependency (sounddevice)
+    _HAS_MEDIA_DEVICES = False
+from .utils import combine_audio_frames
+from .rpc import RpcCallInfo, RpcError, RpcInterceptor, RpcInvocationData
+from .synchronizer import AVSynchronizer
+from .data_stream import (
+    TextStreamInfo,
+    ByteStreamInfo,
+    TextStreamReader,
+    TextStreamWriter,
+    ByteStreamWriter,
+    ByteStreamReader,
+    StreamError,
+)
+from .data_track import (
+    LocalDataTrack,
+    RemoteDataTrack,
+    DataTrackStream,
+    DataTrackFrame,
+    DataTrackInfo,
+    PushFrameError,
+    SubscribeDataTrackError,
+)
+from .frame_processor import FrameProcessor
+
+__all__ = [
+    "EncodedFrameType",
+    "EncodedVideoFrame",
+    "EncodedVideoSource",
+    "EncodedVideoSourceFeedback",
+    "EncodedRateControl",
+    "VideoEncoderBackend",
+    "ConnectionQuality",
+    "ConnectionState",
+    "DataPacketKind",
+    "DegradationPreference",
+    "TrackPublishOptions",
+    "IceTransportType",
+    "ContinualGatheringPolicy",
+    "IceServer",
+    "EncryptionType",
+    "EncryptionState",
+    "KeyDerivationFunction",
+    "StreamState",
+    "TrackKind",
+    "TrackSource",
+    "FrameMetadataFeature",
+    "ParticipantTrackPermission",
+    "VideoBufferType",
+    "VideoRotation",
+    "FrameMetadata",
+    "stats",
+    "AudioFrame",
+    "AudioSource",
+    "AudioStream",
+    "NoiseCancellationOptions",
+    "AudioFilter",
+    "AudioFrameEvent",
+    "LocalParticipant",
+    "Participant",
+    "ParticipantKind",
+    "ParticipantKindDetail",
+    "ParticipantState",
+    "DisconnectReason",
+    "RemoteParticipant",
+    "ConnectError",
+    "Room",
+    "RoomOptions",
+    "DataStreamOptions",
+    "RtcConfiguration",
+    "SimulateScenarioKind",
+    "SipDTMF",
+    "RtcStats",
+    "DataPacket",
+    "LocalAudioTrack",
+    "LocalVideoTrack",
+    "RemoteAudioTrack",
+    "RemoteVideoTrack",
+    "Track",
+    "LocalTrack",
+    "RemoteTrack",
+    "AudioTrack",
+    "VideoTrack",
+    "E2EEManager",
+    "E2EEOptions",
+    "KeyProviderOptions",
+    "KeyProvider",
+    "FrameCryptor",
+    "LocalTrackPublication",
+    "RemoteTrackPublication",
+    "TrackPublication",
+    "Transcription",
+    "TranscriptionSegment",
+    "VideoCodec",
+    "VideoEncoding",
+    "VideoQuality",
+    "VideoFrame",
+    "VideoFrameEvent",
+    "VideoSource",
+    "VideoStream",
+    "AudioMixer",
+    "AudioResampler",
+    "AudioResamplerQuality",
+    "RpcError",
+    "RpcInvocationData",
+    "RpcCallInfo",
+    "RpcInterceptor",
+    "EventEmitter",
+    "combine_audio_frames",
+    "AVSynchronizer",
+    "TextStreamInfo",
+    "ByteStreamInfo",
+    "TextStreamReader",
+    "TextStreamWriter",
+    "ByteStreamReader",
+    "ByteStreamWriter",
+    "StreamError",
+    "AudioProcessingModule",
+    "PlatformAudio",
+    "PlatformAudioSource",
+    "PlatformAudioOptions",
+    "PlatformAudioError",
+    "AudioDeviceInfo",
+    "FrameProcessor",
+    "LocalDataTrack",
+    "RemoteDataTrack",
+    "DataTrackStream",
+    "DataTrackFrame",
+    "DataTrackInfo",
+    "PushFrameError",
+    "SubscribeDataTrackError",
+    "__version__",
+]
+
+# add MediaDevices if available
+if _HAS_MEDIA_DEVICES:
+    __all__.append("MediaDevices")

livekit/rtc/_ffi_client.py

@@ -0,0 +1,321 @@
+# Copyright 2023 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import signal
+import asyncio
+import sys
+from contextlib import ExitStack
+import ctypes
+import importlib.resources
+from .version import __version__
+import logging
+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
+from ._utils import Queue, classproperty
+from .log import logger
+
+_resource_files = ExitStack()
+atexit.register(_resource_files.close)
+
+
+def _lib_name() -> Optional[str]:
+    if platform.system() == "Linux":
+        return "liblivekit_ffi.so"
+    elif platform.system() == "Darwin":
+        return "liblivekit_ffi.dylib"
+    elif platform.system() == "Windows":
+        return "livekit_ffi.dll"
+    return None
+
+
+def get_ffi_lib() -> ctypes.CDLL:
+    # allow to override the lib path using an env var
+    libpath = os.environ.get("LIVEKIT_LIB_PATH", "").strip()
+    if libpath:
+        return ctypes.CDLL(libpath)
+
+    libname = _lib_name()
+    if libname is None:
+        raise Exception(
+            f"no ffi library found for platform {platform.system()}. "
+            "Set LIVEKIT_LIB_PATH to specify the lib path"
+        )
+
+    res = importlib.resources.files("livekit.rtc.resources") / libname
+    ctx = importlib.resources.as_file(res)
+    path = _resource_files.enter_context(ctx)
+    return ctypes.CDLL(str(path))
+
+
+ffi_cb_fnc = ctypes.CFUNCTYPE(None, ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t)
+
+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()
+
+    @property
+    def disposed(self) -> bool:
+        return self._disposed
+
+    def mark_consumed(self) -> None:
+        """Marks the handle as already released on the native side.
+
+        Some requests take ownership of their handle (``take_handle``) rather
+        than borrowing it. After issuing one, the handle must not be dropped
+        again, so this suppresses the drop that dispose/GC would otherwise do.
+        """
+        self._disposed = True
+
+    def dispose(self) -> None:
+        if self.handle != INVALID_HANDLE and not self._disposed:
+            self._disposed = True
+            ffi = FfiClient._instance
+            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
+
+    def __repr__(self) -> str:
+        return f"FfiHandle({self.handle})"
+
+
+T = TypeVar("T")
+
+
+class FfiQueue(Generic[T]):
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        # Format: (queue, loop, filter_fn or None)
+        self._subscribers: List[
+            tuple[Queue[T], asyncio.AbstractEventLoop, Optional[Callable[[T], bool]]]
+        ] = []
+
+    def put(self, item: T) -> None:
+        with self._lock:
+            for queue, loop, filter_fn in self._subscribers:
+                # If filter provided, skip items that don't match
+                if filter_fn is not None:
+                    try:
+                        if not filter_fn(item):
+                            continue
+                    except Exception:
+                        pass  # On filter error, deliver the item
+
+                try:
+                    loop.call_soon_threadsafe(queue.put_nowait, item)
+                except Exception as e:
+                    # this could happen if user closes the runloop without unsubscribing first
+                    # it's not good when it does occur, but we should not fail the entire runloop
+                    logger.error("error putting to queue: %s", e)
+
+    def subscribe(
+        self,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        filter_fn: Optional[Callable[[T], bool]] = None,
+    ) -> Queue[T]:
+        """Subscribe to FFI events.
+
+        Args:
+            loop: Event loop to use (defaults to current).
+            filter_fn: Optional filter function. If provided, only items where
+                      filter_fn(item) returns True will be delivered.
+                      If None, receives all events (original behavior).
+
+        Returns:
+            Queue to receive events from.
+        """
+        with self._lock:
+            queue = Queue[T]()
+            loop = loop or asyncio.get_event_loop()
+            self._subscribers.append((queue, loop, filter_fn))
+            return queue
+
+    def unsubscribe(self, queue: Queue[T]) -> None:
+        with self._lock:
+            # looping here is ok, since we don't expect a lot of subscribers
+            for i, (q, _, _) in enumerate(self._subscribers):
+                if q == queue:
+                    self._subscribers.pop(i)
+                    break
+
+
+@ctypes.CFUNCTYPE(None, ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t)  # type: ignore[untyped-decorator]
+def ffi_event_callback(
+    data_ptr: ctypes.POINTER(ctypes.c_uint8),  # type: ignore
+    data_len: ctypes.c_size_t,
+) -> None:
+    event_data = ctypes.string_at(data_ptr, int(data_len))
+    event = proto_ffi.FfiEvent()
+    event.ParseFromString(event_data)
+
+    which = event.WhichOneof("message")
+    if which == "logs":
+        for record in event.logs.records:
+            level = to_python_level(record.level)
+            debug_env = os.environ.get("LIVEKIT_RTC_DEBUG", "").strip().lower()
+            rtc_debug = debug_env in ("true", "1")
+
+            if level == logging.DEBUG and not rtc_debug:
+                # ignore the rtc debug logs by default
+                if record.target == "libwebrtc" or record.target.startswith("livekit"):
+                    continue
+
+            if level is not None:
+                logger.log(
+                    level,
+                    "%s:%s:%s - %s",
+                    record.target,
+                    record.line,
+                    record.module_path,
+                    record.message,
+                )
+
+        return  # no need to queue the logs
+    elif which == "panic":
+        print("FFI Panic: ", event.panic.message, file=sys.stderr, flush=True)
+        # We are in a unrecoverable state, terminate the process
+        os.kill(os.getpid(), signal.SIGTERM)
+        return
+
+    FfiClient.instance.queue.put(event)
+
+
+def to_python_level(level: proto_ffi.LogLevel.ValueType) -> Optional[int]:
+    if level == proto_ffi.LogLevel.LOG_ERROR:
+        return logging.ERROR
+    elif level == proto_ffi.LogLevel.LOG_WARN:
+        return logging.WARN
+    elif level == proto_ffi.LogLevel.LOG_INFO:
+        return logging.INFO
+    elif level == proto_ffi.LogLevel.LOG_DEBUG:
+        return logging.DEBUG
+    elif level == proto_ffi.LogLevel.LOG_TRACE:
+        # Don't show TRACE logs inside DEBUG, it is too verbos
+        # Python's logging doesn't have a TRACE level
+        # return logging.DEBUG
+        pass
+
+    return None
+
+
+class FfiClient:
+    _instance: Optional["FfiClient"] = None
+    _ffi_disposed: bool = False
+    _instance_lock = threading.Lock()
+
+    @classproperty
+    def instance(cls) -> "FfiClient":
+        if cls._instance is not None:
+            return cls._instance
+        # threads that race here would each get their own client and lose events sent to the other
+        with cls._instance_lock:
+            if cls._instance is None:
+                cls._instance = 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]()
+
+        try:
+            self._ffi_lib = get_ffi_lib()
+        except Exception as e:
+            libname = _lib_name() or "livekit_ffi"
+            raise ImportError(
+                "failed to load %s: %s\n"
+                "Install the livekit package with: pip install livekit\n"
+                "Or set LIVEKIT_LIB_PATH to the path of the native library." % (libname, e)
+            ) from None
+        self._ffi_lib.livekit_ffi_initialize.argtypes = [
+            ffi_cb_fnc,
+            ctypes.c_bool,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+        ]
+        self._ffi_lib.livekit_ffi_request.argtypes = [
+            ctypes.POINTER(ctypes.c_ubyte),
+            ctypes.c_size_t,
+            ctypes.POINTER(ctypes.POINTER(ctypes.c_ubyte)),
+            ctypes.POINTER(ctypes.c_size_t),
+        ]
+        self._ffi_lib.livekit_ffi_request.restype = ctypes.c_uint64
+        self._ffi_lib.livekit_ffi_drop_handle.argtypes = [ctypes.c_uint64]
+        self._ffi_lib.livekit_ffi_drop_handle.restype = ctypes.c_bool
+        self._ffi_lib.livekit_ffi_dispose.argtypes = []
+        self._ffi_lib.livekit_ffi_dispose.restype = None
+
+        self._ffi_lib.livekit_ffi_initialize(
+            ffi_event_callback, True, b"python", __version__.encode("ascii")
+        )
+
+        @atexit.register
+        def _dispose_lk_ffi() -> None:
+            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]:
+        return self._queue
+
+    def request(self, req: proto_ffi.FfiRequest) -> proto_ffi.FfiResponse:
+        if self._pid != os.getpid():
+            raise RuntimeError(
+                "livekit.rtc was used in a parent process before fork(); the native "
+                "runtime cannot be used across fork(). Do not create or connect a Room "
+                "(or use any livekit.rtc object) before forking child processes."
+            )
+        proto_data = req.SerializeToString()
+        proto_len = 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()
+        handle = self._ffi_lib.livekit_ffi_request(
+            data, proto_len, ctypes.byref(resp_ptr), ctypes.byref(resp_len)
+        )
+        assert handle != INVALID_HANDLE
+
+        resp_data = ctypes.string_at(resp_ptr, resp_len.value)
+        resp = proto_ffi.FfiResponse()
+        resp.ParseFromString(resp_data)
+        FfiHandle(handle).dispose()
+        return resp