RTCRtpSender: метод setParameters()

Метод setParameters() интерфейса RTCRtpSender применяет изменения к конфигурации отправителя track, который является MediaStreamTrack, за который отвечает RTCRtpSender.

Другими словами, setParameters() обновляет конфигурацию передачи RTP, а также конфигурацию кодирования для определённого исходящего медиапотока в соединении WebRTC.

parameters

Объект параметров, полученный ранее вызовом метода getParameters() того же отправителя с желаемыми изменениями параметров конфигурации отправителя. Эти параметры включают потенциальные кодеки, которые могут быть использованы для кодирования track отправителя. Доступные параметры:

encodings

Массив объектов, каждый из которых определяет параметры для одного кодека, который может использоваться для кодирования медиа потока. Свойства объектов включают:

active

Установив это значение в true (по умолчанию), это кодирование будет отправляться, в то время как false прекращает его отправку и использование (но не приводит к удалению SSRC).

dtx Устаревший Нестандартный

Используется только для RTCRtpSender, у которого тип kind равен audio, это свойство указывает, использовать ли прерывистую передачу (функция, при которой телефон выключается или микрофон автоматически отключается в отсутствие активности голоса). Значение берется либо enabled, либо disabled.

maxBitrate

Положительное целое число, указывающее максимальное количество бит в секунду, которое пользовательский агент разрешено предоставить для кодирования с этим кодеком. Другие параметры могут дополнительно ограничивать скорость передачи, такие как значение maxFramerate, или пропускную способность, доступную для транспорта или физической сети.

Значение вычисляется с использованием стандартной пропускной способности приложений с максимальной пропускной способностью независимо от транспорта (TIAS), как определено в RFC 3890, раздел 6.2.2; это максимальная пропускная способность, необходимая без учёта накладных расходов протоколов от IP, TCP или UDP и так далее.

Обратите внимание, что скорость передачи данных может быть достигнута различными способами, в зависимости от медиа и кодирования. Например, для видео низкая скорость передачи данных может быть достигнута путём пропуска кадров (скорость передачи данных ноль может позволить отправить только один кадр), а для аудио поток может быть остановлен, если скорость передачи данных слишком низкая для его отправки.

maxFramerate

Значение, указывающее максимальное количество кадров в секунду для этого кодирования.

priority

Строка, указывающая приоритет RTCRtpSender, что может определять, как пользовательский агент распределяет пропускную способность между отправителями. Разрешенные значения: very-low, low (по умолчанию), medium, high.

rid

Строка, которая, если задана, определяет идентификатор потока RTP (RID), который будет отправлен с помощью расширения заголовка RID. Этот параметр нельзя изменить с помощью setParameters(). Его значение можно установить только при первом создании трансивера.

scaleResolutionDownBy

Используется только для отправителей, у которых тип медиапотока kind равен video, это число с плавающей запятой, указывающее множитель, на который необходимо уменьшить видео во время кодирования. Значение по умолчанию 1.0 означает, что видео будет кодироваться в исходном размере. Значение 2.0 уменьшает видеокадры в два раза по каждой размерности, что приводит к видео в 1/4 размера оригинала. Значение не должно быть меньше 1.0 (попытка масштабирования видео до большего размера приведёт к ошибке RangeError).

transactionId

Строка, содержащая уникальный идентификатор. Этот идентификатор устанавливается в предыдущем вызове getParameters() и гарантирует, что параметры получены из предыдущего вызова getParameters().

codecs

Массив объектов, описывающих медиа-кодеки, из которых отправитель выберет кодек. Этот параметр нельзя изменить после первоначальной установки.

Каждый объект кодека в массиве может иметь следующие свойства:

channels Необязательно

Положительное целое число, указывающее количество каналов, поддерживаемых кодеком. Например, для аудиокодеков значение 1 обозначает монофонический звук, а 2 — стерео.

clockRate

Положительное целое число, указывающее частоту тактирования кодека в Герцах (Гц). Частота тактирования — это частота, с которой увеличивается метка времени RTP кодека. Большинство кодеков имеют определённые значения или диапазоны значений, которые они допускают. IANA поддерживает список кодеков и их параметров, включая их частоты тактирования.

mimeType

Строка, обозначающая MIME тип и подтип медиа кодека, указанный в виде строки типа "type/subtype". Строки MIME-типов, используемые в RTP, отличаются от используемых в других местах. IANA поддерживает реестр допустимых MIME-типов. Также см. Кодеки, используемые в WebRTC для получения дополнительной информации о потенциальных кодеках, которые могут быть здесь указаны.

payloadType

Используемый тип полезной нагрузки RTP для идентификации этого кодека.

sdpFmtpLine Необязательно

Строка, содержащая параметры, специфичные для формата, предоставляемые локальным описанием.

headerExtensions

Массив нуля или более расширений заголовка RTP, каждый из которых идентифицирует расширение, поддерживаемое отправителем. Расширения заголовков описаны в RFC 3550, раздел 5.3.1. Этот параметр нельзя изменить.

rtcp

Объект RTCRtcpParameters, предоставляющий параметры конфигурации, используемые для RTCP отправителя. Этот параметр нельзя изменить.

degradationPreference Устаревший

Указывает предпочтительный способ обработки оптимизации пропускной способности в ущерб качеству в ситуациях с ограниченной пропускной способностью. Возможные значения: maintain-framerate, maintain-resolution, или balanced. Значение по умолчанию: balanced.

Объект Promise, который разрешается при обновлении свойства RTCRtpSender.track заданными параметрами.

Если произошла ошибка, возвращаемое обещание отклоняется соответствующим исключением из списка ниже.

InvalidModificationError DOMException

Возвращается, если обнаружена одна из следующих проблем:

• Количество кодировок, указанных в свойстве parameters объекта encodings, не соответствует количеству кодировок, в настоящее время перечисленных для RTCRtpSender. Вы не можете изменить количество вариантов кодировки после создания отправителя.
• Порядок указанных encodings изменился по сравнению с порядком в текущем списке.
• Была предпринята попытка изменить свойство, которое нельзя изменить после первоначального создания отправителя.

InvalidStateError DOMException

Возвращается, если трансивер, частью которого является RTCRtpSender, не работает или не имеет параметров для установки.

OperationError DOMException

Возвращается, если произошла ошибка, которая не соответствует указанным здесь.

RangeError

Возвращается, если значение, указанное для параметра scaleResolutionDownBy, меньше 1.0 — что приведет к масштабированию вверх, а не вниз, что запрещено; или если одно или несколько указанных значений encodings maxFramerate меньше 0.0.

Кроме того, если при конфигурации или доступе к медиа возникает ошибка WebRTC, выбрасывается RTCError с установленным значением errorDetail в hardware-encoder-error.

Важно помнить, что вы не можете создать объект parameters самостоятельно и ожидать, что он будет работать. Вместо этого вы обязательно должны сначала вызвать getParameters(), изменить полученный объект параметров, а затем передать этот объект в setParameters(). WebRTC использует свойство transactionId объекта параметров, чтобы гарантировать, что при установке параметров ваши изменения основаны на самых последних параметрах, а не на устаревшей конфигурации.

Одно из применений setParameters() — это попытка уменьшить использующуюся полосу пропускания сети в ограниченных средах, изменив разрешение и/или битрейт медиа, передаваемого RTCRtpSender.

В настоящее время некоторые браузеры имеют ограничения в своих реализациях, которые могут вызывать проблемы. По этой причине здесь приведены два примера. Первый показывает, как использовать setParameters(), когда все браузеры полностью поддерживают используемые параметры, а второй пример демонстрирует обходные пути для решения ограничений в браузерах с неполной поддержкой параметров maxBitrate и scaleResolutionDownBy.

После того, как все браузеры полностью реализуют спецификацию, эта реализация setVideoParams() сделает свою работу. Это демонстрирует, как должно работать всё. Вам, вероятно, следует использовать второй пример ниже, пока. Но это более наглядная демонстрация основного понятия: сначала извлечь параметры, затем изменить их и затем установить.

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height / height;
  const params = sender.getParameters();

  params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
  params.encodings[0].maxBitrate = bitrate;
  await sender.setParameters(params);
}

При вызове этой функции вы указываете отправителя, а также желаемый масштаб высоты видео отправителя, а также максимальный битрейт для разрешения отправителю передавать данные. Вычисляется коэффициент масштабирования размера видео, scaleRatio. Затем текущие параметры отправителя извлекаются с помощью getParameters().

Затем параметры изменяются путем изменения значения свойства scaleResolutionDownBy и maxBitrate первого объекта encodings на вычисленный коэффициент масштабирования и указанный максимальный bitrate.

Измененные параметры сохраняются путем вызова метода setParameters() отправителя.

Как уже упоминалось выше, предыдущий пример показывает, как всё должно работать. К сожалению, существуют проблемы с реализацией, которые препятствуют этому во многих браузерах прямо сейчас. По этой причине, если вы хотите обеспечить совместимость с iPhone и другими устройствами, работающими на Safari, а также с Firefox, используйте код, более похожий на этот:

async function setVideoParams(sender, height, bitrate) {
  const scaleRatio = sender.track.getSettings().height / height;
  const params = sender.getParameters();

  // If encodings is null, create it

  if (!params.encodings) {
    params.encodings = [{}];
  }

  params.encodings[0].scaleResolutionDownBy = Math.max(scaleRatio, 1);
  params.encodings[0].maxBitrate = bitrate;
  await sender.setParameters(params);

  // If the newly changed value of scaleResolutionDownBy is 1,
  // use applyConstraints() to be sure the height is constrained,
  // since scaleResolutionDownBy may not be implemented

  if (sender.getParameters().encodings[0].scaleResolutionDownBy === 1) {
    await sender.track.applyConstraints({ height });
  }
}

Отличия здесь:

• Если encodings равно null, мы его создаем, чтобы гарантировать, что мы сможем успешно установить параметры без сбоя.
• Если после установки параметров значение scaleResolutionDownBy по-прежнему равно 1, мы вызываем метод applyConstraints() трека отправителя для ограничения высоты трека до height. Это компенсирует нереализованный scaleResolutionDownBy (как это происходит в Safari на данный момент).

Этот код корректно откатится и будет работать обычным образом, если браузер полностью реализует используемые функции.

• API WebRTC
• Кодеки, используемые WebRTC
• Веб-технологии для медиа