livekit 1.2.1__py3-none-win_arm64.whl

livekit/rtc/track.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.
+
+from __future__ import annotations
+
+import weakref
+from typing import TYPE_CHECKING, List, Optional, Union
+from ._ffi_client import FfiHandle, FfiClient
+from ._proto import ffi_pb2 as proto_ffi
+from ._proto import track_pb2 as proto_track
+from ._proto import stats_pb2 as proto_stats
+
+if TYPE_CHECKING:
+    from .audio_source import AudioSource
+    from .audio_stream import AudioStream
+    from .room import Room
+    from .video_source import VideoSource
+    from .encoded_video import EncodedVideoSource
+    from .platform_audio import PlatformAudioSource
+
+
+class Track:
+    def __init__(self, owned_info: proto_track.OwnedTrack):
+        self._info = owned_info.info
+        self._ffi_handle = FfiHandle(owned_info.handle.id)
+        self._room_ref: Optional[weakref.ref[Room]] = None
+        self._audio_streams: weakref.WeakSet[AudioStream] = weakref.WeakSet()
+
+    def _resolve_room(self) -> Optional[Room]:
+        return self._room_ref() if self._room_ref is not None else None
+
+    def _set_room(self, room: Optional[Room]) -> None:
+        old_room = self._resolve_room()
+        if old_room is None and room is None:
+            # Already roomless — nothing to detach and nothing to re-clear.
+            # Without this guard a second _set_room(None) (e.g. the unpublish /
+            # local_track_unpublished race calling it from both paths) would
+            # re-fire _on_*_cleared on every registered processor.
+            return
+        if old_room is not room:
+            if old_room is not None:
+                old_room.off("token_refreshed", self._on_room_token_refreshed)
+            if room is not None:
+                room.on("token_refreshed", self._on_room_token_refreshed)
+
+        self._room_ref = weakref.ref(room) if room is not None else None
+
+        for stream in self._audio_streams:
+            self._push_processor_metadata_to_stream(stream, room)
+
+    def _on_room_token_refreshed(self) -> None:
+        room = self._resolve_room()
+        if room is None or room._token is None or room._server_url is None:
+            return
+        for stream in self._audio_streams:
+            if not stream._processor:
+                continue
+            stream._processor._on_credentials_updated(token=room._token, url=room._server_url)
+
+    def _push_processor_metadata_to_stream(self, stream: AudioStream, room: Optional[Room]) -> None:
+        if not stream._processor:
+            return
+
+        if room is None:
+            # track left a room - clear processor's room context
+            stream._processor._on_stream_info_cleared()
+            stream._processor._on_credentials_cleared()
+            return
+
+        identity = ""
+        pub_sid = ""
+        track_sid = self.sid
+        if track_sid:
+            for participant in room.remote_participants.values():
+                publication = participant.track_publications.get(track_sid)
+                if publication is not None:
+                    identity, pub_sid = participant.identity, publication.sid
+                    break
+            else:
+                local = room._local_participant
+                if local is not None:
+                    for local_publication in local.track_publications.values():
+                        if local_publication.sid == track_sid:
+                            identity, pub_sid = local.identity, local_publication.sid
+                            break
+
+        stream._processor._on_stream_info_updated(
+            room_name=room.name,
+            participant_identity=identity,
+            publication_sid=pub_sid,
+        )
+        if room._token is not None and room._server_url is not None:
+            stream._processor._on_credentials_updated(token=room._token, url=room._server_url)
+
+    def _register_audio_stream(self, stream: AudioStream) -> None:
+        self._audio_streams.add(stream)
+        room = self._resolve_room()
+        if room is not None:
+            self._push_processor_metadata_to_stream(stream, room)
+
+    def _unregister_audio_stream(self, stream: AudioStream) -> None:
+        self._audio_streams.discard(stream)
+
+    @property
+    def sid(self) -> str:
+        return self._info.sid
+
+    @property
+    def name(self) -> str:
+        return self._info.name
+
+    @property
+    def kind(self) -> proto_track.TrackKind.ValueType:
+        return self._info.kind
+
+    @property
+    def stream_state(self) -> proto_track.StreamState.ValueType:
+        return self._info.stream_state
+
+    @property
+    def muted(self) -> bool:
+        return self._info.muted
+
+    async def get_stats(self) -> List[proto_stats.RtcStats]:
+        req = proto_ffi.FfiRequest()
+        req.get_stats.track_handle = self._ffi_handle.handle
+
+        queue = FfiClient.instance.queue.subscribe()
+        try:
+            resp = FfiClient.instance.request(req)
+            cb: proto_ffi.FfiEvent = await queue.wait_for(
+                lambda e: e.get_stats.async_id == resp.get_stats.async_id
+            )
+        finally:
+            FfiClient.instance.queue.unsubscribe(queue)
+
+        if cb.get_stats.error:
+            raise Exception(cb.get_stats.error)
+
+        return list(cb.get_stats.stats)
+
+
+class LocalAudioTrack(Track):
+    def __init__(self, info: proto_track.OwnedTrack):
+        super().__init__(info)
+
+    @staticmethod
+    def create_audio_track(
+        name: str, source: Union["AudioSource", "PlatformAudioSource"]
+    ) -> "LocalAudioTrack":
+        """Create a local audio track from an audio source.
+
+        Args:
+            name: The name of the track (e.g., "microphone", "audio-file").
+            source: Either an AudioSource (synthetic mode for manual frame capture)
+                or a PlatformAudioSource (from PlatformAudio, uses WebRTC ADM).
+
+        Returns:
+            A LocalAudioTrack that can be published to a room.
+
+        Example with PlatformAudio (recommended for most use cases):
+            ```python
+            platform_audio = rtc.PlatformAudio()
+            source = platform_audio.create_audio_source()
+            track = rtc.LocalAudioTrack.create_audio_track("microphone", source)
+            ```
+
+        Example with AudioSource (synthetic mode for custom processing):
+            ```python
+            # Synthetic mode: You must manually capture frames
+            source = rtc.AudioSource(sample_rate=48000, num_channels=1)
+            track = rtc.LocalAudioTrack.create_audio_track("audio", source)
+            # Then in a loop: await source.capture_frame(frame)
+            ```
+        """
+        req = proto_ffi.FfiRequest()
+        req.create_audio_track.name = name
+        req.create_audio_track.source_handle = source._ffi_handle.handle
+
+        resp = FfiClient.instance.request(req)
+        return LocalAudioTrack(resp.create_audio_track.track)
+
+    def mute(self) -> None:
+        req = proto_ffi.FfiRequest()
+        req.local_track_mute.track_handle = self._ffi_handle.handle
+        req.local_track_mute.mute = True
+        FfiClient.instance.request(req)
+        self._info.muted = True
+
+    def unmute(self) -> None:
+        req = proto_ffi.FfiRequest()
+        req.local_track_mute.track_handle = self._ffi_handle.handle
+        req.local_track_mute.mute = False
+        FfiClient.instance.request(req)
+        self._info.muted = False
+
+    def __repr__(self) -> str:
+        return f"rtc.LocalAudioTrack(sid={self.sid}, name={self.name})"
+
+
+class LocalVideoTrack(Track):
+    def __init__(self, info: proto_track.OwnedTrack):
+        super().__init__(info)
+
+    @staticmethod
+    def create_video_track(
+        name: str, source: "Union[VideoSource, EncodedVideoSource]"
+    ) -> "LocalVideoTrack":
+        req = proto_ffi.FfiRequest()
+        req.create_video_track.name = name
+        req.create_video_track.source_handle = source._ffi_handle.handle
+
+        resp = FfiClient.instance.request(req)
+        return LocalVideoTrack(resp.create_video_track.track)
+
+    def mute(self) -> None:
+        req = proto_ffi.FfiRequest()
+        req.local_track_mute.track_handle = self._ffi_handle.handle
+        req.local_track_mute.mute = True
+        FfiClient.instance.request(req)
+        self._info.muted = True
+
+    def unmute(self) -> None:
+        req = proto_ffi.FfiRequest()
+        req.local_track_mute.track_handle = self._ffi_handle.handle
+        req.local_track_mute.mute = False
+        FfiClient.instance.request(req)
+        self._info.muted = False
+
+    def __repr__(self) -> str:
+        return f"rtc.LocalVideoTrack(sid={self.sid}, name={self.name})"
+
+
+class RemoteAudioTrack(Track):
+    def __init__(self, info: proto_track.OwnedTrack):
+        super().__init__(info)
+
+    def __repr__(self) -> str:
+        return f"rtc.RemoteAudioTrack(sid={self.sid}, name={self.name})"
+
+
+class RemoteVideoTrack(Track):
+    def __init__(self, info: proto_track.OwnedTrack):
+        super().__init__(info)
+
+    def __repr__(self) -> str:
+        return f"rtc.RemoteVideoTrack(sid={self.sid}, name={self.name})"
+
+
+LocalTrack = Union[LocalVideoTrack, LocalAudioTrack]
+RemoteTrack = Union[RemoteVideoTrack, RemoteAudioTrack]
+AudioTrack = Union[LocalAudioTrack, RemoteAudioTrack]
+VideoTrack = Union[LocalVideoTrack, RemoteVideoTrack]

livekit/rtc/track_publication.py

@@ -0,0 +1,145 @@
+# 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 typing import List, Optional, cast
+import asyncio
+
+from ._ffi_client import FfiHandle, FfiClient
+from ._proto import e2ee_pb2 as proto_e2ee
+from ._proto import ffi_pb2 as proto_ffi
+from ._proto import track_pb2 as proto_track
+from ._proto import track_publication_pb2 as proto_track_pub
+from .track import Track, LocalTrack, RemoteTrack
+
+VideoQuality = proto_track_pub.VideoQuality
+
+
+class TrackPublication:
+    def __init__(self, owned_info: proto_track.OwnedTrackPublication):
+        self._info = owned_info.info
+        self._track: Optional[Track] = None
+        self._ffi_handle = FfiHandle(owned_info.handle.id)
+
+    @property
+    def track(self) -> Optional[Track]:
+        return self._track
+
+    @property
+    def sid(self) -> str:
+        return self._info.sid
+
+    @property
+    def name(self) -> str:
+        return self._info.name
+
+    @property
+    def kind(self) -> proto_track.TrackKind.ValueType:
+        return self._info.kind
+
+    @property
+    def source(self) -> proto_track.TrackSource.ValueType:
+        return self._info.source
+
+    @property
+    def simulcasted(self) -> bool:
+        return self._info.simulcasted
+
+    @property
+    def width(self) -> int:
+        return self._info.width
+
+    @property
+    def height(self) -> int:
+        return self._info.height
+
+    @property
+    def mime_type(self) -> str:
+        return self._info.mime_type
+
+    @property
+    def muted(self) -> bool:
+        return self._info.muted
+
+    @property
+    def encryption_type(self) -> proto_e2ee.EncryptionType.ValueType:
+        return self._info.encryption_type
+
+    @property
+    def audio_features(self) -> List[proto_track.AudioTrackFeature.ValueType]:
+        return list(self._info.audio_features)
+
+    @property
+    def frame_metadata_features(self) -> List[proto_track.FrameMetadataFeature.ValueType]:
+        return list(self._info.frame_metadata_features)
+
+
+class LocalTrackPublication(TrackPublication):
+    def __init__(self, owned_info: proto_track.OwnedTrackPublication):
+        super().__init__(owned_info)
+        self._first_subscription: asyncio.Future[None] = asyncio.Future()
+
+    @property
+    def track(self) -> Optional[LocalTrack]:
+        return cast(Optional[LocalTrack], self._track)
+
+    async def wait_for_subscription(self) -> None:
+        await asyncio.shield(self._first_subscription)
+
+    def __repr__(self) -> str:
+        return f"rtc.LocalTrackPublication(sid={self.sid}, name={self.name}, kind={self.kind}, source={self.source})"
+
+
+class RemoteTrackPublication(TrackPublication):
+    def __init__(self, owned_info: proto_track.OwnedTrackPublication):
+        super().__init__(owned_info)
+        self._subscribed = False
+
+    @property
+    def track(self) -> Optional[RemoteTrack]:
+        return cast(Optional[RemoteTrack], self._track)
+
+    @property
+    def subscribed(self) -> bool:
+        return self._subscribed
+
+    def set_subscribed(self, subscribed: bool) -> None:
+        req = proto_ffi.FfiRequest()
+        req.set_subscribed.subscribe = subscribed
+        req.set_subscribed.publication_handle = self._ffi_handle.handle
+        FfiClient.instance.request(req)
+
+    def set_video_quality(self, quality: "VideoQuality.ValueType") -> None:
+        """For simulcasted video tracks, request a specific simulcast layer
+        from the server. Use one of `rtc.VideoQuality.VIDEO_QUALITY_LOW` (q),
+        `VIDEO_QUALITY_MEDIUM` (h), or `VIDEO_QUALITY_HIGH` (f).
+
+        Raises:
+            ValueError: if the publication is not a video track, or is not
+                simulcasted (selecting a layer requires multiple layers).
+        """
+        if self.kind != proto_track.TrackKind.KIND_VIDEO:
+            raise ValueError(
+                f"set_video_quality is only supported on video publications (sid={self.sid})"
+            )
+        if not self.simulcasted:
+            raise ValueError(
+                f"set_video_quality requires a simulcasted publication (sid={self.sid})"
+            )
+        req = proto_ffi.FfiRequest()
+        req.set_remote_track_publication_quality.track_publication_handle = self._ffi_handle.handle
+        req.set_remote_track_publication_quality.quality = quality
+        FfiClient.instance.request(req)
+
+    def __repr__(self) -> str:
+        return f"rtc.RemoteTrackPublication(sid={self.sid}, name={self.name}, kind={self.kind}, source={self.source})"

livekit/rtc/transcription.py

@@ -0,0 +1,19 @@
+from typing import List
+from dataclasses import dataclass
+
+
+@dataclass
+class Transcription:
+    participant_identity: str
+    track_sid: str
+    segments: List["TranscriptionSegment"]
+
+
+@dataclass
+class TranscriptionSegment:
+    id: str
+    text: str
+    start_time: int
+    end_time: int
+    language: str
+    final: bool

livekit/rtc/utils.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import AsyncIterator
+
+from .audio_frame import AudioFrame
+
+
+__all__ = ["combine_audio_frames", "sine_wave_generator"]
+
+
+def combine_audio_frames(buffer: AudioFrame | list[AudioFrame]) -> AudioFrame:
+    """
+    Combines one or more `rtc.AudioFrame` objects into a single `rtc.AudioFrame`.
+
+    This function concatenates the audio data from multiple frames, ensuring that
+    all frames have the same sample rate and number of channels. It efficiently
+    merges the data by preallocating the necessary memory and copying the frame
+    data without unnecessary reallocations.
+
+    Args:
+        buffer: A single `rtc.AudioFrame` or a list of `rtc.AudioFrame`
+            objects to be combined.
+
+    Returns:
+        rtc.AudioFrame: A new `rtc.AudioFrame` containing the combined audio data.
+
+    Raises:
+        ValueError: If the buffer is empty.
+        ValueError: If frames have differing sample rates.
+        ValueError: If frames have differing numbers of channels.
+
+    Example:
+        >>> frame1 = rtc.AudioFrame(
+        ...     data=b"\x01\x02", sample_rate=48000, num_channels=2, samples_per_channel=1
+        ... )
+        >>> frame2 = rtc.AudioFrame(
+        ...     data=b"\x03\x04", sample_rate=48000, num_channels=2, samples_per_channel=1
+        ... )
+        >>> combined_frame = combine_audio_frames([frame1, frame2])
+        >>> combined_frame.data
+        b'\x01\x02\x03\x04'
+        >>> combined_frame.sample_rate
+        48000
+        >>> combined_frame.num_channels
+        2
+        >>> combined_frame.samples_per_channel
+        2
+    """
+    if not isinstance(buffer, list):
+        return buffer
+
+    if not buffer:
+        raise ValueError("buffer is empty")
+
+    sample_rate = buffer[0].sample_rate
+    num_channels = buffer[0].num_channels
+
+    total_data_length = 0
+    total_samples_per_channel = 0
+
+    for frame in buffer:
+        if frame.sample_rate != sample_rate:
+            raise ValueError(
+                f"Sample rate mismatch: expected {sample_rate}, got {frame.sample_rate}"
+            )
+
+        if frame.num_channels != num_channels:
+            raise ValueError(
+                f"Channel count mismatch: expected {num_channels}, got {frame.num_channels}"
+            )
+
+        total_data_length += len(frame.data)
+        total_samples_per_channel += frame.samples_per_channel
+
+    data = bytearray(total_data_length)
+    offset = 0
+    for frame in buffer:
+        frame_data = frame.data.cast("b")
+        data[offset : offset + len(frame_data)] = frame_data
+        offset += len(frame_data)
+
+    return AudioFrame(
+        data=data,
+        sample_rate=sample_rate,
+        num_channels=num_channels,
+        samples_per_channel=total_samples_per_channel,
+    )
+
+
+async def sine_wave_generator(
+    freq: float,
+    duration: float,
+    sample_rate: int = 48000,
+    amplitude: float = 0.3,
+) -> AsyncIterator[AudioFrame]:
+    """
+    Generate sine wave audio frames.
+
+    Useful for testing audio pipelines and generating test signals.
+
+    Args:
+        freq: Frequency of the sine wave in Hz.
+        duration: Duration of the audio in seconds.
+        sample_rate: Sample rate in Hz (default: 48000).
+        amplitude: Amplitude of the sine wave, range [0.0, 1.0] (default: 0.3).
+
+    Yields:
+        AudioFrame: Audio frames containing sine wave data.
+
+    Example:
+        >>> import asyncio
+        >>> async def generate_audio():
+        ...     async for frame in sine_wave_generator(440, 1.0):
+        ...         print(f"Generated frame with {frame.samples_per_channel} samples")
+        >>> asyncio.run(generate_audio())
+    """
+    try:
+        import numpy as np
+    except ImportError:
+        raise ImportError(
+            "numpy is required for sine_wave_generator. Install it with: pip install numpy"
+        )
+
+    blocksize = sample_rate // 10
+    total_frames = int((duration * sample_rate) // blocksize)
+    t_frame = np.arange(blocksize) / sample_rate
+
+    for i in range(total_frames):
+        t = t_frame + i * blocksize / sample_rate
+        signal = amplitude * np.sin(2 * np.pi * freq * t)
+        signal_int16 = np.int16(signal * 32767)
+        frame = AudioFrame(
+            signal_int16.tobytes(),
+            sample_rate,
+            1,
+            blocksize,
+        )
+        yield frame

livekit/rtc/version.py

@@ -0,0 +1 @@
+__version__ = "1.2.1"