livekit-datatrack 0.1.1

Data track core for LiveKit
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

// Copyright 2025 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.

use crate::{
    api::{
        DataTrackFrame, DataTrackInfo, DataTrackSid, DataTrackSubscribeError,
        DataTrackSubscribeOptions, RemoteDataTrack,
    },
    packet::Handle,
};
use bytes::Bytes;
use from_variants::FromVariants;
use std::collections::HashMap;
use tokio::sync::{broadcast, oneshot};

/// An external event handled by [`Manager`](super::manager::Manager).
#[derive(Debug, FromVariants)]
pub enum InputEvent {
    SubscribeRequest(SubscribeRequest),
    UnsubscribeRequest(UnsubscribeRequest),
    SfuPublicationUpdates(SfuPublicationUpdates),
    SfuSubscriberHandles(SfuSubscriberHandles),
    /// Packet has been received over the transport.
    PacketReceived(Bytes),
    /// Resend all subscription updates.
    ///
    /// This must be sent after a full reconnect to ensure the SFU knows which
    /// tracks are subscribed to locally.
    ///
    ResendSubscriptionUpdates,
    /// Shutdown the manager, ending any subscriptions.
    Shutdown,
}

/// An event produced by [`Manager`](super::manager::Manager) requiring external action.
#[derive(Debug, FromVariants)]
pub enum OutputEvent {
    SfuUpdateSubscription(SfuUpdateSubscription),
    TrackPublished(TrackPublished),
    TrackUnpublished(TrackUnpublished),
}

// MARK: - Input events

/// Result of a [`SubscribeRequest`].
pub(super) type SubscribeResult =
    Result<broadcast::Receiver<DataTrackFrame>, DataTrackSubscribeError>;

/// Client requested to subscribe to a data track.
///
/// This is sent when the user calls [`RemoteDataTrack::subscribe`].
///
/// Only the first request to subscribe to a given track incurs meaningful overhead; subsequent
/// requests simply attach an additional receiver to the broadcast channel, allowing them to consume
/// frames from the existing subscription pipeline.
///
#[derive(Debug)]
pub struct SubscribeRequest {
    /// Identifier of the track.
    pub(super) sid: DataTrackSid,
    /// Options to use for the subscription.
    pub(super) options: DataTrackSubscribeOptions,
    /// Async completion channel.
    pub(super) result_tx: oneshot::Sender<SubscribeResult>,
}

/// Client requested to unsubscribe from a data track.
#[derive(Debug)]
pub struct UnsubscribeRequest {
    /// Identifier of the track to unsubscribe from.
    pub(super) sid: DataTrackSid,
}

/// SFU notification that track publications have changed.
///
/// This event is produced from both [`livekit_protocol::JoinResponse`] and [`livekit_protocol::ParticipantUpdate`]
/// to provide a complete view of remote participants' track publications:
///
/// - From a `JoinResponse`, it captures the initial set of tracks published when a participant joins.
/// - From a `ParticipantUpdate`, it captures subsequent changes (i.e., new tracks being
///   published and existing tracks unpublished).
///
/// See [`event_from_join`](super::proto::event_from_join) and
///     [`event_from_participant_update`](super::proto::event_from_participant_update).
///
#[derive(Debug)]
pub struct SfuPublicationUpdates {
    /// Mapping between participant identity and data tracks currently
    /// published by that participant.
    pub updates: HashMap<String, Vec<DataTrackInfo>>,
}

/// SFU notification that handles have been assigned for requested subscriptions.
///
/// Protocol equivalent: [`livekit_protocol::DataTrackSubscriberHandles`].
///
#[derive(Debug)]
pub struct SfuSubscriberHandles {
    /// Mapping between track handles attached to incoming packets to the
    /// track SIDs they belong to.
    pub mapping: HashMap<Handle, DataTrackSid>,
}

// MARK: - Output events

/// Request sent to the SFU to update the subscription for a data track.
///
/// Protocol equivalent: [`livekit_protocol::UpdateDataSubscription`].
///
#[derive(Debug)]
pub struct SfuUpdateSubscription {
    /// Identifier of the affected track.
    pub sid: DataTrackSid,
    /// Whether to subscribe or unsubscribe.
    pub subscribe: bool,
}

/// A track has been published by a remote participant and is available to be
/// subscribed to.
///
/// Emit a public event to deliver the track to the user, allowing them to subscribe
/// with [`RemoteDataTrack::subscribe`] if desired.
///
#[derive(Debug)]
pub struct TrackPublished {
    /// Track that was published.
    pub track: RemoteDataTrack,
}

/// A track has been unpublished by a remote participant.
///
/// Emit a public event to inform the user.
///
#[derive(Debug)]
pub struct TrackUnpublished {
    /// SID of the track that was unpublished.
    pub sid: DataTrackSid,
}