livekit_datatrack/remote/
events.rs

1// Copyright 2025 LiveKit, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use crate::{
16    api::{
17        DataTrackFrame, DataTrackInfo, DataTrackSid, DataTrackSubscribeError,
18        DataTrackSubscribeOptions, RemoteDataTrack,
19    },
20    packet::Handle,
21};
22use bytes::Bytes;
23use from_variants::FromVariants;
24use std::collections::HashMap;
25use tokio::sync::{broadcast, oneshot};
26
27/// An external event handled by [`Manager`](super::manager::Manager).
28#[derive(Debug, FromVariants)]
29pub enum InputEvent {
30    SubscribeRequest(SubscribeRequest),
31    UnsubscribeRequest(UnsubscribeRequest),
32    SfuPublicationUpdates(SfuPublicationUpdates),
33    SfuSubscriberHandles(SfuSubscriberHandles),
34    /// Packet has been received over the transport.
35    PacketReceived(Bytes),
36    /// Resend all subscription updates.
37    ///
38    /// This must be sent after a full reconnect to ensure the SFU knows which
39    /// tracks are subscribed to locally.
40    ///
41    ResendSubscriptionUpdates,
42    /// Shutdown the manager, ending any subscriptions.
43    Shutdown,
44}
45
46/// An event produced by [`Manager`](super::manager::Manager) requiring external action.
47#[derive(Debug, FromVariants)]
48pub enum OutputEvent {
49    SfuUpdateSubscription(SfuUpdateSubscription),
50    TrackPublished(TrackPublished),
51    TrackUnpublished(TrackUnpublished),
52}
53
54// MARK: - Input events
55
56/// Result of a [`SubscribeRequest`].
57pub(super) type SubscribeResult =
58    Result<broadcast::Receiver<DataTrackFrame>, DataTrackSubscribeError>;
59
60/// Client requested to subscribe to a data track.
61///
62/// This is sent when the user calls [`RemoteDataTrack::subscribe`].
63///
64/// Only the first request to subscribe to a given track incurs meaningful overhead; subsequent
65/// requests simply attach an additional receiver to the broadcast channel, allowing them to consume
66/// frames from the existing subscription pipeline.
67///
68#[derive(Debug)]
69pub struct SubscribeRequest {
70    /// Identifier of the track.
71    pub(super) sid: DataTrackSid,
72    /// Options to use for the subscription.
73    pub(super) options: DataTrackSubscribeOptions,
74    /// Async completion channel.
75    pub(super) result_tx: oneshot::Sender<SubscribeResult>,
76}
77
78/// Client requested to unsubscribe from a data track.
79#[derive(Debug)]
80pub struct UnsubscribeRequest {
81    /// Identifier of the track to unsubscribe from.
82    pub(super) sid: DataTrackSid,
83}
84
85/// SFU notification that track publications have changed.
86///
87/// This event is produced from both [`livekit_protocol::JoinResponse`] and [`livekit_protocol::ParticipantUpdate`]
88/// to provide a complete view of remote participants' track publications:
89///
90/// - From a `JoinResponse`, it captures the initial set of tracks published when a participant joins.
91/// - From a `ParticipantUpdate`, it captures subsequent changes (i.e., new tracks being
92///   published and existing tracks unpublished).
93///
94/// See [`event_from_join`](super::proto::event_from_join) and
95///     [`event_from_participant_update`](super::proto::event_from_participant_update).
96///
97#[derive(Debug)]
98pub struct SfuPublicationUpdates {
99    /// Mapping between participant identity and data tracks currently
100    /// published by that participant.
101    pub updates: HashMap<String, Vec<DataTrackInfo>>,
102}
103
104/// SFU notification that handles have been assigned for requested subscriptions.
105///
106/// Protocol equivalent: [`livekit_protocol::DataTrackSubscriberHandles`].
107///
108#[derive(Debug)]
109pub struct SfuSubscriberHandles {
110    /// Mapping between track handles attached to incoming packets to the
111    /// track SIDs they belong to.
112    pub mapping: HashMap<Handle, DataTrackSid>,
113}
114
115// MARK: - Output events
116
117/// Request sent to the SFU to update the subscription for a data track.
118///
119/// Protocol equivalent: [`livekit_protocol::UpdateDataSubscription`].
120///
121#[derive(Debug)]
122pub struct SfuUpdateSubscription {
123    /// Identifier of the affected track.
124    pub sid: DataTrackSid,
125    /// Whether to subscribe or unsubscribe.
126    pub subscribe: bool,
127}
128
129/// A track has been published by a remote participant and is available to be
130/// subscribed to.
131///
132/// Emit a public event to deliver the track to the user, allowing them to subscribe
133/// with [`RemoteDataTrack::subscribe`] if desired.
134///
135#[derive(Debug)]
136pub struct TrackPublished {
137    /// Track that was published.
138    pub track: RemoteDataTrack,
139}
140
141/// A track has been unpublished by a remote participant.
142///
143/// Emit a public event to inform the user.
144///
145#[derive(Debug)]
146pub struct TrackUnpublished {
147    /// SID of the track that was unpublished.
148    pub sid: DataTrackSid,
149}
livekit_datatrack/remote/events.rs

livekit_datatrack/remote/
events.rs
