obs-webrtc: Add trickle ICE support for WHIP

- Reduces connection latency by sending offer after first ICE candidate
- (150ms) instead of waiting for full gather (5s). Late candidates are
- trickled via PATCH per RFC 8840.

Author: steveseguin

plugins/obs-webrtc/whip-output.cpp

@@ -1,6 +1,7 @@
 #include "whip-output.h"
 #include "whip-utils.h"
 
+#include <regex>
 #include <obs.hpp>
 
 /*
@@ -37,7 +38,14 @@ WHIPOutput::WHIPOutput(obs_data_t *, obs_output_t *output)
 	  ice_gathering_mutex(),
 	  ice_gathering_cv(),
 	  ice_gathering_complete(false),
+	  has_first_candidate(false),
+	  offer_sent(false),
 	  has_ice_servers(false),
+	  ice_ufrag(),
+	  ice_pwd(),
+	  pending_candidates(),
+	  pending_candidates_mutex(),
+	  post_response_gather_started(false),
 	  running(false),
 	  start_stop_mutex(),
 	  start_stop_thread(),
@@ -354,14 +362,65 @@ bool WHIPOutput::Setup()
 #endif
 
 	ice_gathering_complete = false;
+	has_first_candidate = false;
+	offer_sent = false;
+	post_response_gather_started = false;
+	ice_ufrag.clear();
+	ice_pwd.clear();
+	first_mid.clear();
+	{
+		std::lock_guard<std::mutex> lock(pending_candidates_mutex);
+		pending_candidates.clear();
+	}
+
 	peer_connection = std::make_shared<rtc::PeerConnection>(cfg);
 
+	// Track when we receive our first ICE candidate
+	peer_connection->onLocalCandidate([this](rtc::Candidate candidate) {
+		{
+			std::lock_guard<std::mutex> lock(ice_gathering_mutex);
+			if (!has_first_candidate) {
+				has_first_candidate = true;
+				first_mid = candidate.mid(); // Saved for end-of-candidates signal
+				ice_gathering_cv.notify_one();
+			}
+		}
+		// If offer already sent, trickle this candidate immediately
+		// Otherwise queue it - it will be sent after POST completes
+		// Only trickle if we have ICE servers (trickle ICE not needed for host-only)
+		if (has_ice_servers) {
+			bool should_send = false;
+			// Lock to synchronize with the flush in Connect()
+			// This prevents candidates from being lost between setting
+			// offer_sent and flushing the queue
+			{
+				std::lock_guard<std::mutex> lock(pending_candidates_mutex);
+				if (offer_sent) {
+					should_send = true;
+				} else {
+					pending_candidates.push_back(candidate);
+				}
+			}
+			if (should_send) {
+				SendTrickleCandidate(candidate);
+			}
+		}
+	});
+
 	// Set up async ICE gathering completion notification
 	peer_connection->onGatheringStateChange([this](rtc::PeerConnection::GatheringState state) {
 		if (state == rtc::PeerConnection::GatheringState::Complete) {
-			std::lock_guard<std::mutex> lock(ice_gathering_mutex);
-			ice_gathering_complete = true;
-			ice_gathering_cv.notify_one();
+			{
+				std::lock_guard<std::mutex> lock(ice_gathering_mutex);
+				ice_gathering_complete = true;
+				ice_gathering_cv.notify_one();
+			}
+			// Only send end-of-candidates after the final (post-response) gather
+			// completes, not after the pre-offer OPTIONS gather. This ensures
+			// candidates from POST response ICE servers aren't ignored (RFC 8840).
+			if (has_ice_servers && post_response_gather_started) {
+				SendEndOfCandidates();
+			}
 		}
 	});
 
@@ -485,23 +544,33 @@ bool WHIPOutput::Connect()
 	std::vector<std::string> http_headers;
 
 #if RTC_VERSION_MAJOR == 0 && RTC_VERSION_MINOR > 20 || RTC_VERSION_MAJOR > 0
-	// Wait for ICE gathering to complete (with timeout) so candidates are
-	// bundled in the offer. This is required for P2P WHIP endpoints that
-	// may not support trickle ICE. Only wait if we have ICE servers.
+	// Smart waiting: if we have ICE servers, wait for first candidate OR 150ms.
+	// This gets us at least host candidates quickly, and likely some STUN
+	// candidates too. Any candidates gathered after offer is sent will be
+	// trickled via PATCH.
 	if (has_ice_servers) {
 		std::unique_lock<std::mutex> lock(ice_gathering_mutex);
-		if (!ice_gathering_complete) {
-			auto timeout = std::chrono::milliseconds(5000);
-			if (!ice_gathering_cv.wait_for(lock, timeout,
-						       [this] { return ice_gathering_complete.load(); })) {
-				do_log(LOG_WARNING, "ICE gathering timed out; sending offer with partial candidates");
-			}
+		if (!has_first_candidate) {
+			// 150ms balances latency vs. candidate coverage; typically enough for host + STUN
+			auto timeout = std::chrono::milliseconds(150);
+			ice_gathering_cv.wait_for(lock, timeout, [this] { return has_first_candidate.load(); });
 		}
 	}
 #endif
 
 	auto offer_sdp = std::string(peer_connection->localDescription().value());
 
+	// Extract ICE credentials for trickle PATCH requests
+	std::regex re_ufrag("a=ice-ufrag:([^\\r\\n]+)");
+	std::regex re_pwd("a=ice-pwd:([^\\r\\n]+)");
+	std::smatch match;
+	if (std::regex_search(offer_sdp, match, re_ufrag)) {
+		ice_ufrag = match[1];
+	}
+	if (std::regex_search(offer_sdp, match, re_pwd)) {
+		ice_pwd = match[1];
+	}
+
 #ifdef DEBUG_SDP
 	do_log(LOG_DEBUG, "Offer SDP:\n%s", offer_sdp.c_str());
 #endif
@@ -631,6 +700,23 @@ bool WHIPOutput::Connect()
 	do_log(LOG_DEBUG, "WHIP Resource URL is: %s", resource_url.c_str());
 	curl_url_cleanup(url_builder);
 
+	// Flush any candidates that arrived during the POST request (trickle ICE only)
+	// Set offer_sent inside the lock to prevent race with onLocalCandidate callback
+	if (has_ice_servers) {
+		std::vector<rtc::Candidate> candidates_to_send;
+		{
+			std::lock_guard<std::mutex> lock(pending_candidates_mutex);
+			offer_sent = true;
+			candidates_to_send = std::move(pending_candidates);
+			pending_candidates.clear();
+		}
+		for (const auto &candidate : candidates_to_send) {
+			SendTrickleCandidate(candidate);
+		}
+	} else {
+		offer_sent = true;
+	}
+
 #ifdef DEBUG_SDP
 	do_log(LOG_DEBUG, "Answer SDP:\n%s", read_buffer.c_str());
 #endif
@@ -677,6 +763,8 @@ bool WHIPOutput::Connect()
 	// Always gather with POST response servers to:
 	// 1. Get host candidates even if no ICE servers provided
 	// 2. Incorporate any TURN servers/credentials from the POST response
+	// Mark that this is the final gather - end-of-candidates will be sent when complete
+	post_response_gather_started = true;
 	peer_connection->gatherLocalCandidates(iceServers);
 #endif
 
@@ -821,6 +909,90 @@ void WHIPOutput::Send(void *data, uintptr_t size, uint64_t duration, std::shared
 	}
 }
 
+void WHIPOutput::SendTrickleIcePatch(const std::string &sdp_frag)
+{
+	struct curl_slist *headers = NULL;
+	headers = curl_slist_append(headers, "Content-Type: application/trickle-ice-sdpfrag");
+	if (!bearer_token.empty()) {
+		auto bearer_token_header = std::string("Authorization: Bearer ") + bearer_token;
+		headers = curl_slist_append(headers, bearer_token_header.c_str());
+	}
+	headers = curl_slist_append(headers, user_agent.c_str());
+
+	char error_buffer[CURL_ERROR_SIZE] = {};
+
+	CURL *c = curl_easy_init();
+	curl_easy_setopt(c, CURLOPT_HTTPHEADER, headers);
+	curl_easy_setopt(c, CURLOPT_URL, resource_url.c_str());
+	curl_easy_setopt(c, CURLOPT_CUSTOMREQUEST, "PATCH");
+	curl_easy_setopt(c, CURLOPT_COPYPOSTFIELDS, sdp_frag.c_str());
+	curl_easy_setopt(c, CURLOPT_TIMEOUT, 8L);
+	curl_easy_setopt(c, CURLOPT_FOLLOWLOCATION, 1L);
+	curl_easy_setopt(c, CURLOPT_UNRESTRICTED_AUTH, 1L);
+	curl_easy_setopt(c, CURLOPT_ERRORBUFFER, error_buffer);
+
+	CURLcode res = curl_easy_perform(c);
+	if (res != CURLE_OK) {
+		do_log(LOG_WARNING, "Trickle ICE PATCH failed: %s",
+		       error_buffer[0] ? error_buffer : curl_easy_strerror(res));
+	} else {
+		long response_code = 0;
+		curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, &response_code);
+		if (response_code < 200 || response_code >= 300) {
+			do_log(LOG_WARNING, "Trickle ICE PATCH returned HTTP %ld", response_code);
+		}
+	}
+
+	curl_easy_cleanup(c);
+	curl_slist_free_all(headers);
+}
+
+void WHIPOutput::SendTrickleCandidate(const rtc::Candidate &candidate)
+{
+	// Guard: credentials not yet extracted from offer SDP
+	if (resource_url.empty() || ice_ufrag.empty() || ice_pwd.empty()) {
+		return;
+	}
+
+	// Build SDP fragment with single candidate (RFC 8840 compliant)
+	std::string sdp_frag;
+	sdp_frag.append("a=ice-ufrag:" + ice_ufrag + "\r\n");
+	sdp_frag.append("a=ice-pwd:" + ice_pwd + "\r\n");
+	std::string mid = candidate.mid();
+	if (!mid.empty()) {
+		sdp_frag.append("a=mid:" + mid + "\r\n");
+	}
+	sdp_frag.append("a=" + candidate.candidate() + "\r\n");
+
+	do_log(LOG_DEBUG, "Trickle ICE candidate (mid=%s): %s", mid.c_str(), candidate.candidate().c_str());
+	SendTrickleIcePatch(sdp_frag);
+}
+
+void WHIPOutput::SendEndOfCandidates()
+{
+	// Guard: credentials not yet extracted from offer SDP
+	if (resource_url.empty() || ice_ufrag.empty() || ice_pwd.empty()) {
+		return;
+	}
+
+	// Build SDP fragment with end-of-candidates marker (RFC 8840 compliant)
+	std::string sdp_frag;
+	sdp_frag.append("a=ice-ufrag:" + ice_ufrag + "\r\n");
+	sdp_frag.append("a=ice-pwd:" + ice_pwd + "\r\n");
+	std::string mid;
+	{
+		std::lock_guard<std::mutex> lock(ice_gathering_mutex);
+		mid = first_mid;
+	}
+	if (!mid.empty()) {
+		sdp_frag.append("a=mid:" + mid + "\r\n");
+	}
+	sdp_frag.append("a=end-of-candidates\r\n");
+
+	do_log(LOG_DEBUG, "Sending end-of-candidates");
+	SendTrickleIcePatch(sdp_frag);
+}
+
 void register_whip_output()
 {
 	const uint32_t base_flags = OBS_OUTPUT_ENCODED | OBS_OUTPUT_SERVICE | OBS_OUTPUT_MULTI_TRACK_AV;

plugins/obs-webrtc/whip-output.h

@@ -15,6 +15,8 @@
 #include <condition_variable>
 
 #include <rtc/rtc.hpp>
+#include <vector>
+#include <rtc/candidate.hpp>
 
 struct videoLayerState {
 	uint16_t sequenceNumber;
@@ -50,6 +52,9 @@ class WHIPOutput {
 	bool FetchIceServersViaOptions(std::vector<rtc::IceServer> &iceServers);
 	void Send(void *data, uintptr_t size, uint64_t duration, std::shared_ptr<rtc::Track> track,
 		  std::shared_ptr<rtc::RtcpSrReporter> rtcp_sr_reporter);
+	void SendTrickleCandidate(const rtc::Candidate &candidate);
+	void SendEndOfCandidates();
+	void SendTrickleIcePatch(const std::string &sdp_frag);
 
 	obs_output_t *output;
 
@@ -60,8 +65,18 @@ class WHIPOutput {
 	std::mutex ice_gathering_mutex;
 	std::condition_variable ice_gathering_cv;
 	std::atomic<bool> ice_gathering_complete;
+	std::atomic<bool> has_first_candidate;
+	std::atomic<bool> offer_sent;
 	bool has_ice_servers;
 
+	// Trickle ICE support (RFC 8840)
+	std::string ice_ufrag;
+	std::string ice_pwd;
+	std::string first_mid;
+	std::vector<rtc::Candidate> pending_candidates; // Queued until POST completes
+	std::mutex pending_candidates_mutex;
+	std::atomic<bool> post_response_gather_started; // Distinguishes pre-offer vs final gather
+
 	std::atomic<bool> running;
 
 	std::mutex start_stop_mutex;