Skip to content

Commit 4959b76

Browse files
Additional RemoteTrackPublication options (#219)
Additional RemoteTrackPublication options that better match the JS SDK where possible (FFI-supported only). Built as a result of user issue #212
1 parent 8172332 commit 4959b76

5 files changed

Lines changed: 363 additions & 4 deletions

File tree

‎include/livekit/remote_track_publication.h‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@
1616

1717
#pragma once
1818

19+
#include <cstdint>
20+
21+
#include "livekit/track.h"
1922
#include "livekit/track_publication.h"
2023
#include "livekit/visibility.h"
2124

@@ -32,12 +35,79 @@ class LIVEKIT_API RemoteTrackPublication : public TrackPublication {
3235
/// safe to accept proto::OwnedTrackPublication.
3336
explicit RemoteTrackPublication(const proto::OwnedTrackPublication& owned);
3437

38+
/// @brief Returns the locally recorded subscription state.
39+
///
40+
/// @return True if the publication is marked as subscribed.
3541
bool subscribed() const noexcept { return subscribed_; }
3642

37-
void setSubscribed(bool subscribed);
43+
/// @brief Changes the desired subscription state for this publication.
44+
///
45+
/// @param subscribed True to subscribe; false to unsubscribe.
46+
/// @throws std::runtime_error if the publication has an invalid FFI handle or
47+
/// the FFI request fails.
48+
void setSubscribed(const bool subscribed);
49+
50+
/// @brief Returns whether media delivery is enabled for this publication.
51+
///
52+
/// @return True if media delivery is enabled.
53+
bool enabled() const noexcept { return enabled_; }
54+
55+
/// @brief Enables or disables media delivery for this publication.
56+
///
57+
/// Disabling a subscribed publication reduces bandwidth without changing its
58+
/// desired subscription state.
59+
///
60+
/// @param enabled True to enable media delivery; false to disable it.
61+
/// @return True if an update was sent; false if the state is unchanged or
62+
/// the publication is not subscribed.
63+
/// @throws std::runtime_error if the publication has an invalid FFI handle or
64+
/// the FFI request fails.
65+
bool setEnabled(const bool enabled);
66+
67+
/// @brief Returns the requested maximum simulcast quality.
68+
///
69+
/// @return The requested quality, or @c VideoQuality::HIGH when dimensions
70+
/// are preferred.
71+
VideoQuality videoQuality() const noexcept { return video_quality_; }
72+
73+
/// @brief Requests the maximum simulcast quality to receive.
74+
///
75+
/// This overrides a previous call to setVideoDimensions().
76+
///
77+
/// @param quality Maximum acceptable simulcast quality.
78+
/// @return True if an update was sent; false if the quality is unchanged or
79+
/// the publication is not a subscribed, simulcasted video track.
80+
/// @throws std::runtime_error if the publication has an invalid FFI handle or
81+
/// the FFI request fails.
82+
bool setVideoQuality(const VideoQuality quality);
83+
84+
/// @brief Requests the maximum video dimensions to receive for this publication.
85+
///
86+
/// The server selects the closest available simulcast or scalable-video layer.
87+
/// This overrides a previous call to setVideoQuality().
88+
/// Repeating the current dimensions does not send another request.
89+
///
90+
/// @param width Requested maximum width in pixels. Must be greater than zero.
91+
/// @param height Requested maximum height in pixels. Must be greater than zero.
92+
/// @return True if an update was sent; false if the dimensions are unchanged
93+
/// or the publication is not a subscribed video track.
94+
/// @throws std::runtime_error if the publication has an invalid FFI handle or
95+
/// the FFI request fails.
96+
bool setVideoDimensions(const std::uint32_t width, const std::uint32_t height);
3897

3998
private:
99+
enum class VideoPreference {
100+
DEFAULT,
101+
DIMENSIONS,
102+
QUALITY,
103+
};
104+
40105
bool subscribed_{false};
106+
bool enabled_{true};
107+
VideoPreference video_preference_{VideoPreference::DEFAULT};
108+
VideoQuality video_quality_{VideoQuality::HIGH};
109+
std::uint32_t requested_width_{0};
110+
std::uint32_t requested_height_{0};
41111
};
42112

43113
} // namespace livekit

‎include/livekit/track.h‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
#include <memory>
2222
#include <optional>
2323
#include <string>
24-
#include <unordered_map>
2524
#include <vector>
2625

2726
#include "livekit/ffi_handle.h"
@@ -55,6 +54,13 @@ enum class StreamState {
5554
STATE_PAUSED = 2,
5655
};
5756

57+
/// @brief Maximum receive quality requested for a remote video track.
58+
enum class VideoQuality {
59+
LOW,
60+
MEDIUM,
61+
HIGH,
62+
};
63+
5864
/// @brief Optional audio processing or encoding feature advertised for a track.
5965
enum class AudioTrackFeature {
6066
TF_STEREO = 0,

‎src/remote_track_publication.cpp‎

Lines changed: 118 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818

1919
#include "ffi.pb.h"
2020
#include "ffi_client.h"
21+
#include "lk_log.h"
2122
#include "track_proto_converter.h"
2223

2324
namespace livekit {
@@ -29,7 +30,7 @@ RemoteTrackPublication::RemoteTrackPublication(const proto::OwnedTrackPublicatio
2930
static_cast<EncryptionType>(owned.info().encryption_type()),
3031
convertAudioFeatures(owned.info().audio_features())) {}
3132

32-
void RemoteTrackPublication::setSubscribed(bool subscribed) {
33+
void RemoteTrackPublication::setSubscribed(const bool subscribed) {
3334
if (ffiHandleId() == 0) {
3435
throw std::runtime_error("RemoteTrackPublication::setSubscribed: invalid FFI handle");
3536
}
@@ -47,4 +48,120 @@ void RemoteTrackPublication::setSubscribed(bool subscribed) {
4748
subscribed_ = subscribed;
4849
}
4950

51+
bool RemoteTrackPublication::setEnabled(const bool enabled) {
52+
if (!subscribed_ || track() == nullptr) {
53+
LK_LOG_WARN("RemoteTrackPublication::setEnabled ignored for unsubscribed publication {}", sid());
54+
return false;
55+
}
56+
if (enabled_ == enabled) {
57+
return false;
58+
}
59+
if (ffiHandleId() == 0) {
60+
throw std::runtime_error("RemoteTrackPublication::setEnabled: invalid FFI handle");
61+
}
62+
63+
proto::FfiRequest req;
64+
auto* msg = req.mutable_enable_remote_track_publication();
65+
msg->set_track_publication_handle(static_cast<std::uint64_t>(ffiHandleId()));
66+
msg->set_enabled(enabled);
67+
68+
const proto::FfiResponse resp = FfiClient::instance().sendRequest(req);
69+
if (!resp.has_enable_remote_track_publication()) {
70+
throw std::runtime_error("RemoteTrackPublication::setEnabled: FFI response missing enabled update result");
71+
}
72+
73+
enabled_ = enabled;
74+
return true;
75+
}
76+
77+
bool RemoteTrackPublication::setVideoQuality(const VideoQuality quality) {
78+
if (kind() != TrackKind::KIND_VIDEO) {
79+
LK_LOG_WARN("RemoteTrackPublication::setVideoQuality ignored for non-video publication {}", sid());
80+
return false;
81+
}
82+
if (!simulcasted()) {
83+
LK_LOG_WARN("RemoteTrackPublication::setVideoQuality ignored for non-simulcast publication {}", sid());
84+
return false;
85+
}
86+
if (!subscribed_ || track() == nullptr) {
87+
LK_LOG_WARN("RemoteTrackPublication::setVideoQuality ignored for unsubscribed publication {}", sid());
88+
return false;
89+
}
90+
if (video_preference_ == VideoPreference::QUALITY && video_quality_ == quality) {
91+
return false;
92+
}
93+
94+
proto::VideoQuality proto_quality;
95+
switch (quality) {
96+
case VideoQuality::LOW:
97+
proto_quality = proto::VideoQuality::VIDEO_QUALITY_LOW;
98+
break;
99+
case VideoQuality::MEDIUM:
100+
proto_quality = proto::VideoQuality::VIDEO_QUALITY_MEDIUM;
101+
break;
102+
case VideoQuality::HIGH:
103+
proto_quality = proto::VideoQuality::VIDEO_QUALITY_HIGH;
104+
break;
105+
default:
106+
LK_LOG_WARN("RemoteTrackPublication::setVideoQuality ignored invalid quality for publication {}", sid());
107+
return false;
108+
}
109+
if (ffiHandleId() == 0) {
110+
throw std::runtime_error("RemoteTrackPublication::setVideoQuality: invalid FFI handle");
111+
}
112+
113+
proto::FfiRequest req;
114+
auto* msg = req.mutable_set_remote_track_publication_quality();
115+
msg->set_track_publication_handle(static_cast<std::uint64_t>(ffiHandleId()));
116+
msg->set_quality(proto_quality);
117+
118+
const proto::FfiResponse resp = FfiClient::instance().sendRequest(req);
119+
if (!resp.has_set_remote_track_publication_quality()) {
120+
throw std::runtime_error("RemoteTrackPublication::setVideoQuality: FFI response missing quality update result");
121+
}
122+
123+
video_preference_ = VideoPreference::QUALITY;
124+
video_quality_ = quality;
125+
return true;
126+
}
127+
128+
bool RemoteTrackPublication::setVideoDimensions(const std::uint32_t width, const std::uint32_t height) {
129+
if (kind() != TrackKind::KIND_VIDEO) {
130+
LK_LOG_WARN("RemoteTrackPublication::setVideoDimensions ignored for non-video publication {}", sid());
131+
return false;
132+
}
133+
if (width == 0 || height == 0) {
134+
LK_LOG_WARN("RemoteTrackPublication::setVideoDimensions requires non-zero dimensions for publication {}", sid());
135+
return false;
136+
}
137+
if (!subscribed_ || track() == nullptr) {
138+
LK_LOG_WARN("RemoteTrackPublication::setVideoDimensions ignored for unsubscribed publication {}", sid());
139+
return false;
140+
}
141+
if (video_preference_ == VideoPreference::DIMENSIONS && requested_width_ == width && requested_height_ == height) {
142+
return false;
143+
}
144+
if (ffiHandleId() == 0) {
145+
throw std::runtime_error("RemoteTrackPublication::setVideoDimensions: invalid FFI handle");
146+
}
147+
148+
proto::FfiRequest req;
149+
auto* msg = req.mutable_update_remote_track_publication_dimension();
150+
msg->set_track_publication_handle(static_cast<std::uint64_t>(ffiHandleId()));
151+
msg->set_width(width);
152+
msg->set_height(height);
153+
154+
const proto::FfiResponse resp = FfiClient::instance().sendRequest(req);
155+
if (!resp.has_update_remote_track_publication_dimension()) {
156+
throw std::runtime_error(
157+
"RemoteTrackPublication::setVideoDimensions: FFI response missing dimension update result");
158+
}
159+
160+
requested_width_ = width;
161+
requested_height_ = height;
162+
video_preference_ = VideoPreference::DIMENSIONS;
163+
video_quality_ = VideoQuality::HIGH;
164+
return true;
165+
}
166+
50167
} // namespace livekit
Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
/*
2+
* Copyright 2026 LiveKit
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#include <chrono>
18+
#include <cstdint>
19+
#include <memory>
20+
#include <string>
21+
#include <thread>
22+
23+
#include "tests/common/test_common.h"
24+
25+
namespace livekit::test {
26+
27+
class RemoteTrackPublicationServerTest : public LiveKitTestBase {};
28+
29+
TEST_F(RemoteTrackPublicationServerTest, PublicationControlsRoundTripAndDeduplicate) {
30+
failIfNotConfigured();
31+
32+
Room publisher_room;
33+
Room subscriber_room;
34+
const RoomOptions options;
35+
36+
ASSERT_TRUE(subscriber_room.connect(config_.url, config_.token_b, options));
37+
ASSERT_TRUE(publisher_room.connect(config_.url, config_.token_a, options));
38+
39+
const std::string publisher_identity = lockLocalParticipant(publisher_room)->identity();
40+
ASSERT_TRUE(waitForParticipant(&subscriber_room, publisher_identity, 10s));
41+
42+
constexpr std::uint32_t kSourceWidth = 640;
43+
constexpr std::uint32_t kSourceHeight = 360;
44+
constexpr std::uint32_t kRequestedWidth = 320;
45+
constexpr std::uint32_t kRequestedHeight = 180;
46+
const std::string track_name = "remote-dimension-update";
47+
48+
auto source = std::make_shared<VideoSource>(kSourceWidth, kSourceHeight);
49+
auto track = LocalVideoTrack::createLocalVideoTrack(track_name, source);
50+
TrackPublishOptions publish_options;
51+
publish_options.source = TrackSource::SOURCE_CAMERA;
52+
publish_options.simulcast = true;
53+
ASSERT_NO_THROW(lockLocalParticipant(publisher_room)->publishTrack(track, publish_options));
54+
55+
std::shared_ptr<RemoteTrackPublication> publication;
56+
const auto subscription_deadline = std::chrono::steady_clock::now() + 10s;
57+
while (std::chrono::steady_clock::now() < subscription_deadline) {
58+
auto publisher = subscriber_room.remoteParticipant(publisher_identity).lock();
59+
if (publisher != nullptr) {
60+
for (const auto& [sid, candidate] : publisher->trackPublications()) {
61+
(void)sid;
62+
if (candidate != nullptr && candidate->name() == track_name && candidate->subscribed() &&
63+
candidate->track() != nullptr) {
64+
publication = candidate;
65+
break;
66+
}
67+
}
68+
}
69+
if (publication != nullptr) {
70+
break;
71+
}
72+
std::this_thread::sleep_for(10ms);
73+
}
74+
75+
ASSERT_NE(publication, nullptr) << "Timed out waiting for remote video subscription";
76+
ASSERT_EQ(publication->kind(), TrackKind::KIND_VIDEO);
77+
ASSERT_TRUE(publication->simulcasted());
78+
EXPECT_EQ(publication->width(), kSourceWidth);
79+
EXPECT_EQ(publication->height(), kSourceHeight);
80+
81+
EXPECT_TRUE(publication->setVideoDimensions(kRequestedWidth, kRequestedHeight));
82+
EXPECT_EQ(publication->width(), kSourceWidth);
83+
EXPECT_EQ(publication->height(), kSourceHeight);
84+
EXPECT_FALSE(publication->setVideoDimensions(kRequestedWidth, kRequestedHeight));
85+
86+
EXPECT_FALSE(publication->setVideoQuality(static_cast<VideoQuality>(-1)));
87+
EXPECT_TRUE(publication->setVideoQuality(VideoQuality::LOW));
88+
EXPECT_EQ(publication->videoQuality(), VideoQuality::LOW);
89+
EXPECT_FALSE(publication->setVideoQuality(VideoQuality::LOW));
90+
EXPECT_TRUE(publication->setVideoDimensions(kRequestedWidth, kRequestedHeight));
91+
EXPECT_EQ(publication->videoQuality(), VideoQuality::HIGH);
92+
93+
EXPECT_TRUE(publication->setEnabled(false));
94+
EXPECT_FALSE(publication->enabled());
95+
EXPECT_FALSE(publication->setEnabled(false));
96+
EXPECT_TRUE(publication->setEnabled(true));
97+
EXPECT_TRUE(publication->enabled());
98+
99+
EXPECT_FALSE(publication->setVideoDimensions(0, kRequestedHeight));
100+
101+
publication->setSubscribed(false);
102+
EXPECT_FALSE(publication->setVideoDimensions(kSourceWidth, kSourceHeight));
103+
EXPECT_FALSE(publication->setVideoQuality(VideoQuality::MEDIUM));
104+
EXPECT_FALSE(publication->setEnabled(false));
105+
106+
if (track->publication() != nullptr) {
107+
lockLocalParticipant(publisher_room)->unpublishTrack(track->publication()->sid());
108+
}
109+
}
110+
111+
} // namespace livekit::test

0 commit comments

Comments
 (0)