Skip to content

Commit 9dc2d35

Browse files
author
Jill Grant
authored
Merge pull request #266219 from jsaurezlee-msft/patch-3
ASC Calling Media Statistics Native SDKs GA
2 parents a2faf80 + a220c5f commit 9dc2d35

File tree

5 files changed

+123
-163
lines changed

5 files changed

+123
-163
lines changed

‎articles/communication-services/concepts/voice-video-calling/includes/media-stats/media-stats-android.md

Lines changed: 36 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -14,77 +14,64 @@ ms.subservice: calling
1414

1515
## Media quality statistics for an ongoing call
1616

17-
Media quality statistics is an extended feature of the core `Call` API. You first need to obtain the `MediaStatsCallFeature` API object:
17+
Media quality statistics is an extended feature of the core `Call` API. You first need to obtain the `MediaStatisticsCallFeature` API object:
1818

1919
```java
20-
MediaStatsCallFeature mediaStatsCallFeature = call.feature(Features.MEDIA_STATS);
20+
MediaStatisticsCallFeature mediaStatisticsCallFeature = call.feature(Features.MEDIA_STATISTICS);
2121
```
2222

23-
The `MediaStatsCallFeature` object has the following API structure:
24-
25-
- The `OnSampleReportedListener` event listens for periodic reports of the media statistics.
26-
- `setSampleIntervalInSeconds(int value)` sets the interval, in seconds, of the media statistics report generation. If it's not specified, the SDK uses defaults.
27-
- A `MediaStatsReport` object contains the definition of the outgoing and incoming media statistics, categorized by audio, video, and screen share.
28-
- `getOutgoingMediaStats()`: The list of media statistics for outgoing media.
29-
- `getAudio()`: The list of media statistics for outgoing audio.
30-
- `getVideo()`: The list of media statistics for outgoing video.
31-
- `getScreenShare()`: The list of media statistics for outgoing screen share.
32-
- `getIncomingStats()`: The list of media statistics for incoming media.
33-
- `getAudio()`: The list of media statistics for incoming audio.
34-
- `getVideo()`: The list of media statistics for the incoming video.
35-
- `getScreenShare()`: The list of media statistics for incoming screen share.
36-
- `getGeneratedAt()`: The date when the report was generated.
37-
- `getIncomingMediaStatsFromParticipant`: Gets the `IncomingMediaStats` value for `RemoteParticipant`.
38-
39-
Then, subscribe to the `addOnSampleReportedListener` event to get regular updates about the current media quality statistics:
23+
The `MediaStatisticsCallFeature` object has the following API structure:
24+
25+
- The `OnReportReceivedListener` event listens for periodic reports of the media statistics.
26+
- `getReportIntervalInSeconds` gets the interval, in seconds, of the media statistics report generation. The SDK uses `10` second as default.
27+
- `updateReportIntervalInSeconds()` updates the interval, in seconds, of the media statistics report generation. The SDK uses `10` second as default.
28+
- A `MediaStatisticsReport` contains the definition of the outgoing and incoming media statistics, categorized by audio, video, and screen share.
29+
- `getOutgoingStatistics()`: The list of media statistics for outgoing media.
30+
- `getAudioStatistics()`: The list of media statistics for outgoing audio.
31+
- `getVideoStatistics()`: The list of media statistics for outgoing video.
32+
- `getScreenShareStatistics()`: The list of media statistics for outgoing screen share.
33+
- `getDataChannelStatistics()`: The list of media statistics for data channel.
34+
- `getIncomingStatistics()`: The list of media statistics for incoming media.
35+
- `getAudioStatistics()`: The list of media statistics for incoming audio.
36+
- `getVideoStatistics()`: The list of media statistics for the incoming video.
37+
- `getScreenShareStatistics()`: The list of media statistics for incoming screen share.
38+
- `getDataChannelStatistics()`: The list of media statistics for data channel.
39+
- `getLastUpdatedAt()`: The date when the report was generated.
40+
41+
Then, subscribe to the `addOnReportReceivedListener` event to get regular updates about the current media quality statistics:
4042

4143
```java
42-
mediaStatsCallFeature.addOnSampleReportedListener(handleSampleReportedListener);
44+
mediaStatisticsCallFeature.addOnReportReceivedListener(handleReportReceivedListener);
4345
// Optionally, set the interval for media statistics report generation
44-
mediaStatsCallFeature.setSampleReportedIntervalInSeconds(15);
46+
mediaStatisticsCallFeature.updateReportIntervalInSeconds(15);
4547

46-
private void handleSampleReportedListener(MediaStatsReportEvent args) {
48+
private void handleReportReceivedListener(MediaStatisticssReportEvent args) {
4749
// Obtain the media statistics report instance
48-
MediaStatsReport report = args.getReport();
50+
MediaStatisticsReport report = args.getReport();
4951

5052
// Obtain the outgoing media statistics for audio
51-
List<OutgoingAudioMediaStats> outgoingAudioMediaStats = report.getOutgoingMediaStats().getAudio();
53+
List<OutgoingAudioStatistics> outgoingAudioStatistics = report.getOutgoingStatistics().getAudioStatistics();
5254

5355
// Obtain the outgoing media statistics for video
54-
List<OutgoingVideoMediaStats> outgoingVideoMediaStats = report.getOutgoingMediaStats().getVideo();
56+
List<OutgoingVideoStatistics> outgoingVideoStatistics = report.getOutgoingStatistics().getVideoStatistics();
5557

5658
// Obtain the outgoing media statistics for screen share
57-
List<OutgoingScreenShareMediaStats> outgoingScreenShareMediaStats = report.getOutgoingMediaStats().getScreenShare();
59+
List<OutgoingScreenShareStatistics> outgoingScreenShareStatistics = report.getOutgoingStatistics().getScreenShareStatistics();
60+
61+
// Obtain the outgoing media statistics for data channel
62+
List<OutgoingDataChannelStatistics> outgoingDataChannelStatistics = report.getOutgoingStatistics().getDataChannelStatistics();
5863

5964
// Obtain the incoming media statistics for audio
60-
List<IncomingAudioMediaStats> incomingAudioMediaStats = report.getIncomingMediaStats().getAudio();
65+
List<IncomingAudioStatistics> incomingAudioStatistics = report.getIncomingStatistics().getAudioStatistics();
6166

6267
// Obtain the incoming media statistics for video
63-
List<IncomingVideoMediaStats> incomingVideoMediaStats = report.getIncomingMediaStats().getVideo();
68+
List<IncomingVideoStatistics> incomingVideoStatistics = report.getIncomingStatistics().getVideoStatistics();
6469

6570
// Obtain the incoming media statistics for screen share
66-
List<IncomingScreenShareMediaStats> incomingScreenShareMediaStats = report.getIncomingMediaStats().getScreenShare();
67-
}
68-
```
69-
70-
Also, `MediaStatsReport` has a helper method to obtain the `IncomingMediaStats` value for a particular `RemoteParticipant` instance.
71-
For example, to get the `IncomingMediaStats` value for all the remote participants in the call, you can use:
71+
List<IncomingScreenShareStatistics> incomingScreenShareStatistics = report.getIncomingStatistics().getScreenShareStatistics();
7272

73-
```java
74-
private void handleSampleReportedListener(MediaStatsReportEvent args) {
75-
List<RemoteParticipant> remoteParticipants = call.getRemoteParticipants();
76-
for (RemoteParticipant remoteParticipant : remoteParticipants) {
77-
{
78-
IncomingMediaStatsInfo incomingMediaStatsInfo = report.getIncomingMediaStatsFromParticipant(remoteParticipant.getIdentifier());
79-
// Obtain the incoming media statistics for audio
80-
List<IncomingAudioMediaStats> incomingAudioMediaStats = incomingMediaStatsInfo.getAudio();
81-
82-
// Obtain the incoming media statistics for video
83-
List<IncomingVideoMediaStats> incomingVideoMediaStats = incomingMediaStatsInfo.getVideo();
84-
85-
// Obtain the incoming media statistics for screen share
86-
List<IncomingScreenShareMediaStats> incomingScreenShareMediaStats = incomingMediaStatsInfo.getScreenShare();
87-
}
73+
// Obtain the incoming media statistics for data channel
74+
List<IncomingDataChannelStatistics> incomingDataChannelStatistics = report.getIncomingStatistics().getDataChannelStatistics();
8875
}
8976
```
9077

‎articles/communication-services/concepts/voice-video-calling/includes/media-stats/media-stats-ios.md

Lines changed: 29 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -14,83 +14,67 @@ ms.subservice: calling
1414

1515
## Media quality statistics for an ongoing call
1616

17-
Media quality statistics is an extended feature of the core `Call` API. You first need to obtain the `mediaStatsCallFeature` API object:
17+
Media quality statistics is an extended feature of the core `Call` API. You first need to obtain the `mediaStatisticsCallFeature` API object:
1818

1919
```swift
20-
var mediaStatsCallFeature = self.call?.feature(Features.mediaStats)
20+
var mediaStatisticsCallFeature = self.call.feature(Features.mediaStatistics)
2121
```
2222

23-
The `mediaStatsCallFeature` object has the following API structure:
23+
The `mediaStatisticsCallFeature` object has the following API structure:
2424

25-
- The `didReceiveSample` delegate method listens for periodic reports of the media statistics.
26-
- `sampleIntervalInSeconds` gets and sets the interval, in seconds, of the media statistics report generation. If it's not specified, the SDK uses defaults.
27-
- A `MediaStatsReport` object contains the definition of the outgoing and incoming media statistics, categorized by audio, video, and screen share.
28-
- `OutgoingMediaStats`: The list of media statistics for outgoing media.
25+
- The `didReceiveReport` delegate method listens for periodic reports of the media statistics.
26+
- `reportIntervalInSeconds` gets the interval, in seconds, of the media statistics report generation. The SDK uses `10` second as default.
27+
- `updateReportInterval(inSeconds)` updates the interval, in seconds, of the media statistics report generation. The SDK uses `10` second as default.
28+
- A `MediaStatisticsReport` object contains the definition of the outgoing and incoming media statistics, categorized by audio, video, and screen share.
29+
- `outgoingMediaStatistics`: The list of media statistics for outgoing media.
2930
- `audio`: The list of media statistics for the outgoing audio.
3031
- `video`: The list of media statistics for the outgoing video.
3132
- `screenShare`: The list of media statistics for the outgoing screen share.
32-
- `OncomingStats`: The list of media statistics for incoming media.
33+
- `dataChannel`: The list of media statistics for the outgoing data channel.
34+
- `incomingMediaStatistics`: The list of media statistics for incoming media.
3335
- `audio`: The list of media statistics for the incoming audio.
3436
- `video`: The list of media statistics for the incoming video.
3537
- `screenShare`: The list of media statistics for the incoming screen share.
36-
- `generatedAt`: The date when the report was generated.
37-
- `incomingMediaStats`: Gets the `IncomingMediaStats` value for `RemoteParticipant`.
38+
- `dataChannel`: The list of media statistics for the incoming data channel.
39+
- `lastUpdated`: The date when the report was generated.
3840

39-
Then, subscribe to the `SampleReported` event to get regular updates about the current media quality statistics:
41+
Then, implement the `didReceiveReport` delegate to get regular updates about the current media quality statistics:
4042

4143
```swift
4244
// Optionally, set the interval for media statistics report generation
43-
mediaStatsCallFeature.sampleIntervalInSeconds = 15
44-
mediaStatsCallFeature.delegate = MediaStatsDelegate()
45+
mediaStatisticsCallFeature.updateReportInterval(inSeconds: 15)
46+
mediaStatisticsCallFeature.delegate = MediaStatisticsDelegate()
4547

4648

47-
public class MediaStatsDelegate : MediaStatsCallFeatureDelegate
49+
public class MediaStatisticsDelegate : MediaStatisticsCallFeatureDelegate
4850
{
49-
public func mediaStatsCallFeature(_ mediaStatsCallFeature: MediaStatsCallFeature, didReceiveSample args: MediaStatsReportEventArgs) {
51+
public func mediaStatisticsCallFeature(_ mediaStatisticsCallFeature: MediaStatisticsCallFeature,
52+
didReceiveReport args: MediaStatisticsReportReceivedEventArgs) {
5053
let report = args.report
5154

5255
// Obtain the outgoing media statistics for audio
53-
let outgoingAudioMediaStats = report.outgoingMediaStats.audio
56+
let outgoingAudioStatistics = report.outgoingStatistics.audio
5457

5558
// Obtain the outgoing media statistics for video
56-
let outgoingVideoMediaStats = report.outgoingMediaStats.video
59+
let outgoingVideoStatistics = report.outgoingStatistics.video
5760

5861
// Obtain the outgoing media statistics for screen share
59-
let outgoingScreenShareMediaStats = report.outgoingMediaStats.screenShare
62+
let outgoingScreenShareStatistics = report.outgoingStatistics.screenShare
63+
64+
// Obtain the outgoing media statistics for data channel
65+
let outgoingDataChannelStatistics = report.outgoingStatistics.dataChannel
6066

6167
// Obtain the incoming media statistics for audio
62-
let incomingAudioMediaStats = report.incomingMediaStats.audio
68+
let incomingAudioStatistics = report.incomingStatistics.audio
6369

6470
// Obtain the incoming media statistics for video
65-
let incomingVideoMediaStats = report.incomingMediaStats.video
71+
let incomingVideoStatistics = report.incomingStatistics.video
6672

6773
// Obtain the incoming media statistics for screen share
68-
let incomingScreenShareMediaStats = report.incomingMediaStats.screenShare
69-
}
70-
}
71-
```
72-
73-
Also, `MediaStatsReport` has a helper method to obtain the `IncomingMediaStats` value for a particular `RemoteParticipant` instance.
74-
For example, to get the `IncomingMediaStats` value for all the remote participants in the call, you can use:
75-
76-
```swift
77-
public class MediaStatsDelegate : MediaStatsCallFeatureDelegate
78-
{
79-
public func mediaStatsCallFeature(_ mediaStatsCallFeature: MediaStatsCallFeature, didReceiveSample args: MediaStatsReportEventArgs) {
80-
let report = args.report
81-
82-
call.remoteParticipants.forEach{ remoteParticipant in
83-
let remoteIncomingMediaStats = report.incomingMediaStats(fromParticipant: remoteParticipant.identifier)
74+
let incomingScreenShareStatistics = report.incomingStatistics.screenShare
8475

85-
// Obtain the incoming media statistics for audio
86-
let incomingAudioMediaStats = remoteIncomingMediaStats.audio
87-
88-
// Obtain the incoming media statistics for video
89-
let incomingVideoMediaStats = remoteIncomingMediaStats.video
90-
91-
// Obtain the incoming media statistics for screen share
92-
let incomingScreenShareMediaStats = remoteIncomingMediaStats.screenShare
93-
}
76+
// Obtain the incoming media statistics for data channel
77+
let incomingDataChannelStatistics = report.incomingStatistics.dataChannel
9478
}
9579
}
9680
```

‎articles/communication-services/concepts/voice-video-calling/includes/media-stats/media-stats-native-metrics.md

Lines changed: 31 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -14,64 +14,69 @@ ms.subservice: calling
1414

1515
## Best practices
1616

17-
If you want to collect the data for offline inspection, we recommend that you collect the data and send it to your pipeline ingestion after your call ends. If you transmit the data during a call, it could use internet bandwidth that's needed to continue an Azure Communication Services call (especially when available bandwidth is low).
17+
If you want to collect the data for offline inspection, we recommend that you collect the data and send it to your pipeline ingestion after your call ends. If you transmit the data during a call, it could use internet bandwidth needed to continue an Azure Communication Services call (especially when available bandwidth is low).
1818

1919
### Outgoing audio metrics
2020

2121
| Metric name | Description | Comments |
2222
| ----------- | ----------- | -------- |
2323
| `CodecName` | Codec name | |
24-
| `Bitrate` | Audio send bitrate (bits per second) | General values are in the 24-Kbps range (36-128 Kbps is typical). |
24+
| `BitrateInBps` | Audio send bitrate (bits per second) | General values are in the 24-Kbps range (36-128 Kbps is typical). |
2525
| `JitterInMs` | Packet jitter (milliseconds) | Lower is better. |
26-
| `PacketsPerSecond` | Packet rate (packets per second) | |
27-
| `RoundTripTimeInMs` | Round-trip time (milliseconds) | Lower is better. It's calculated from the RTCP receiver report. We recommend a round-trip time of 200 ms or less. |
28-
| `AvailableBitrate` | Bandwidth estimation (bits per second) | |
26+
| `PacketCount` | The total number of packets sent. | |
2927

3028
### Incoming audio metrics
3129

3230
| Metric name | Description | Comments |
3331
| ----------- | ----------- | -------- |
3432
| `CodecName` | Codec name | |
3533
| `JitterInMs` | Packet jitter (milliseconds) | Lower is better. |
36-
| `PacketsPerSecond` | Packet rate (packets per second) | |
34+
| `PacketCount` | The total number of packets sent. | |
3735
| `PacketsLostPerSecond` | Packet loss rate (packets per second) | Lower is better. |
3836

3937
### Outgoing video metrics
4038

4139
| Metric name | Description | Comments |
4240
| ----------- | ----------- | -------- |
4341
| `CodecName` | Codec name | |
44-
| `Bitrate` | Video send bitrate (bits per second) | |
45-
| `PacketsPerSecond` | Packet rate (packets per second) | |
46-
| `PacketsLostPerSecond` | Packet loss rate (packets per second) | Lower is better. |
47-
| `RoundTripTimeInMs` | Round-trip time (milliseconds) | Lower is better. It's calculated from the RTCP receiver report. We recommend a round-trip time of 200 ms or less. |
48-
| `AvailableBitrate` | Bandwidth estimation (bits per second) | We recommend 1.5 Mbps or higher for high-quality video for upload/download. |
49-
| `FrameRateInput` | Frame rate that originates from the video source (frames per second) | |
50-
| `FrameWidthInput` | Frame width of the last frame that originates from the video source (pixels) | |
51-
| `FrameHeightInput` | Frame height of the last frame that originates from the video source (pixels) | |
52-
| `FrameRateSent` | Frame rate sent on the RTP stream (frames per second) | |
53-
| `FrameWidthSent` | Frame width of the encoded frame (pixels) | |
54-
| `FrameHeightSent` | Frame height of the encoded frame (pixels) | |
42+
| `BitrateInBps` | Video send bitrate (bits per second) | |
43+
| `PacketCount` | The total number of packets sent. | |
44+
| `FrameRate` | Frame rate sent on the RTP stream (frames per second) | |
45+
| `FrameWidth` | Frame width of the encoded frame (pixels) | |
46+
| `FrameHeight` | Frame height of the encoded frame (pixels) | |
5547

5648
### Incoming video metrics
5749

5850
| Metric name | Description | Comments |
5951
| ----------- | ----------- | -------- |
6052
| `CodecName` | Codec name | |
61-
| `Bitrate` | Video receive bitrate (bits per second) | |
53+
| `BitrateInBps` | Video receive bitrate (bits per second) | |
6254
| `JitterInMs` | Packet jitter (milliseconds) | Lower is better. |
63-
| `PacketsPerSecond` | Packet rate (packets per second) | |
55+
| `PacketCount` | The total number of packets sent. | |
6456
| `PacketsLostPerSecond` | Packet loss rate (packets per second) | Lower is better. |
6557
| `StreamId` | Stream ID | The `streamId` value corresponds to the ID of the video of the remote participant. It can be used to match the sender. |
66-
| `FrameRateReceived` | Frame rate received on the RTP stream (frames per second) | |
67-
| `FrameWidthReceived` | Frame width of the decoded frame (pixels) | |
68-
| `FrameHeightReceived` | Frame height of the decoded frame (pixels) | |
58+
| `FrameRate` | Frame rate received on the RTP stream (frames per second) | |
59+
| `FrameWidth` | Frame width of the decoded frame (pixels) | |
60+
| `FrameHeight` | Frame height of the decoded frame (pixels) | |
6961
| `TotalFreezeDurationInMs` | Total freeze duration (milliseconds) | |
7062

71-
### Screen-share send metrics
63+
### Outgoing screen share metrics
64+
65+
Currently, statistics fields are the same as *Outgoing video metrics*.
66+
67+
### Incoming screen share metrics
68+
69+
Currently, statistics fields are the same as *Incoming video metrics*.
70+
71+
### Outgoing data channel metrics
7272

73-
Currently, statistics fields are the same as *video send metrics*.
73+
| Metric name | Description | Comments |
74+
| ----------- | ----------- | -------- |
75+
| `PacketCount` | The total number of packets sent. | |
7476

75-
### Screen-share receive metrics
77+
### Incoming data channel metrics
7678

77-
Currently, statistics fields are the same as *video receive metrics*.
79+
| Metric name | Description | Comments |
80+
| ----------- | ----------- | -------- |
81+
| `JitterInMs` | Packet jitter (milliseconds) | Lower is better. |
82+
| `PacketCount` | The total number of packets sent. | |

0 commit comments

Comments
 (0)