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, RemoteDataTrackPipelineOptions,
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    SetPipelineOptions(SetPipelineOptions),
35    /// Packet has been received over the transport.
36    PacketReceived(Bytes),
37    /// Resend all subscription updates.
38    ///
39    /// This must be sent after a full reconnect to ensure the SFU knows which
40    /// tracks are subscribed to locally.
41    ///
42    ResendSubscriptionUpdates,
43    /// Shutdown the manager, ending any subscriptions.
44    Shutdown,
45}
46
47/// An event produced by [`Manager`](super::manager::Manager) requiring external action.
48#[derive(Debug, FromVariants)]
49pub enum OutputEvent {
50    SfuUpdateSubscription(SfuUpdateSubscription),
51    TrackPublished(TrackPublished),
52    TrackUnpublished(TrackUnpublished),
53}
54
55// MARK: - Input events
56
57/// Result of a [`SubscribeRequest`].
58pub(super) type SubscribeResult =
59    Result<broadcast::Receiver<DataTrackFrame>, DataTrackSubscribeError>;
60
61/// Client requested to subscribe to a data track.
62///
63/// This is sent when the user calls [`RemoteDataTrack::subscribe`].
64///
65/// Only the first request to subscribe to a given track incurs meaningful overhead; subsequent
66/// requests simply attach an additional receiver to the broadcast channel, allowing them to consume
67/// frames from the existing subscription pipeline.
68///
69#[derive(Debug)]
70pub struct SubscribeRequest {
71    /// Identifier of the track.
72    pub(super) sid: DataTrackSid,
73    /// Options to use for the subscription.
74    pub(super) options: DataTrackSubscribeOptions,
75    /// Async completion channel.
76    pub(super) result_tx: oneshot::Sender<SubscribeResult>,
77}
78
79/// Client requested to unsubscribe from a data track.
80#[derive(Debug)]
81pub struct UnsubscribeRequest {
82    /// Identifier of the track to unsubscribe from.
83    pub(super) sid: DataTrackSid,
84}
85
86/// Client requested to update the pipeline options for a data track.
87#[derive(Debug)]
88pub struct SetPipelineOptions {
89    /// Identifier of the track to update.
90    pub(super) sid: DataTrackSid,
91    /// New pipeline options to apply.
92    pub(super) options: RemoteDataTrackPipelineOptions,
93}
94
95/// SFU notification that track publications have changed.
96///
97/// This event is produced from both [`livekit_protocol::JoinResponse`] and [`livekit_protocol::ParticipantUpdate`]
98/// to provide a complete view of remote participants' track publications:
99///
100/// - From a `JoinResponse`, it captures the initial set of tracks published when a participant joins.
101/// - From a `ParticipantUpdate`, it captures subsequent changes (i.e., new tracks being
102///   published and existing tracks unpublished).
103///
104/// See [`event_from_join`](super::proto::event_from_join) and
105///     [`event_from_participant_update`](super::proto::event_from_participant_update).
106///
107#[derive(Debug)]
108pub struct SfuPublicationUpdates {
109    /// Mapping between participant identity and data tracks currently
110    /// published by that participant.
111    pub updates: HashMap<String, Vec<DataTrackInfo>>,
112}
113
114/// SFU notification that handles have been assigned for requested subscriptions.
115///
116/// Protocol equivalent: [`livekit_protocol::DataTrackSubscriberHandles`].
117///
118#[derive(Debug)]
119pub struct SfuSubscriberHandles {
120    /// Mapping between track handles attached to incoming packets to the
121    /// track SIDs they belong to.
122    pub mapping: HashMap<Handle, DataTrackSid>,
123}
124
125// MARK: - Output events
126
127/// Request sent to the SFU to update the subscription for a data track.
128///
129/// Protocol equivalent: [`livekit_protocol::UpdateDataSubscription`].
130///
131#[derive(Debug)]
132pub struct SfuUpdateSubscription {
133    /// Identifier of the affected track.
134    pub sid: DataTrackSid,
135    /// Whether to subscribe or unsubscribe.
136    pub subscribe: bool,
137}
138
139/// A track has been published by a remote participant and is available to be
140/// subscribed to.
141///
142/// Emit a public event to deliver the track to the user, allowing them to subscribe
143/// with [`RemoteDataTrack::subscribe`] if desired.
144///
145#[derive(Debug)]
146pub struct TrackPublished {
147    /// Track that was published.
148    pub track: RemoteDataTrack,
149}
150
151/// A track has been unpublished by a remote participant.
152///
153/// Emit a public event to inform the user.
154///
155#[derive(Debug)]
156pub struct TrackUnpublished {
157    /// SID of the track that was unpublished.
158    pub sid: DataTrackSid,
159}
livekit_datatrack/remote/events.rs

livekit_datatrack/remote/
events.rs
