이 페이지는 Cloud Translation API를 통해 번역되었습니다.

WebRTC: 기존 getStats() 이전 가이드

Henrik Boström

기존 getStats() WebRTC API는 Chrome 117에서 삭제되므로 이를 사용하는 앱은 표준 API로 이전해야 합니다. 이 도움말에서는 코드를 이전하는 방법과 변경하는 데 시간이 더 필요한 경우 취해야 할 조치를 설명합니다.

이전에는 WebRTC getStats() API의 두 가지 버전이 경쟁했습니다. 표준화 프로세스 이전에 만들어졌으며 콜백 인수를 사용하는 기존 getStats() API와 프라미스를 반환하는 표준화되고 광범위하게 지원되는 API가 있습니다.

표준 API는 기능이 더 풍부하며 W3C 사양 WebRTC의 통계 API 식별자에 공개적으로 문서화된 잘 정의된 측정항목이 있습니다. 사양에는 이 가이드에 나열된 각 측정항목에 대한 설명 등이 포함되어 있습니다.

Chrome 117부터 기존 getStats() API가 안정화 버전 채널에서 예외를 발생시킵니다 (예외 발생은 점진적으로 출시됨). 이 가이드를 따라 표준 API로 원활하게 전환하세요.

참고: 별도의 탭에서 chrome://webrtc-internals/로 이동한 다음 드롭다운 표를 사용하여 기존 또는 표준 측정항목을 선택하면 앱이 실행되는 동안 기존 측정항목과 표준 측정항목을 실시간으로 비교할 수 있습니다.

기존 통계 유형과 표준 통계 유형 비교

표준 통계 유형의 전체 목록은 사양의 RTCStatsType enum을 참고하세요. 여기에는 각 유형에 대해 수집된 측정항목을 설명하는 통계 사전 정의가 포함됩니다.

통계 객체에는 모두 여러 getStats() 호출에서 기본 객체를 고유하게 식별하는 id 속성이 있습니다. 메서드가 호출될 때마다 동일한 객체에 동일한 ID가 할당됩니다. 이는 측정항목의 변동률을 계산하는 데 유용합니다 (다음 섹션에 예시가 있음). ID는 참조 관계도 형성합니다. 예를 들어 outbound-rtp 통계 객체는 outbound-rtp.mediaSourceId 속성을 통해 연결된 media-source 통계 객체를 참조합니다. 모든 ...Id 관계를 그리면 그래프가 생성됩니다.

기존 API에는 다음과 같이 표준 유형에 해당하는 다음과 같은 통계 유형이 있습니다.

기존 유형	표준 유형
`ssrc`	연결된 `MediaStreamTrack`에 관한 RTP 스트림 및 측정항목을 나타냅니다. 이러한 측정항목의 표준 유형은 `inbound-rtp` (수신 RTP 스트림 및 연결된 원격 `MediaStreamTrack`의 경우), `outbound-rtp` (전송 RTP 스트림의 경우), `media-source` (전송 RTP 스트림과 연결된 로컬 `MediaStreamTrack` 측정항목의 경우)입니다. RTP 스트림 측정항목에는 RTP 스트림에서 사용하는 인코더 또는 디코더에 관한 정보도 포함됩니다.
`VideoBwe`	대역폭 추정 측정항목, 타겟 비트 전송률, 인코더 비트 전송률, 실제 비트 전송률 이러한 유형의 측정항목은 RTP 측정항목 (`outbound-rtp` 및 `inbound-rtp`) 및 ICE 후보 쌍 측정항목 (`candidate-pair`)의 일부입니다.
`googComponent`	전송 (ICE 및 DTLS)을 나타냅니다. 표준 버전은 `transport`입니다.
`localcandidate and remotecandidate`	ICE 후보를 나타냅니다. 표준 버전은 `local-candidate` 및 `remote-candidate`입니다.
`googCandidatePair`	로컬 후보와 원격 후보의 페어링인 ICE 후보 쌍을 나타냅니다. 표준 버전은 `candidate-pair`입니다.
`googCertificate`	DTLS 전송에서 사용하는 인증서를 나타냅니다. 표준 버전은 `certificate`입니다.
`googLibjingleSession`	`RTCPeerConnection`를 나타냅니다. 콘텐츠는 표준의 아무것도 매핑하지 않지만 표준에는 `RTCPeerConnection`와 연결된 유형(`peer-connection`)이 있습니다.
기존 API에 없음	다음 통계 유형은 상응하는 기존 유형이 없는 표준 API에 추가되었습니다. `codec`: 현재 RTP 스트림에서 인코딩 또는 디코딩에 사용 중인 코덱입니다. 이는 SDP에서 협상된 코덱의 하위 집합입니다. `remote-inbound-rtp`: 이 엔드포인트에서 전송하는 아웃바운드 RTP 스트림 (`outbound-rtp`)에 해당하는 원격 엔드포인트의 인바운드 RTP 스트림입니다. 원격 엔드포인트에서 측정되며 RTCP 수신기 보고서 (RR) 또는 RTCP 확장 보고서 (XR)에 보고됩니다. `remote-outbound-rtp`: 이 엔드포인트에서 수신하는 인바운드 RTP 스트림 (`inbound-rtp`)에 해당하는 원격 엔드포인트의 아웃바운드 RTP 스트림입니다. 원격 엔드포인트에서 측정되며 RTCP Sender Report (SR)에 보고됩니다. `media-playout`: 수신 RTP 스트림 (`inbound-rtp`)과 연결된 원격 `MediaStreamTrack`의 재생에 관한 측정항목입니다. `data-channel`: `RTCDataChannel`를 나타냅니다.

기존 측정항목과 표준 측정항목 매핑

이 매핑은 개발자가 어떤 기존 측정항목이 어떤 표준 측정항목과 일치하는지 찾는 데 도움이 되도록 고안되었지만, 상응하는 측정항목이 다른 단위를 사용하거나 순간 값이 아닌 총계 카운터로 표현될 수 있습니다. 측정항목 정의는 사양을 참고하세요.
표준 API는 비율이 아닌 총 카운터를 노출하는 것을 선호합니다. 즉, 기존 API와 같이 상응하는 비율 (예: 비트 전송률)을 가져오려면 앱이 두 개의 getStats() 호출 간의 차이를 사용하여 평균 비율을 계산해야 합니다. 예를 들면 다음과 같습니다.

// Periodically (e.g. every second or every 10 seconds)...
const currReport = await pc.getStats();
// Calculate bitrate since the last getStats() call.
// Handling of undefined is omitted for clarity.
const currOutboundRtp = currReport.values().find(s => s.type == 'outbound-rtp');
const prevOutboundRtp = prevReport.get(currOutboundRtp.id);
const deltaBits = (currOutboundRtp.bytesSent - prevOutboundRtp.bytesSent) * 8;
const deltaSeconds = (currOutboundRtp.timestamp - prevOutboundRtp.timestamp) / 1000;
logBitrateMeasurement(deltaBits / deltaSeconds);
// Remember the report for next time.
prevReport = currReport;

이렇게 비율과 평균을 직접 계산하는 것은 번거로운 추가 단계처럼 보일 수 있지만 원하는 시간 간격에 대한 평균을 얻을 수 있다는 장점이 있습니다. 기존 API를 사용해야 하는 것보다 표준 API를 덜 자주 호출하면 성능상의 이점이 있습니다.

기존 측정항목 `googCertificate`	표준 서신 `certificate`
`.googFingerprint`	`.fingerprint`
`.googFingerprintAlgorithm`	`.fingerprintAlgorithm`
`.googDerBase64`	`.base64Certificate`

기존 측정항목 `googComponent`	표준 서신 `transport`
`.localCertificateId`	`.localCertificateId`
`.remoteCertificateId`	`.remoteCertificateId`
`.selectedCandidatePairId`	`.selectedCandidatePairId`
`.dtlsCipher`	`.dtlsCipher`
`.srtpCipher`	`.srtpCipher`

기존 측정항목 `localcandidate`	표준 서신 `local-candidate` 또는 `candidate-pair`
`.stunKeepaliveRequestsSent`	`candidate-pair.requestsSent` (`candidate-pair.localCandidateId`를 통한 역조회 `candidate-pair`)
`.portNumber`	`local-candidate.port`
`.networkType`	`local-candidate.networkType`
`.ipAddress`	`local-candidate.address`
`.stunKeepaliveResponsesReceived`	`candidate-pair.responsesReceived`
`.stunKeepaliveRttTotal`	`candidate-pair.totalRoundTripTime`
`.transport`	`local-candidate.protocol`
`.candidateType`	`local-candidate.candidateType`
`.priority`	`local-candidate.priority`

기존 측정항목 `remotecandidate`	표준 서신 `remote-candidate`
위의 `localcandidate`와 동일합니다.	위의 `local-candidate`와 동일합니다.

기존 측정항목 `googCandidatePair`	표준 서신 `candidate-pair`
`.responsesSent`	`candidate-pair.responsesSent`
`.requestsReceived`	`candidate-pair.requestsReceived`
`.googRemoteCandidateType`	`remote-candidate.candidateType` ( `candidate-pair.remoteCandidateId`를 통해 `remote-candidate` 조회)
`.googReadable`	`googReadable`는 최근에 `candidate-pair.requestsReceived` 또는 `candidate-pair.responsesReceived`를 증분했는지 여부를 반영하는 불리언입니다.
`.googLocalAddress`	`local-candidate.address` ( `candidate-pair.localCandidateId`를 통해 `local-candidate` 조회)
`.consentRequestsSent`	`candidate-pair.consentRequestsSent`
`.googTransportType`	`local-candidate.protocol` 및 `remote-candidate.protocol`와 동일합니다.
`.googChannelId`	`candidate-pair.transportId`
`.googLocalCandidateType`	`local-candidate.candidateType`
`.googWritable`	`googWritable`는 최근에 `candidate-pair.responsesReceived`을 증분했는지 여부를 반영하는 불리언입니다.
`.googRemoteAddress`	`remote-candidate.address`
`.googRtt`	`candidate-pair.currentRoundTripTime`
`.googActiveConnection`	활성 연결은 현재 전송에서 선택한 후보 쌍을 나타냅니다(예: `candidate-pair.id == transport.selectedCandidatePairId`
`.packetsDiscardedOnSend`	`candidate-pair.packetsDiscardedOnSend`
`.bytesReceived`	`candidate-pair.bytesReceived`
`.responsesReceived`	`candidate-pair.responsesReceived`
`.remoteCandidateId`	`candidate-pair.remoteCandidateId`
`.localCandidateId`	`candidate-pair.localCandidateId`
`.bytesSent`	`candidate-pair.bytesSent`
`.packetsSent`	`candidate-pair.packetsSent`
`.bytesReceived`	`candidate-pair.bytesReceived`
`.bytesReceived`	`candidate-pair.bytesReceived`

기존 측정항목 `ssrc`	표준 상응 `inbound-rtp`, `outbound-rtp`, `media-source`
`.audioInputLevel`	`media-source.audioLevel`. 기존 측정항목은 [0..32768] 범위이지만 표준 측정항목은 [0..1] 범위입니다.
`.audioOutputLevel`	`inbound-rtp.audioLevel`. 기존 측정항목은 [0..32768] 범위이지만 표준 측정항목은 [0..1] 범위입니다.
`.packetsLost`	`inbound-rtp.packetsLost`
`.googTrackId`	로컬 `MediaStreamTrack`의 경우 `media-source.trackIdentifier`, 원격 `MediaStreamTrack`의 경우 `inbound-rtp.trackIdentifier`
`.googRtt`	`remote-inbound-rtp.roundTripTime` (`outbound-rtp.remoteId` 참고)
`.googEchoCancellationReturnLossEnhancement`	`inbound-rtp.echoReturnLossEnhancement`
`.googCodecName`	코덱 이름은 'type/subtype' MIME 유형 `codec.mimeType`의 하위유형입니다 (`inbound-rtp.codecId` 및 `outbound-rtp.codecId` 참고).
`.transportId`	`inbound-rtp.transportId` 및 `outbound-rtp.transportId`
`.mediaType`	`inbound-rtp.kind` 및 `outbound-rtp.kind` 또는 `media-source.kind`
`.googEchoCancellationReturnLoss`	`inbound-rtp.echoReturnLoss`
`.totalAudioEnergy`	`inbound-rtp.totalAudioEnergy` 및 `media-source.totalAudioEnergy`
`ssrc.totalSamplesDuration`	`inbound-rtp.totalSamplesDuration` 및 `media-source.totalSamplesDuration`
`.ssrc`	`inbound-rtp.ssrc` 및 `outbound-rtp.ssrc`
`.googJitterReceived`	`inbound-rtp.jitter`
`.packetsSent`	`outbound-rtp.packetsSent`
`.bytesSent`	`outbound-rtp.bytesSent`
`.googContentType`	`inbound-rtp.contentType` 및 `outbound-rtp.contentType`
`.googFrameWidthInput`	`media-source.width`
`.googFrameHeightInput`	`media-source.height`
`.googFrameRateInput`	`media-source.framesPerSecond`
`.googFrameWidthSent`	`outbound-rtp.frameWidth`
`.googFrameHeightSent`	`outbound-rtp.frameHeight`
`.googFrameRateSent`	전송 FPS는 `outbound-rtp.framesSent`의 변화율이지만 실제로는 FPS를 인코딩하는 `outbound-rtp.framesPerSecond`로 구현됩니다.
`.googFrameWidthReceived`	`inbound-rtp.frameWidth`
`.googFrameHeightReceived`	`inbound-rtp.frameHeight`
`.googFrameRateDecoded`	`inbound-rtp.framesDecoded`의 변화율
`.googFrameRateOutput`	`inbound-rtp.framesDecoded` - `inbound-rtp.framesDropped`의 변화율
`.hugeFramesSent`	`outbound-rtp.hugeFramesSent`
`.qpSum`	`inbound-rtp.qpSum` 및 `outbound-rtp.qpSum`
`.framesEncoded`	`outbound-rtp.framesEncoded`
`.googAvgEncodeMs`	`outbound-rtp.totalEncodeTime`/`outbound-rtp.framesEncoded`
`.codecImplementationName`	`inbound-rtp.decoderImplementation` 및 `outbound-rtp.encoderImplementation`
`.googCpuLimitedResolution`	`outbound-rtp.qualityLimitationReason == "cpu"`인 경우 True
`.googBandwidthLimitedResolution`	`outbound-rtp.qualityLimitationReason == "bandwidth"`인 경우 True
`.googAdaptationChanges`	기존 측정항목은 `qualityLimitationReason` 관련 이유로 해상도 또는 프레임 속도가 변경된 횟수를 집계합니다. 이는 다른 측정항목(예: 전송 해상도 또는 프레임 속도가 소스 해상도 또는 프레임 속도와 다름)에서 추론할 수 있지만, 제한된 기간(`outbound-rtp.qualityLimitationDurations`)은 해상도 또는 프레임 속도가 변경된 빈도보다 더 유용할 수 있습니다.
`.googNacksReceived`	`inbound-rtp.nackCount`
`.googNacksSent`	`inbound-rtp.nackCount`
`.googPlisReceived`	`inbound-rtp.pliCount`
`.googPlisSent`	`inbound-rtp.pliCount`
`.googFirsReceived`	`inbound-rtp.firCount`
`.googFirsSent`	`inbound-rtp.firCount`
`.googSecondaryDecodedRate`	오류 수정이 포함된 패킷의 최근 비율: `inbound-rtp.fecPacketsReceived` - `inbound-rtp.fecPacketsDiscarded`
`.packetsReceived`	`inbound-rtp.packetsReceived`
`.googJitterBufferMs`	`inbound-rtp.jitterBufferDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googTargetDelayMs` (동영상)	`inbound-rtp.jitterBufferTargetDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googPreferredJitterBufferMs` (오디오)	`inbound-rtp.jitterBufferTargetDelay`/`inbound-rtp.jitterBufferEmittedCount`
`.googExpandRate`	최근 숨겨진 샘플의 비율: `inbound-rtp.concealedSamples` / `inbound-rtp.totalSamplesReceived`
`.googSpeechExpandRate`	스트림이 무음 상태가 아니었던 동안 숨겨진 샘플의 최근 비율입니다. (`inbound-rtp.concealedSamples` - `inbound-rtp.silentConcealedSamples`) / `inbound-rtp.concealedSamples`
`.googAccelerateRate`	재생 속도를 높이기 위해 삭제된 최근 샘플의 비율입니다(`inbound-rtp.removedSamplesForAcceleration` / `inbound-rtp.totalSamplesReceived`).
`.googPreemptiveExpandRate`	재생 속도를 감속하기 위해 합성된 최근 샘플의 비율입니다(`inbound-rtp.insertedSamplesForDeceleration` / `inbound-rtp.totalSamplesReceived`).
`.googSecondaryDiscardedRate`	`inbound-rtp.fecPacketsDiscarded`
`.bytesReceived`	`inbound-rtp.bytesReceived`
`s.googCurrentDelayMs`	`inbound-rtp.jitterBufferDelay` + media-playout.totalPlayoutDelay
`.googDecodeMs`	`inbound-rtp.totalDecodeTime`/`inbound-rtp.framesDecoded`
`.googTimingFrameInfo`	남은 유일한 goog 측정항목입니다. `inbound-rtp.googTimingFrameInfo`
`.framesDecoded`	`inbound-rtp.framesDecoded`

기존 측정항목 `VideoBwe`	표준 서신 `outbound-rtp` 및 `candidate-pair`
`.googTargetEncBitrate`	`outbound-rtp.targetBitrate`(순간 값) 또는 `outbound-rtp.totalEncodedBytesTarget` / `outbound-rtp.framesEncoded`(평균)
`.googActualEncBitrate`	인코더에서 생성된 바이트는 재전송을 제외한 페이로드 바이트입니다. `outbound-rtp.bytesSent` - `outbound-rtp.retransmittedBytesSent`의 변화율입니다.
`.googBucketDelay`	`outbound-rtp.totalPacketSendDelay`/`outbound-rtp.packetsSent`
`.googTransmitBitrate`	RTP 스트림 비트 전송률당 `outbound-rtp.headerBytesSent` + `outbound-rtp.bytesSent`, ICE 후보 비트 전송률당 `candidate-pair.bytesSent` 또는 전송 비트 전송률당 `transport.bytesSent`의 변화율
`.googRetransmitBitrate`	`outbound-rtp.retransmittedBytesSent`의 변화 범위
`.googAvailableSendBandwidth`	`candidate-pair.availableOutgoingBitrate`
`.googAvailableReceiveBandwidth`	`candidate-pair.availableIncomingBitrate`

표준 API는 멀티캐스트를 인식합니다.

멀티캐스트를 사용하는 경우 멀티캐스트를 사용하여 세 개의 개별 SSRC를 통해 세 개의 RTP 스트림을 전송하는 경우에도 기존 API가 단일 SSRC만 보고한다는 점에 유의하세요.

표준 API는 이 제한사항을 공유하지 않으며 SSRC마다 하나씩 세 개의 outbound-rtp 통계 객체를 반환합니다. 즉, 각 RTP 스트림을 개별적으로 분석할 수 있지만 모든 RTP 전송 스트림의 총 비트 전송률을 얻으려면 직접 집계해야 합니다.

반면 scalabilityMode API를 통해 구성된 여러 공간 레이어가 있는 SVC 스트림 또는 RTP 스트림은 단일 SSRC를 통해 전송되므로 여전히 단일 outbound-rtp로 표시됩니다.

이전에 시간이 더 필요한 경우

Chrome 117에서 기존 API가 삭제되면 이를 사용하면 예외가 발생합니다. 코드를 제때 이전할 수 없는 경우 RTCPeerConnection 콜백 기반 getStats() API의 출처 체험판을 사용하면 등록된 웹사이트에서 이전하는 데 더 많은 시간을 확보할 수 있습니다. 출처 체험판 토큰을 사용하면 기존 getStats() API를 Chrome 121까지 계속 사용할 수 있습니다.