explainer

README

Pion Explainer

Explainer decodes WebRTC... so you don't have too!

Explainer provides a PeerConnection Explainer that parses WebRTC Offers/Answers then provides summaries and suggestions. It returns information like what codecs are supported, how many tracks each peer is attempting to send and ICE information. It also provides suggestions to fix common errors.

The goal of this project is to make learning and debugging WebRTC easier.

Use Cases

• Debugging - Discover common errors without having to read and compare SDP values.
• Learning - Learn SDP keys and values and how they effect your WebRTC sessions.
• Passive Monitoring - Add Explainer to your existing Signaling and Media servers. Surface and fix existing issues.
• Custom Tooling - Include Explainer with your own UI in an existing project. Make it easier for your customers to use WebRTC.

Features

• Session Description Parsing - Human readable JSON output explaining your Offer/Answer
• Session Description Suggestions - Searches for errors and possible improvements, not just explaining the current values.
• Made for Learning - Returns line numbers for suggestion and parsing.
• Portable - Available in Browser, Go, nodejs, C/C++, Java, C# and more thanks to WASM.
• Interactive - Web demo provides interactive discovery of the SessionDescription.
• Flexible - Accepts SesionDescriptions or SDP, either value can be base64
• Decoupled - Easily ship your own UI, Explainer can run on clients or servers

Future Features

• getStats Parsing - Human readable JSON output explaining the status of your PeerConnection. What it is sending and why.
• getStats Suggestions - Understand why a certain bitrate is being sent or why you are seeing video corruption.
• getStats Graphing - Generate values that are easily plottable in your tool of choice.

Running

Examples for different languages are in the examples directory. A Web UI is provided in the web directory.

Each example will have a README.md describing its specific setup.

Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Discord.

Follow the Pion Bluesky or Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package explainer provides APIs to make debugging and learning WebRTC easier

Index

• type PeerConnectionExplainer
  • func NewPeerConnectionExplainer() PeerConnectionExplainer
• type PeerDetails
• type Result
• type SessionDetails

Types

type PeerConnectionExplainer

type PeerConnectionExplainer interface {
	// SetLocalDescription updates the PeerConnectionExplainer with the provided SessionDescription
	SetLocalDescription(input string)

	// GetLocalDescription returns the current SDP we are using from SetLocalDescription
	GetLocalDescription() string

	// SetRemoteDescription updates the PeerConnectionExplainer with the provided SessionDescription
	SetRemoteDescription(input string)

	// GetRemoteDescription returns the current SDP we are using from SetRemoteDescription
	GetRemoteDescription() string

	// Explain returns the result of the current PeerConnectionExplainer.
	Explain() Result
}

PeerConnectionExplainer mocks the PeerConnection API and returns analysis and suggestions.

func NewPeerConnectionExplainer

func NewPeerConnectionExplainer() PeerConnectionExplainer

NewPeerConnectionExplainer returns a new PeerConnectionExplainer.

type PeerDetails

type PeerDetails = result.PeerDetails

PeerDetails contains the details published by a single peer. This is what a single peer Offered or Answered.

type Result

type Result struct {
	Errors      []output.Message `json:"errors"`
	Warnings    []output.Message `json:"warnings"`
	Suggestions []output.Message `json:"suggestions"`

	LocalDetails  PeerDetails `json:"localDetails"`
	RemoteDetails PeerDetails `json:"remoteDetails"`

	SessionDetails SessionDetails `json:"sessionDetails"`
}

Result is the current status of the PeerConnectionExplainer.

type SessionDetails

type SessionDetails = result.SessionDetails

SessionDetails is the combination of the Offer/Answer and what the actual state of the WebRTC session is.