feat: Support different rtp header extentions and payload for each consumer

This commit introduces the ability to specify custom RTP parameters for consumers, allowing for advanced scenarios where the wire-level payload types and header-extension IDs differ from the router's canonical values. The implementation includes validation against the producer's consumable RTP parameters and ensures compatibility. Additionally, tests have been added to verify the correct behavior of this feature, including rejection of overrides in pipe transports and validation of codec mappings.

Author: wuxinfei

node/src/ConsumerTypes.ts

@@ -70,6 +70,25 @@ export type ConsumerOptions<ConsumerAppData extends AppData = AppData> = {
 	 */
 	pipe?: boolean;
 
+	/**
+	 * When set, bypasses ortc.getConsumerRtpParameters and is used verbatim
+	 * as the Consumer's rtpParameters. The payload types and header-extension
+	 * ids declared here become the on-wire values for this Consumer.
+	 *
+	 * mediasoup validates compatibility against the Producer's
+	 * consumableRtpParameters (1:1 codec mapping, compatible fmtp, matching
+	 * layer/simulcast structure, header-extension URIs being a subset of the
+	 * consumable ones) and asks the worker to rewrite outgoing RTP headers
+	 * accordingly.
+	 *
+	 * Intended for advanced scenarios (e.g. WHEP) where the answer SDP
+	 * dictates wire-level PT / ext-id values that differ from the Router's
+	 * canonical ones.
+	 *
+	 * Not supported together with pipe=true.
+	 */
+	rtpParameters?: RtpParameters;
+
 	/**
 	 * Custom application data.
 	 */

node/src/Transport.ts

@@ -585,6 +585,7 @@ export abstract class TransportImpl<
 		ignoreDtx = false,
 		enableRtx,
 		pipe = false,
+		rtpParameters: overrideRtpParameters,
 		appData,
 	}: ConsumerOptions<ConsumerAppData>): Promise<Consumer<ConsumerAppData>> {
 		logger.debug('consume()');
@@ -595,6 +596,10 @@ export abstract class TransportImpl<
 			throw new TypeError('if given, appData must be an object');
 		} else if (mid && (typeof mid !== 'string' || mid.length === 0)) {
 			throw new TypeError('if given, mid must be non empty string');
+		} else if (overrideRtpParameters && pipe) {
+			throw new TypeError(
+				'rtpParameters override is not supported together with pipe=true'
+			);
 		}
 
 		// Clone given RTP capabilities to not modify input data.
@@ -614,19 +619,28 @@ export abstract class TransportImpl<
 			enableRtx = producer.kind === 'video';
 		}
 
+		let consumerRtpMapping: ortc.ConsumerRtpMapping | undefined;
+
 		// This may throw.
-		const rtpParameters = ortc.getConsumerRtpParameters({
+		const rtpParameters: RtpParameters = ortc.getConsumerRtpParameters({
 			consumableRtpParameters: producer.consumableRtpParameters,
-			remoteRtpCapabilities: clonedRtpCapabilities,
+			remoteRtpCapabilities: overrideRtpParameters ?? clonedRtpCapabilities,
 			pipe,
 			enableRtx,
 		});
 
+		if (overrideRtpParameters) {
+			consumerRtpMapping = ortc.getConsumerRtpMapping(
+				producer.consumableRtpParameters,
+				rtpParameters
+			);
+		}
+
 		// Set MID.
 		if (!pipe) {
 			if (mid) {
 				rtpParameters.mid = mid;
-			} else {
+			} else if (!rtpParameters.mid) {
 				rtpParameters.mid = `${this.#nextMidForConsumers++}`;
 
 				// We use up to 8 bytes for MID (string).
@@ -650,6 +664,7 @@ export abstract class TransportImpl<
 			preferredLayers,
 			ignoreDtx,
 			pipe,
+			consumerRtpMapping,
 		});
 
 		const response = await this.channel.request(
@@ -1348,6 +1363,7 @@ function createConsumeRequest({
 	preferredLayers,
 	ignoreDtx,
 	pipe,
+	consumerRtpMapping,
 }: {
 	builder: flatbuffers.Builder;
 	producer: Producer;
@@ -1357,6 +1373,7 @@ function createConsumeRequest({
 	preferredLayers?: ConsumerLayers;
 	ignoreDtx?: boolean;
 	pipe: boolean;
+	consumerRtpMapping?: ortc.ConsumerRtpMapping;
 }): number {
 	const rtpParametersOffset = serializeRtpParameters(builder, rtpParameters);
 	const consumerIdOffset = builder.createString(consumerId);
@@ -1389,6 +1406,15 @@ function createConsumeRequest({
 			FbsConsumer.ConsumerLayers.endConsumerLayers(builder);
 	}
 
+	let consumerRtpMappingOffset: number | undefined;
+
+	if (consumerRtpMapping) {
+		consumerRtpMappingOffset = ortc.serializeConsumerRtpMapping(
+			builder,
+			consumerRtpMapping
+		);
+	}
+
 	const ConsumeRequest = FbsTransport.ConsumeRequest;
 
 	// Create Consume Request.
@@ -1420,6 +1446,10 @@ function createConsumeRequest({
 
 	ConsumeRequest.addIgnoreDtx(builder, Boolean(ignoreDtx));
 
+	if (consumerRtpMappingOffset !== undefined) {
+		ConsumeRequest.addConsumerRtpMapping(builder, consumerRtpMappingOffset);
+	}
+
 	return ConsumeRequest.endConsumeRequest(builder);
 }