{"id":13528263,"url":"https://github.com/VLprojects/webrtc-issue-detector","last_synced_at":"2025-04-01T11:31:13.634Z","repository":{"id":56816749,"uuid":"524857000","full_name":"VLprojects/webrtc-issue-detector","owner":"VLprojects","description":"Diagnostic tool and troubleshooter for WebRTC applications with Mean Opinion Score (MOS) calculator","archived":false,"fork":false,"pushed_at":"2025-02-07T10:47:30.000Z","size":255,"stargazers_count":97,"open_issues_count":2,"forks_count":16,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-04T01:11:51.620Z","etag":null,"topics":["client-library","issue","javascipt","mos","network","rtcpeerconnection","troubleshooting","typescipt","webrtc","webrtc-libraries","webrtc-stats","webrtc-tools"],"latest_commit_sha":null,"homepage":"https://github.com/VLprojects/webrtc-issue-detector/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VLprojects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-15T04:41:14.000Z","updated_at":"2025-02-20T21:45:33.000Z","dependencies_parsed_at":"2024-01-13T22:23:18.216Z","dependency_job_id":"5e2e765d-3544-49b9-8536-f4746c43764e","html_url":"https://github.com/VLprojects/webrtc-issue-detector","commit_stats":{"total_commits":25,"total_committers":5,"mean_commits":5.0,"dds":0.64,"last_synced_commit":"2daeb9dc512e83ebe1275e081c65d0a37c54ca1f"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VLprojects%2Fwebrtc-issue-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VLprojects%2Fwebrtc-issue-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VLprojects%2Fwebrtc-issue-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VLprojects%2Fwebrtc-issue-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VLprojects","download_url":"https://codeload.github.com/VLprojects/webrtc-issue-detector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246631813,"owners_count":20808762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-library","issue","javascipt","mos","network","rtcpeerconnection","troubleshooting","typescipt","webrtc","webrtc-libraries","webrtc-stats","webrtc-tools"],"created_at":"2024-08-01T06:02:22.084Z","updated_at":"2025-04-01T11:31:13.628Z","avatar_url":"https://github.com/VLprojects.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Libraries"],"sub_categories":["JavaScript"],"readme":"# webrtc-issue-detector\n\nDiagnostic tool for WebRTC JS applications that analyzes WebRTC getStats() result in realtime and generates a report on possible issues.\n\n\n## Key features\n\n- **Mean opinion score** - calculates [MOS](https://en.wikipedia.org/wiki/Mean_opinion_score) for inbound and outbound network connections that can indicate a problem before it even appears.\n- **CPU issues** - indicates possible issues with encoding and decoding media streams.\n- **Server issues** - indicates possible server side issues.\n- **Fully customizable** - allows to create your own detectors or WebRTC getStats() parsers.\n\n\n## Installation\n\n`yarn add webrtc-issue-detector`\n\n\n## Usage\n\n### Getting started\n\n```typescript\nimport WebRTCIssueDetector from 'webrtc-issue-detector';\n\n// create it before the first instance of RTCPeerConnection is created\nconst webRtcIssueDetector = new WebRTCIssueDetector({\n    onIssues: (issues) =\u003e issues.map((issue) =\u003e {\n        console.log('Issues type:', issue.type); // eg. \"network\"\n        console.log('Issues reason:', issue.reason); // eg. \"outbound-network-throughput\"\n        console.log('Stats:', issue.statsSample); // eg. \"packetLossPct: 12%, avgJitter: 230, rtt: 150\"\n    }),\n    onNetworkScoresUpdated: (scores) =\u003e {\n        console.log('Inbound network score', scores.inbound); // eg. 3.7\n        console.log('Outbound network score', scores.outbound); // eg. 4.5\n        console.log('Network stats', scores.statsSamples); // eg. { inboundStatsSample: { avgJitter: 0.1, rtt: 30, packetsLoss: 8 }, ... }\n    }\n});\n\n// start collecting getStats() and detecting issues\nwebRtcIssueDetector.watchNewPeerConnections();\n\n// stop collecting WebRTC stats and issues detection\nwebRtcIssueDetector.stopWatchingNewPeerConnections();\n```\n\n### Configure\n\nBy default, WebRTCIssueDetector can be created with minimum of mandatory constructor parameters. But it's possible to override most of them.\n\n```typescript\nimport WebRTCIssueDetector, {\n  QualityLimitationsIssueDetector,\n  InboundNetworkIssueDetector,\n  OutboundNetworkIssueDetector,\n  NetworkMediaSyncIssueDetector,\n  AvailableOutgoingBitrateIssueDetector,\n  UnknownVideoDecoderImplementationDetector,\n  FrozenVideoTrackDetector,\n  VideoDecoderIssueDetector,\n} from 'webrtc-issue-detector';\n\nconst widWithDefaultConstructorArgs = new WebRTCIssueDetector();\n\n// or you can fully customize WebRTCIssueDetector with constructor arguments\n\nconst widWithCustomConstructorArgs = new WebRTCIssueDetector({\n  detectors: [ // you are free to change the detectors list according to your needs\n    new QualityLimitationsIssueDetector(),\n    new InboundNetworkIssueDetector(),\n    new OutboundNetworkIssueDetector(),\n    new NetworkMediaSyncIssueDetector(),\n    new AvailableOutgoingBitrateIssueDetector(),\n    new UnknownVideoDecoderImplementationDetector(),\n    new FrozenVideoTrackDetector(),\n    new VideoDecoderIssueDetector(),\n  ],\n  getStatsInterval: 10_000, // set custom stats parsing interval\n  onIssues: (payload: IssueDetectorResult) =\u003e {\n    // your custom callback for detected issues handling\n  },\n  onNetworkScoresUpdated: (payload: NetworkScores) =\u003e {\n    // your custom callback for networks score updates handling\n  },\n  ignoreSSRCList: [\n    // in case you need to skip some ssrc from parsing, add its numbers to the array\n  ],\n});\n```\n\n## Detectors\n\n### AvailableOutgoingBitrateIssueDetector\nDetects issues with outgoing network connection.\n```js\nconst exampleIssue = {\n    type: 'network',\n    reason: 'outbound-network-throughput',\n    statsSample: {\n      availableOutgoingBitrate: 1234,\n      videoStreamsTotalBitrate: 1234,\n      audioStreamsTotalTargetBitrate: 1234,\n    },\n}\n```\n\n### VideoDecoderIssueDetector\nDetects issues with decoder.\n```js\nconst exampleIssue = {\n    type: 'cpu',\n    reason: 'decoder-cpu-throttling',\n    statsSample: {\n      affectedStreamsPercent: 67,\n      throtthedStreams: [\n        { ssrc: 123, allDecodeTimePerFrame: [1.2, 1.6, 1.9, 2.4, 2.9], volatility: 1.7 },\n      ]\n    },\n}\n```\n\n### InboundNetworkIssueDetector\nDetects issues with inbound network connection.\n```js\nconst exampleIssue = {\n    type: 'network',\n    reason: 'inbound-network-quality' | 'inbound-network-media-latency' | 'network-media-sync-failure',\n    iceCandidate: 'ice-candidate-id',\n    statsSample: {\n      rtt: 1234,\n      packetLossPct: 1234,\n      avgJitter: 1234,\n      avgJitterBufferDelay: 1234,\n    },\n}\n```\n\nAlso can detect server side issues if there is high RTT and jitter is ok.\n```js\nconst exampleIssue = {\n    type: 'server',\n    reason: 'server-issue',\n    iceCandidate: 'ice-candidate-id',\n      statsSample: {\n        rtt: 1234,\n        packetLossPct: 1234,\n        avgJitter: 1234,\n        avgJitterBufferDelay: 1234,\n      },\n}\n```\n\n### NetworkMediaSyncIssueDetector\nDetects issues with audio synchronization.\n```js\nconst exampleIssue = {\n    type: 'network',\n    reason: 'network-media-sync-failure',\n    ssrc: 1234,\n    statsSample: {\n      correctedSamplesPct: 15,\n    },\n}\n```\n\n### OutboundNetworkIssueDetector\nDetects issues with outbound network connection.\n```js\nconst exampleIssue = {\n    type: 'network',\n    reason: 'outbound-network-quality' | 'outbound-network-media-latency',\n    iceCandidate: 'ice-candidate-id',\n    statsSample: {\n      rtt: 1234,\n      avgJitter: 1234,\n      packetLossPct: 1234,\n    },\n}\n```\n\n### QualityLimitationsIssueDetector\nDetects issues with encoder and outbound network. Based on native qualityLimitationReason.\n```js\nconst exampleIssue = {\n    type: 'cpu',\n    reason: 'encoder-cpu-throttling',\n    ssrc: 1234,\n    statsSample: {\n      qualityLimitationReason: 'cpu',\n    },\n}\n```\n\n```js\nconst exampleIssue = {\n    type: 'network',\n    reason: 'outbound-network-throughput',\n    ssrc: 1234,\n    statsSample: {\n      qualityLimitationReason: 'bandwidth',\n    },\n}\n```\n\n### VideoCodecMismatchDetector\nDetects issues with decoding stream.\n```js\nconst exampleIssue = {\n    type: 'stream',\n    reason: 'unknown-video-decoder',\n    ssrc: 1234,\n    trackIdentifier: 'some-track-id',\n    statsSample: {\n      mimeType: 'video/vp9',\n      decoderImplementation: 'unknown'\n    },\n}\n```\n\n\n### MissingStreamDataDetector\nDetects issues with missing data in active inbound streams\n```ts\nconst exampleIssue = {\n    type: 'stream',\n    reason: 'missing-video-stream-data' | 'missing-audio-stream-data',\n    trackIdentifier: 'some-track-id',\n    statsSample: {\n        bytesReceivedDelta: 0, // always zero if issue detected\n        bytesReceived: 2392384,\n        trackDetached: false,\n        trackEnded: false,\n    },\n}\n```\n\n## Roadmap\n\n- [ ] Adaptive getStats() call interval based on last getStats() execution time \n- [ ] Structured issue debug\n- [ ] Issues detector for user devices permissions\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVLprojects%2Fwebrtc-issue-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVLprojects%2Fwebrtc-issue-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVLprojects%2Fwebrtc-issue-detector/lists"}