Reassign ownership of WebRTC documentation Reassign the owner field in the freshness marker of 16 documentation files to the new assigned owners. Also did minor updates using automatic tools. Bug: None Change-Id: I0e54d06c96e9a3ae3573cf553befe8e679a0f6dc Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/483281 Reviewed-by: Danil Chapovalov <danilchap@webrtc.org> Commit-Queue: Harald Alvestrand <hta@webrtc.org> Cr-Commit-Position: refs/heads/main@{#48044}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 14c4886..0eef5a9 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md
@@ -1,71 +1,85 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # Contributors Code of Conduct -Google and the WebRTC team are committed to preserving and fostering a diverse, welcoming and open -community. The WebRTC project is open to contributors from all walks of life and should be a -harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender -identity and expression, level of experience, nationality, personal appearance, race, religion, or -sexual identity and orientation. +Google and the WebRTC team are committed to preserving and fostering a diverse, +welcoming and open community. The WebRTC project is open to contributors from +all walks of life and should be a harassment-free experience for everyone, +regardless of age, body size, disability, ethnicity, gender identity and +expression, level of experience, nationality, personal appearance, race, +religion, or sexual identity and orientation. ## Scope -This Code of Conduct applies to our repos and organizations, mailing lists, blog content, and any -other WebRTC-supported communication group, as well as any private communication initiated in the -context of these spaces. + +This Code of Conduct applies to our repos and organizations, mailing lists, blog +content, and any other WebRTC-supported communication group, as well as any +private communication initiated in the context of these spaces. ## Standards -Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit -permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting ## Responsibilities -You are empowered to politely engage when you feel that you or others are disrespected. The person -making you feel uncomfortable may not be aware of what they are doing - politely bringing their -behavior to their attention is encouraged. +You are empowered to politely engage when you feel that you or others are +disrespected. The person making you feel uncomfortable may not be aware of what +they are doing - politely bringing their behavior to their attention is +encouraged. -If you are uncomfortable speaking up, or feel that your concerns are not being duly considered, you -can email community@webrtc.org to request involvement from a community manager. All concerns shared -with community managers will be kept confidential. While all reports will be taken seriously, the -WebRTC community managers may not act on complaints that they feel are not violations of this code -of conduct. +If you are uncomfortable speaking up, or feel that your concerns are not being +duly considered, you can email community@webrtc.org to request involvement from +a community manager. All concerns shared with community managers will be kept +confidential. While all reports will be taken seriously, the WebRTC community +managers may not act on complaints that they feel are not violations of this +code of conduct. ## Enforcement -Consequences for failing to comply with this policy may include, at the sole discretion of the -WebRTC community managers: +Consequences for failing to comply with this policy may include, at the sole +discretion of the WebRTC community managers: -* a request for an apology; -* a private or public warning or reprimand; -* a temporary ban from the mailing list, blog, WebRTC repository or organization, or other -WebRTC-supported communication group, including loss of committer status; -* a permanent ban from any of the above, or from all current and future WebRTC-supported or -Google-supported communities, including loss of committer status. +- a request for an apology; +- a private or public warning or reprimand; +- a temporary ban from the mailing list, blog, WebRTC repository or + organization, or other WebRTC-supported communication group, including loss of + committer status; +- a permanent ban from any of the above, or from all current and future + WebRTC-supported or Google-supported communities, including loss of committer + status. -Participants warned to stop any harassing behavior are expected to comply immediately; failure to do -so will result in an escalation of consequences. +Participants warned to stop any harassing behavior are expected to comply +immediately; failure to do so will result in an escalation of consequences. -The decisions of the WebRTC community managers may be appealed via community-appeals@webrtc.org. +The decisions of the WebRTC community managers may be appealed via +community-appeals@webrtc.org. ## Acknowledgements -This Code of Conduct is based on Contributor Covenant, version 1.4, -available [here](http://contributor-covenant.org/version/1/4) and [Chromium](https://chromium.googlesource.com/chromium/src/+/main/CODE_OF_CONDUCT.md) +This Code of Conduct is based on Contributor Covenant, version 1.4, available +[here](http://contributor-covenant.org/version/1/4) and +[Chromium](https://chromium.googlesource.com/chromium/src/+/main/CODE_OF_CONDUCT.md) ## License -This Code of Conduct is available for reuse under the Creative Commons Zero (CC0) license. +This Code of Conduct is available for reuse under the Creative Commons Zero +(CC0) license.
diff --git a/api/README.md b/api/README.md index cf6d73a..5113147 100644 --- a/api/README.md +++ b/api/README.md
@@ -1,25 +1,26 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # How to write code in the `api/` directory Mostly, just follow the regular [style guide](/g3doc/style-guide.md), but: -* Note that `api/` code is not exempt from the “`.h` and `.cc` files come in +- Note that `api/` code is not exempt from the “`.h` and `.cc` files come in pairs” rule, so if you declare something in `api/path/to/foo.h`, it should be defined in `api/path/to/foo.cc`. -* Headers in `api/` should, if possible, not `#include` headers outside `api/`. +- Headers in `api/` should, if possible, not `#include` headers outside `api/`. It’s not always possible to avoid this, but be aware that it adds to a small mountain of technical debt that we’re trying to shrink. -* `.cc` files in `api/`, on the other hand, are free to `#include` headers +- `.cc` files in `api/`, on the other hand, are free to `#include` headers outside `api/`. -* Avoid structs in api, prefer classes. +- Avoid structs in api, prefer classes. -The preferred way for `api/` code to access non-`api/` code is to call -it from a `.cc` file, so that users of our API headers won’t transitively -`#include` non-public headers. +The preferred way for `api/` code to access non-`api/` code is to call it from a +`.cc` file, so that users of our API headers won’t transitively `#include` +non-public headers. -For headers in `api/` that need to refer to non-public types, forward +For headers in `api/` that need to refer to non-`api/` types, forward declarations are often a lesser evil than including non-public header files. The usual [rules](/g3doc/style-guide.md#forward-declarations) still apply, though. @@ -27,11 +28,13 @@ substantial implementation is needed, consider putting it with our non-public code, and just call it from the `api/` `.cc` file. -Avoid defining api with structs as it makes harder for the api to evolve. -Your struct may gain invariant, or change how it represents data. -Evolving struct from the api is particular challenging as it is designed to be -used in other code bases and thus needs to be updated independetly from its usage. -Class with accessors and setters makes such migration safer. -See [Google C++ style guide](https://google.github.io/styleguide/cppguide.html#Structs_vs._Classes) for more. +Avoid defining api with structs as it makes harder for the api to evolve. Your +struct may gain invariant, or change how it represents data. Evolving struct +from the api is particularly challenging as it is designed to be used in other +code bases and thus needs to be updated independently from its usage. Class with +accessors and setters makes such migration safer. See +[Google C++ style guide](https://google.github.io/styleguide/cppguide.html#Structs_vs._Classes) +for more. -If you need to evolve existent struct in api, prefer first to convert it into a class. +If you need to evolve an existing struct in api, prefer first to convert it into +a class.
diff --git a/api/g3doc/index.md b/api/g3doc/index.md index cd4415c..c78418a 100644 --- a/api/g3doc/index.md +++ b/api/g3doc/index.md
@@ -1,16 +1,17 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # The WebRTC API -The public API of the WebRTC library consists of the api/ directory and -its subdirectories. No other files should be depended on by webrtc users. +The public API of the WebRTC library consists of the api/ directory and its +subdirectories. No other files should be depended on by webrtc users. -Before starting to code against the API, it is important to understand -some basic concepts, such as: +Before starting to code against the API, it is important to understand some +basic concepts, such as: -* Memory management, including webrtc's reference counted objects -* [Thread management](threading_design.md) +- Memory management, including webrtc's reference counted objects +- [Thread management](threading_design.md) ## Using WebRTC through the PeerConnection class @@ -18,27 +19,27 @@ [PeerConnectionInterface](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/peer_connection_interface.h?q=webrtc::PeerConnectionInterface) class is the recommended way to use the WebRTC library. -It is closely modeled after the Javascript API documented in the [WebRTC -specification](https://w3c.github.io/webrtc-pc/). +It is closely modeled after the Javascript API documented in the +[WebRTC specification](https://w3c.github.io/webrtc-pc/). -PeerConnections are created using the [PeerConnectionFactoryInterface](https://source.chromium.org/search?q=webrtc::PeerConnectionFactoryInterface). +PeerConnections are created using the +[PeerConnectionFactoryInterface](https://source.chromium.org/search?q=webrtc::PeerConnectionFactoryInterface). There are two levels of customization available: -* Pass a PeerConnectionFactoryDependencies object to the function that creates - a PeerConnectionFactory. This object defines factories for a lot of internal - objects inside the PeerConnection, so that users can override them. - All PeerConnections using this interface will have the same options. -* Pass a PeerConnectionInterface::RTCConfiguration object to the - CreatePeerConnectionOrError() function on the - PeerConnectionFactoryInterface. These customizations will apply only to a - single PeerConnection. +- Pass a PeerConnectionFactoryDependencies object to the function that creates a + PeerConnectionFactory. This object defines factories for a lot of internal + objects inside the PeerConnection, so that users can override them. All + PeerConnections using this interface will have the same options. +- Pass a PeerConnectionInterface::RTCConfiguration object to the + CreatePeerConnectionOrError() function on the PeerConnectionFactoryInterface. + These customizations will apply only to a single PeerConnection. Most functions on the PeerConnection interface are asynchronous, and take a callback that is executed when the function is finished. The callbacks are mostly called on the thread that is passed as the "signaling thread" field of the PeerConnectionFactoryDependencies, or the thread that called -PeerConnectionFactory::CreatePeerConnectionOrError() if no thread is given. +`webrtc::CreatePeerConnectionFactory()` if no signaling thread is given. See each class' module documentation for details. @@ -49,8 +50,4 @@ ## Video Codecs -* [RTC Video Encoder API v2](/api/video_codecs/g3doc/video_encoder_api_v2.md) - - - - +- [RTC Video Encoder API v2](/api/video_codecs/g3doc/video_encoder_api_v2.md)
diff --git a/api/g3doc/threading_design.md b/api/g3doc/threading_design.md index 38ace68..5251ead 100644 --- a/api/g3doc/threading_design.md +++ b/api/g3doc/threading_design.md
@@ -1,43 +1,43 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-04-12'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # API Threading Design considerations -The header files in this directory form the API to the WebRTC library -that is intended for client applications' use. +The header files in this directory form the API to the WebRTC library that is +intended for client applications' use. This API is designed to be used on top of a multithreaded runtime. -The public API functions are designed to be called from a single thread* -(the "client thread"), and can do internal dispatching to the thread -where activity needs to happen. Those threads can be passed in by the -client, typically as arguments to factory constructors, or they can be -created by the library if factory constructors that don't take threads -are used. +The public API functions are designed to be called from a single thread\* (the +"client thread"), and can do internal dispatching to the thread where activity +needs to happen. Those threads can be passed in by the client, typically as +arguments to factory constructors, or they can be created by the library if +factory constructors that don't take threads are used. -Many of the functions are designed to be used in an asynchronous manner, -where a function is called to initiate an activity, and a callback will -be called when the activity is completed, or a handler function will -be called on an observer object when interesting events happen. +Many of the functions are designed to be used in an asynchronous manner, where a +function is called to initiate an activity, and a callback will be called when +the activity is completed, or a handler function will be called on an observer +object when interesting events happen. -Note: Often, even functions that look like simple functions (such as -information query functions) will need to jump between threads to perform -their function - which means that things may happen on other threads -between calls; writing "increment(x); increment(x)" is not a safe -way to increment X by exactly two, since the increment function may have -jumped to another thread that already had a queue of things to handle, -causing large amounts of other activity to have intervened between -the two calls. +Note: Often, even functions that look like simple functions (such as information +query functions) will need to jump between threads to perform their function - +which means that things may happen on other threads between calls; writing +"increment(x); increment(x)" is not a safe way to increment X by exactly two, +since the increment function may have jumped to another thread that already had +a queue of things to handle, causing large amounts of other activity to have +intervened between the two calls. -(*) The term "thread" is used here to denote any construct that guarantees -sequential execution - other names for such constructs are task runners -and sequenced task queues. +(\*) The term "thread" is used here to denote any construct that guarantees +sequential execution - other names for such constructs are task runners and +sequenced task queues. ## Client threads and callbacks -At the moment, the API does not give any guarantee on which thread* the -callbacks and events are called on. So it's best to write all callback -and event handlers like this (pseudocode): +At the moment, the API does not give any guarantee on which thread\* the +callbacks and events are called on. So it's best to write all callback and event +handlers like this (pseudocode): + ``` void ObserverClass::Handler(event) { if (!called_on_client_thread()) { @@ -47,35 +47,36 @@ // Process event, we're now on the right thread } ``` -It is generally NOT safe to call WebRTC library functions from the callback; -if this is wanted, one should instead dispatch a task on an appropriate -thread to do so. -In the future, the implementation may evolve to crash or return an error -if this happens. +It is generally NOT safe to call WebRTC library functions from the callback; if +this is wanted, one should instead dispatch a task on an appropriate thread to +do so. -In the future, the implementation may change to always call the callbacks -and event handlers on the client thread. +In the future, the implementation may evolve to crash or return an error if this +happens. + +In the future, the implementation may change to always call the callbacks and +event handlers on the client thread. ## Implementation considerations -The C++ classes that are part of the public API are also used to derive -classes that form part of the implementation. +The C++ classes that are part of the public API are also used to derive classes +that form part of the implementation. -This should not directly concern users of the API, but may matter if one -wants to look at how the WebRTC library is implemented, or for legacy code -that directly accesses internal APIs. +This should not directly concern users of the API, but may matter if one wants +to look at how the WebRTC library is implemented, or for legacy code that +directly accesses internal APIs. Many APIs are defined in terms of a "proxy object", which will do a blocking -dispatch of the function to another thread, and an "implementation object" -which will do the actual -work, but can only be created, invoked and destroyed on its "home thread". +dispatch of the function to another thread, and an "implementation object" which +will do the actual work, but can only be created, invoked and destroyed on its +"home thread". -Usually, the classes are named "xxxInterface" (in api/), "xxxProxy" and -"xxx" (not in api/). WebRTC users should only need to depend on the files -in api/. In many cases, the "xxxProxy" and "xxx" classes are subclasses -of "xxxInterface", but this property is an implementation feature only, -and should not be relied upon. +Usually, the classes are named "xxxInterface" (in api/), "xxxProxy" and "xxx" +(not in api/). WebRTC users should only need to depend on the files in api/. In +many cases, the "xxxProxy" and "xxx" classes are subclasses of "xxxInterface", +but this property is an implementation feature only, and should not be relied +upon. -The threading properties of these internal APIs are NOT documented in -this note, and need to be understood by inspecting those classes. +The threading properties of these internal APIs are NOT documented in this note, +and need to be understood by inspecting those classes.
diff --git a/g3doc/field-trials.md b/g3doc/field-trials.md index 7273fbc..96ed1f5 100644 --- a/g3doc/field-trials.md +++ b/g3doc/field-trials.md
@@ -1,6 +1,6 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2026-04-23'} *--> +<!--* freshness: {owner: 'danilchap' reviewed: '2026-06-17'} *--> # Field trials
diff --git a/g3doc/implementation_basics.md b/g3doc/implementation_basics.md index 6860638..c1e5587 100644 --- a/g3doc/implementation_basics.md +++ b/g3doc/implementation_basics.md
@@ -1,29 +1,28 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2024-09-09'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # Basic concepts and primitives ## Time Internally, time is represent using the [webrtc::Timestamp][1] class. This -represents -time with a resolution of one microsecond, using a 64-bit integer, and provides -converters to milliseconds or seconds as needed. +represents time with a resolution of one microsecond, using a 64-bit integer, +and provides converters to milliseconds or seconds as needed. All timestamps need to be measured from the system monotonic time. The epoch is not specified (because we can't always know if the system clock is -correct), but whenever an absolute epoch is needed, the Unix time -epoch (Jan 1, 1970 at 0:00 GMT) is used. +correct), but whenever an absolute epoch is needed, the Unix time epoch (Jan 1, +1970 at 0:00 GMT) is used. -Conversion from/to other formats (for example milliseconds, NTP times, -timestamp strings) should happen as close to the interface requiring that -format as possible. +Conversion from/to other formats (for example milliseconds, NTP times, timestamp +strings) should happen as close to the interface requiring that format as +possible. NOTE: There are parts of the codebase that don't use Timestamp, parts of the codebase that use the NTP epoch, and parts of the codebase that don't use the -monotonic clock. They need to -be updated. +monotonic clock. They need to be updated. ## Threads @@ -32,36 +31,36 @@ This API offers primitives for posting tasks, with or without delay. -Some core parts use the [webrtc::Thread][2], which is a subclass of TaskQueueBase. -This may contain a SocketServer for processing I/O, and is used for policing -certain calling pattern between a few core threads (the NetworkThread cannot -do Invoke on the Worker thread, for instance). +Some core parts use the [webrtc::Thread][2], which is a subclass of +TaskQueueBase. This may contain a SocketServer for processing I/O, and is used +for policing certain calling pattern between a few core threads (the +NetworkThread cannot do Invoke on the Worker thread, for instance). ## Reserved class suffixes -C++ classes with names ending in the suffixes "Factory", "Builder" and "Manager" are supposed to behave -in certain well known ways. +C++ classes with names ending in the suffixes "Factory", "Builder" and "Manager" +are supposed to behave in certain well known ways. For a particular class name Foo, the following classes, if they exist, should behave as follows: -* FooFactory: Has a Create function that creates a Foo object and returns the +- FooFactory: Has a Create function that creates a Foo object and returns the object or an owning reference to it (for instance std::unique_ptr or webrtc::scoped_refptr<Foo>). The Create function should NOT alter the factory state; ideally, it is marked const. Ownership of the returned object is only with the caller. -* FooBuilder: Has a Build function that returns ownership of a Foo object (as +- FooBuilder: Has a Build function that returns ownership of a Foo object (as above). The Builder can only be used once, and resources given to the Builder before the Build function is called are either released or owned by the Foo - object. The Build function may be reference-qualified (declared as ```Foo - Build() &&```), which means it is invoked as ```std::move(builder).Build()```, + object. The Build function may be reference-qualified (declared as + `Foo Build() &&`), which means it is invoked as `std::move(builder).Build()`, and C++ will ensure that it is not used again. -* FooManager: Has a Create function that returns an webrtc::scoped_refptr<Foo> (if - shared ownership) or a Foo* (if the Manager retains sole ownership). If +- FooManager: Has a Create function that returns an webrtc::scoped_refptr<Foo> + (if shared ownership) or a Foo\* (if the Manager retains sole ownership). If Create() cannot fail, consider returning a Foo&. The Manager is responsible - for keeping track of the object; if the Create function returns a Foo*, the + for keeping track of the object; if the Create function returns a Foo\*, the Foo object is guaranteed to be destroyed when the FooManager is destroyed. If a Manager class manages multiple classes of objects, the Create functions @@ -71,8 +70,8 @@ FooFactory is mainly useful for the case where preparation for producing Foo objects is complex. If Foo can be created with just an argument list, consider -exposing its constructor instead; if Foo creation can fail, consider having -a free function called CreateFoo instead of a factory. +exposing its constructor instead; if Foo creation can fail, consider having a +free function called CreateFoo instead of a factory. Note that classes with these names exist that do not follow these conventions. When they are detected, they need to be marked with TODO statements and bugs @@ -82,30 +81,28 @@ ### PostTask and thread-guarded variables -The preferred method for synchronization is to post tasks between threads, -and to let each thread take care of its own variables (lock-free programming). -All variables in -classes intended to be used with multiple threads should therefore be -annotated with RTC_GUARDED_BY(thread). +The preferred method for synchronization is to post tasks between threads, and +to let each thread take care of its own variables (lock-free programming). All +variables in classes intended to be used with multiple threads should therefore +be annotated with RTC_GUARDED_BY(thread). -For classes used with only one thread, the recommended pattern is to let -them own a webrtc::SequenceChecker (conventionally named sequence_checker_) -and let all variables be RTC_GUARDED_BY(sequence_checker_). +For classes used with only one thread, the recommended pattern is to let them +own a webrtc::SequenceChecker (conventionally named sequence_checker\_) and let +all variables be RTC_GUARDED_BY(sequence_checker\_). Member variables marked const do not need to be guarded, since they never change. (But note that they may point to objects that can change!) -When posting tasks with callbacks, it is the duty of the caller to check -that the object one is calling back into still exists when the callback -is made. A helper for this task is the [webrtc::ScopedTaskSafety][5] -flag, which can automatically drop callbacks in this situation, and -associated classes. +When posting tasks with callbacks, it is the duty of the caller to check that +the object one is calling back into still exists when the callback is made. A +helper for this task is the [webrtc::ScopedTaskSafety][5] flag, which can +automatically drop callbacks in this situation, and associated classes. ### Synchronization primitives to be used when needed -When it is absolutely necessary to let one thread wait for another thread -to do something, Thread::BlockingCall can be used. This function is DISCOURAGED, -since it leads to performance issues, but is currently still widespread. +When it is absolutely necessary to let one thread wait for another thread to do +something, Thread::BlockingCall can be used. This function is DISCOURAGED, since +it leads to performance issues, but is currently still widespread. When it is absolutely necessary to access one variable from multiple threads, the webrtc::Mutex can be used. Such variables MUST be marked up with @@ -115,62 +112,82 @@ Avoid mixing use of Mutex and TaskQueue. Prefer lock-free programming. ### Synchronization primitives that are being removed -The following non-exhaustive list of synchronization primitives are -in the (slow) process of being removed from the codebase. -* RecursiveCriticalSection. Try to use [webrtc::Mutex][6] instead, and don't recurse. +The following non-exhaustive list of synchronization primitives are in the +(slow) process of being removed from the codebase. -* std::atomic. See [the abseil article about the subject][7] for why. +- RecursiveCriticalSection. Try to use [webrtc::Mutex][6] instead, and don't + recurse. + +- std::atomic. See [the abseil article about the subject][7] for why. ## Enum-To-String functions + If there is a need to convert an enum to a string representation, such as for -enums exposed at the Javascript API interface, the recommended way is to write -a function named AsString, declared "static constexpr" and returning an +enums exposed at the Javascript API interface, the recommended way is to write a +function named AsString, declared "static constexpr" and returning an absl::string_view. The declaration should be right after the enum declaration, -in the same scope; the implementation (which must be marked "inline") should -be at the end of the same header file. +in the same scope; the implementation (which must be marked "inline") should be +at the end of the same header file. If the enum is not defined within a class, the "static" keyword is not needed. +## Namespaces + +`cricket` and `rtc` namespaces do not exist; they were removed in 2025. All +WebRTC types are in the `webrtc` namespace. + +## Verification of changes + +When making changes to the source code, it is not enough to only build the test +binary that covers the modified code. + +Before uploading changes to gerrit for review, make sure to complete the +following steps: + +- Ensure that your branch is up to date. +- Run `git cl format`. This will format source code and build (.gn) files. +- Check for and fix any IWYU errors. +- Check for and fix any gn errors. +- Ensure that a *full build* of all binaries passes. This will save time and + resources. +- If at any of the above steps changes had to be made, go back the first step + and repeat until no changes are required at every step. + +## Pointer Nullability Annotations + +To ensure high-quality, machine-checkable C++ code in WebRTC, adhere to the +following rules regarding pointer nullability. + +- **Core Principle**: Prevent accidental use of invalid null values by + explicitly declaring the nullability contract of all raw and smart pointers. + +- **Classify Every Pointer**: Avoid leaving pointers in the "Unknown" + (unannotated) state. Actively classify whether null is a valid semantic state + for every pointer you write or modify. + +- **Annotate Nullable Exceptions (`absl_nullable`)**: When null is a valid and + expected value at the point of use, you must explicitly annotate the pointer. + + - Raw Pointers: Use the format `T* absl_nullable` (e.g., + `Widget* absl_nullable widget`). + - Smart Pointers: Use the format `absl_nullable std::unique_ptr<T>` (e.g., + `absl_nullable std::unique_ptr<Widget> widget`). + +- **Enforce Strict Requirements (`absl_nonnull`)**: When a pointer must + fundamentally never be null, enforce this contract explicitly. + + - Raw Pointers: Use the format `T* absl_nonnull` but for non-null raw pointers + prefer to use a reference instead. + - Smart Pointers: Use the format `absl_nonnull std::unique_ptr<T>`. + +- **Leverage Machine Checking**: Treat these annotations as strict contracts. + Rely on them to surface potential null-dereference errors or contract + violations during static analysis and compilation. + [1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/units/timestamp.h;drc=b95d90b78a3491ef8e8aa0640dd521515ec881ca;l=29 [2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/thread.h;drc=1107751b6f11c35259a1c5c8a0f716e227b7e3b4;l=194 [3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/task_queue/task_queue_base.h;drc=1107751b6f11c35259a1c5c8a0f716e227b7e3b4;l=25 -[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/callback_list.h;drc=54b91412de3f579a2d5ccdead6e04cc2cc5ca3a1;l=162 [5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/task_utils/pending_task_safety_flag.h;drc=86ee89f73e4f4799b3ebcc0b5c65837c9601fe6d;l=117 [6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/rtc_base/synchronization/mutex.h;drc=0d3c09a8fe5f12dfbc9f1bcd5790fda8830624ec;l=40 [7]: https://abseil.io/docs/cpp/atomic_danger - -## Namespaces -`cricket` and `rtc` namespaces do not exist; they were removed in 2025. All WebRTC types -are in the `webrtc` namespace. - -## Verification of changes -When making changes to the source code, it is not enough to only build the test binary that -covers the modified code. - -Before uploading changes to gerrit for review, make sure to complete the following steps: - -* Ensure that your branch is up to date. -* Run `git cl format`. This will format source code and build (.gn) files. -* Check for and fix any IWYU errors. -* Check for and fix any gn errors. -* Ensure that a *full build* of all binaries passes. This will save time and resources. -* If at any of the above steps changes had to be made, go back the first step and repeat - until no changes are required at every step. - -## Pointer Nullability Annotations -To ensure high-quality, machine-checkable C++ code in WebRTC, adhere to the following rules regarding pointer nullability. - -* **Core Principle**: Prevent accidental use of invalid null values by explicitly declaring the nullability contract of all raw and smart pointers. - -* **Classify Every Pointer**: Avoid leaving pointers in the "Unknown" (unannotated) state. Actively classify whether null is a valid semantic state for every pointer you write or modify. - -* **Annotate Nullable Exceptions (`absl_nullable`)**: When null is a valid and expected value at the point of use, you must explicitly annotate the pointer. - * Raw Pointers: Use the format `T* absl_nullable` (e.g., `Widget* absl_nullable widget`). - * Smart Pointers: Use the format `absl_nullable std::unique_ptr<T>` (e.g., `absl_nullable std::unique_ptr<Widget> widget`). - -* **Enforce Strict Requirements (`absl_nonnull`)**: When a pointer must fundamentally never be null, enforce this contract explicitly. - * Raw Pointers: Use the format `T* absl_nonnull` but for non-null raw pointers prefer to use a reference instead. - * Smart Pointers: Use the format `absl_nonnull std::unique_ptr<T>`. - -* **Leverage Machine Checking**: Treat these annotations as strict contracts. Rely on them to surface potential null-dereference errors or contract violations during static analysis and compilation. \ No newline at end of file
diff --git a/g3doc/org-contributions.md b/g3doc/org-contributions.md index 62d01bc..3a939a2 100644 --- a/g3doc/org-contributions.md +++ b/g3doc/org-contributions.md
@@ -1,6 +1,6 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2026-04-16'} *--> +<!--* freshness: {owner: 'solenberg' reviewed: '2026-06-17'} *--> # Organizational contributors to WebRTC
diff --git a/g3doc/plan_b_removal.md b/g3doc/plan_b_removal.md index 6946a65..dcc7c7c 100644 --- a/g3doc/plan_b_removal.md +++ b/g3doc/plan_b_removal.md
@@ -1,29 +1,38 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2026-01-17'} *--> + +<!--* freshness: {owner: 'hbos' reviewed: '2026-06-17'} *--> # Plan B Deprecation and Removal -This document describes the tooling and process for deprecating and eventually removing Plan B SDP semantics from the WebRTC codebase. +This document describes the tooling and process for deprecating and eventually +removing Plan B SDP semantics from the WebRTC codebase. ## Build Configuration -To support a gradual deprecation, a new GN argument and C++ macro have been introduced. +To support a gradual deprecation, a new GN argument and C++ macro have been +introduced. ### GN Argument: `deprecate_plan_b` -Defined in `webrtc.gni`, this argument controls whether Plan B specific APIs are marked as deprecated at compile time. +Defined in `webrtc.gni`, this argument controls whether Plan B specific APIs are +marked as deprecated at compile time. -* **`false` (default):** Plan B APIs are available without warnings. -* **`true`:** Plan B APIs are annotated with `[[deprecated]]`. In WebRTC's default build configuration (which treats warnings as errors), this will cause compilation to fail if any Plan B APIs are used. +- **`false` (default):** Plan B APIs are available without warnings. +- **`true`:** Plan B APIs are annotated with `[[deprecated]]`. In WebRTC's + default build configuration (which treats warnings as errors), this will cause + compilation to fail if any Plan B APIs are used. To enable this in your local build, add the following to your `args.gn`: + ```gn deprecate_plan_b = true ``` ### C++ Macro: `PLAN_B_ONLY` -Defined in `rtc_base/system/plan_b_only.h`, this macro should be used to annotate functions, classes, or variables that are only needed for Plan B semantics. +Defined in `rtc_base/system/plan_b_only.h`, this macro should be used to +annotate functions, classes, or variables that are only needed for Plan B +semantics. ```cpp #include "rtc_base/system/plan_b_only.h" @@ -36,7 +45,8 @@ ### Suppression Macros -To allow existing Plan B code to compile when `deprecate_plan_b = true`, the following macros are provided in `rtc_base/system/plan_b_only.h`: +To allow existing Plan B code to compile when `deprecate_plan_b = true`, the +following macros are provided in `rtc_base/system/plan_b_only.h`: - `RTC_ALLOW_PLAN_B_DEPRECATION_BEGIN()` - `RTC_ALLOW_PLAN_B_DEPRECATION_END()` @@ -46,13 +56,20 @@ ## Usage Guidelines ### Annotating New Plan B Code -Avoid adding new Plan B code. If it is absolutely necessary, ensure it is annotated with the `PLAN_B_ONLY` macro. + +Avoid adding new Plan B code. If it is absolutely necessary, ensure it is +annotated with the `PLAN_B_ONLY` macro. ### Identifying Plan B Dependencies -By setting `deprecate_plan_b = true`, developers can identify all call sites that still rely on Plan B. This is the primary method for auditing the progress of the migration to Unified Plan. + +By setting `deprecate_plan_b = true`, developers can identify all call sites +that still rely on Plan B. This is the primary method for auditing the progress +of the migration to Unified Plan. ### Suppressing Deprecation Warnings in Legacy Code -Existing Plan B call sites in "glue code" (e.g., `PeerConnection` delegation logic) should be wrapped with the suppression macros to allow the build to pass. + +Existing Plan B call sites in "glue code" (e.g., `PeerConnection` delegation +logic) should be wrapped with the suppression macros to allow the build to pass. ```cpp RTC_ALLOW_PLAN_B_DEPRECATION_BEGIN(); @@ -60,7 +77,11 @@ RTC_ALLOW_PLAN_B_DEPRECATION_END(); ``` -This ensures that the build only fails on *new*, unwrapped Plan B usage, while clearly marking legacy code that requires migration. +This ensures that the build only fails on *new*, unwrapped Plan B usage, while +clearly marking legacy code that requires migration. ### Transitioning to Unified Plan -Functions that are compatible with both Plan B and Unified Plan should **not** be annotated. Only those that are functionally incorrect or redundant under Unified Plan (often guarded by `RTC_DCHECK(!IsUnifiedPlan())`) should be marked. + +Functions that are compatible with both Plan B and Unified Plan should **not** +be annotated. Only those that are functionally incorrect or redundant under +Unified Plan (often guarded by `RTC_DCHECK(!IsUnifiedPlan())`) should be marked.
diff --git a/g3doc/todo/remove_deprecated.md b/g3doc/todo/remove_deprecated.md index 6e9b759..7d1ed24 100644 --- a/g3doc/todo/remove_deprecated.md +++ b/g3doc/todo/remove_deprecated.md
@@ -1,6 +1,6 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2026-04-24'} *--> +<!--* freshness: {owner: 'danilchap' reviewed: '2026-06-17'} *--> # Plan: Iterative Removal of Deprecated Symbols
diff --git a/native-api.md b/native-api.md index ec100a3..993d636 100644 --- a/native-api.md +++ b/native-api.md
@@ -1,70 +1,66 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *--> + +<!--* freshness: {owner: 'tommi' reviewed: '2026-06-17'} *--> # API header files -As a user of the WebRTC library, you may use headers and build files -in the following directories: +As a user of the WebRTC library, you may use headers and build files in the +following directories: -API directory | Including subdirectories? ---------------|------------------------- -`api` | Yes +| API directory | Including subdirectories? | +| ------------- | ------------------------- | +| `api` | Yes | -For now, you may also use headers and build files in the following -legacy API directories—but see the -[disclaimer](#legacy-disclaimer) below. +For now, you may also use headers and build files in the following legacy API +directories—but see the [disclaimer](#legacy-disclaimer) below. -Legacy API directory | Including subdirectories? --------------------------------------------|-------------------------- -`common_audio/include` | No -`media/base` | No -`media/engine` | No -`modules/audio_coding/include` | No -`modules/audio_device/include` | No -`modules/audio_processing/include` | No -`modules/congestion_controller/include` | No -`modules/include` | No -`modules/rtp_rtcp/include` | No -`modules/rtp_rtcp/source` | No -`modules/utility/include` | No -`modules/video_coding/codecs/h264/include` | No -`modules/video_coding/codecs/vp8/include` | No -`modules/video_coding/codecs/vp9/include` | No -`modules/video_coding/include` | No -`pc` | No -`rtc_base` | No -`system_wrappers/include` | No +| Legacy API directory | Including subdirectories? | +| ------------------------------------------ | ------------------------- | +| `common_audio/include` | No | +| `media/base` | No | +| `media/engine` | No | +| `modules/audio_coding/include` | No | +| `modules/audio_device/include` | No | +| `modules/audio_processing/include` | No | +| `modules/congestion_controller/include` | No | +| `modules/include` | No | +| `modules/rtp_rtcp/include` | No | +| `modules/rtp_rtcp/source` | No | +| `modules/utility/include` | No | +| `modules/video_coding/codecs/h264/include` | No | +| `modules/video_coding/codecs/vp8/include` | No | +| `modules/video_coding/codecs/vp9/include` | No | +| `modules/video_coding/include` | No | +| `pc` | No | +| `rtc_base` | No | +| `system_wrappers/include` | No | -While the files, types, functions, macros, build targets, etc. in the -API and legacy API directories will sometimes undergo incompatible -changes, such changes will be announced in advance to -[discuss-webrtc@googlegroups.com][discuss-webrtc], and a migration -path will be provided. +While the files, types, functions, macros, build targets, etc. in the API and +legacy API directories will sometimes undergo incompatible changes, such changes +will be announced in advance to +[discuss-webrtc@googlegroups.com][discuss-webrtc], and a migration path will be +provided. -[discuss-webrtc]: https://groups.google.com/forum/#!forum/discuss-webrtc +In the directories not listed in the tables above, incompatible changes may +happen at any time, and are not announced. -In the directories not listed in the tables above, incompatible -changes may happen at any time, and are not announced. +## <a name="legacy-disclaimer"></a>The legacy API directories contain some things you shouldn’t use -## <a name="legacy-disclaimer"></a>The legacy API directories contain some things you shouldn’t use +The legacy API directories, in addition to things that genuinely should be part +of the API, also contain things that should *not* be part of the API. We are in +the process of moving the good stuff to the `api` directory tree, and will +remove directories from the legacy list once they no longer contain anything +that should be in the API. -The legacy API directories, in addition to things that genuinely -should be part of the API, also contain things that should *not* be -part of the API. We are in the process of moving the good stuff to the -`api` directory tree, and will remove directories from the legacy list -once they no longer contain anything that should be in the API. +In other words, if you find things in the legacy API directories that don’t seem +like they belong in the WebRTC native API, don’t grow too attached to them. -In other words, if you find things in the legacy API directories that -don’t seem like they belong in the WebRTC native API, -don’t grow too attached to them. +## All these worlds are yours—except Europa -## All these worlds are yours—except Europa - -In the API headers, or in files included by the API headers, there are -types, functions, namespaces, etc. that have `impl` or `internal` in -their names (in various styles, such as `CamelCaseImpl`, -`snake_case_impl`). They are not part of the API, and may change -incompatibly at any time; do not use them. +In the API headers, or in files included by the API headers, there are types, +functions, namespaces, etc. that have `impl` or `internal` in their names (in +various styles, such as `CamelCaseImpl`, `snake_case_impl`). They are not part +of the API, and may change incompatibly at any time; do not use them. # Preprocessor macros @@ -75,6 +71,7 @@ code. ## `WEBRTC_EXCLUDE_BUILT_IN_SSL_ROOT_CERTS` + If you want to ship your own set of SSL certificates and inject them into WebRTC PeerConnections, you will probably want to avoid to compile and ship WebRTC's default set of SSL certificates. @@ -85,14 +82,15 @@ macro for you. ## `WEBRTC_EXCLUDE_METRICS_DEFAULT` + If you want to provide your own implementation of `webrtc::metrics` functions (more info [here][metrics_h]) you will have to exclude WebRTC's default implementation. You can achieve this by defining the preprocessor macro `WEBRTC_EXCLUDE_METRICS_DEFAULT`. If you use GN, you can just set the GN -argument `rtc_exclude_metrics_default` to true and GN will define the -macro for you. +argument `rtc_exclude_metrics_default` to true and GN will define the macro for +you. +[discuss-webrtc]: https://groups.google.com/forum/#!forum/discuss-webrtc [metrics_h]: https://webrtc.googlesource.com/src/+/main/system_wrappers/include/metrics.h -
diff --git a/pc/g3doc/dtls_transport.md b/pc/g3doc/dtls_transport.md index b567338..0b7024b 100644 --- a/pc/g3doc/dtls_transport.md +++ b/pc/g3doc/dtls_transport.md
@@ -1,13 +1,14 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *--> + +<!--* freshness: {owner: 'danilchap' reviewed: '2026-06-17'} *--> ## Overview WebRTC uses DTLS in two ways: -* to negotiate keys for SRTP encryption using - [DTLS-SRTP](https://www.rfc-editor.org/info/rfc5763) -* as a transport for SCTP which is used by the Datachannel API +- to negotiate keys for SRTP encryption using + [DTLS-SRTP](https://www.rfc-editor.org/info/rfc5763) +- as a transport for SCTP which is used by the Datachannel API The W3C WebRTC API represents this as the [DtlsTransport](https://w3c.github.io/webrtc-pc/#rtcdtlstransport-interface). @@ -33,9 +34,10 @@ ## webrtc::DtlsTransportInternal The [`webrtc::DtlsTransportInternal`][4] class is an interface. Its -implementation is [`webrtc::DtlsTransportInternalImpl`][5]. The `webrtc::DtlsTransportInternalImpl` -sends and receives network packets via an ICE transport. It also demultiplexes -DTLS packets and SRTP packets according to the scheme described in +implementation is [`webrtc::DtlsTransportInternalImpl`][5]. The +`webrtc::DtlsTransportInternalImpl` sends and receives network packets via an +ICE transport. It also demultiplexes DTLS packets and SRTP packets according to +the scheme described in [RFC 5764](https://tools.ietf.org/html/rfc5764#section-5.1.2). ## webrtc::DtlsSrtpTranport @@ -44,10 +46,10 @@ SRTP keys after the DTLS handshake as well as protection and unprotection of SRTP packets via its [`webrtc::SrtpSession`][7]. -[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_transport.h;l=32;drc=6a55e7307b78edb50f94a1ff1ef8393d58218369 -[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=76;drc=34437d5660a80393d631657329ef74c6538be25a -[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=41;drc=34437d5660a80393d631657329ef74c6538be25a -[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/dtls_transport_internal.h;l=63;drc=34437d5660a80393d631657329ef74c6538be25a -[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/base/dtls_transport.h;l=94;drc=653bab6790ac92c513b7cf4cd3ad59039c589a95 -[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=31;drc=c32f00ea9ddf3267257fe6b45d4d79c6f6bcb829 -[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=33;drc=be66d95ab7f9428028806bbf66cb83800bda9241 +[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_transport.h;l=30;drc=031d798a20cc5d9c867598a38632accb20c6effe +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=96;drc=031d798a20cc5d9c867598a38632accb20c6effe +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/dtls_transport_interface.h;l=46;drc=031d798a20cc5d9c867598a38632accb20c6effe +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/dtls/dtls_transport_internal.h;l=49;drc=031d798a20cc5d9c867598a38632accb20c6effe +[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/p2p/dtls/dtls_transport.h;l=137;drc=031d798a20cc5d9c867598a38632accb20c6effe +[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=33;drc=031d798a20cc5d9c867598a38632accb20c6effe +[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=39;drc=031d798a20cc5d9c867598a38632accb20c6effe
diff --git a/pc/g3doc/peer_connection.md b/pc/g3doc/peer_connection.md index 255def1..e114de1 100644 --- a/pc/g3doc/peer_connection.md +++ b/pc/g3doc/peer_connection.md
@@ -1,59 +1,56 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-05-07'} *--> + +<!--* freshness: {owner: 'hbos' reviewed: '2026-06-17'} *--> # PeerConnection and friends -The PeerConnection is the C++-level implementation of the Javascript -object "RTCPeerConnection" from the +The PeerConnection is the C++-level implementation of the Javascript object +"RTCPeerConnection" from the [WEBRTC specification](https://w3c.github.io/webrtc-pc/). Like many objects in WebRTC, the PeerConnection is used via a factory and an observer: - * PeerConnectionFactory, which is created via a static Create method and takes - a PeerConnectionFactoryDependencies structure listing such things as - non-default threads and factories for use by all PeerConnections using - the same factory. (Using more than one factory should be avoided, since - it takes more resources.) - * PeerConnection itself, which is created by the method called - PeerConnectionFactory::CreatePeerConnectionOrError, and takes a - PeerConnectionInterface::RTCConfiguration argument, as well as - a PeerConnectionDependencies (even more factories, plus other stuff). - * PeerConnectionObserver (a member of PeerConnectionDependencies), which - contains the functions that will be called on events in the PeerConnection +- PeerConnectionFactory, which is created via a static Create method and takes a + PeerConnectionFactoryDependencies structure listing such things as non-default + threads and factories for use by all PeerConnections using the same factory. + (Using more than one factory should be avoided, since it takes more + resources.) +- PeerConnection itself, which is created by the method called + PeerConnectionFactory::CreatePeerConnectionOrError, and takes a + PeerConnectionInterface::RTCConfiguration argument, as well as a + PeerConnectionDependencies (even more factories, plus other stuff). +- PeerConnectionObserver (a member of PeerConnectionDependencies), which + contains the functions that will be called on events in the PeerConnection These types are visible in the API. ## Internal structure of PeerConnection and friends -The PeerConnection is, to a large extent, a "God object" - most things -that are done in WebRTC require a PeerConnection. +The PeerConnection is, to a large extent, a "God object" - most things that are +done in WebRTC require a PeerConnection. Internally, it is divided into several objects, each with its own -responsibilities, all of which are owned by the PeerConnection and live -as long as the PeerConnection: +responsibilities, all of which are owned by the PeerConnection and live as long +as the PeerConnection: - * SdpOfferAnswerHandler takes care of negotiating configurations with - a remote peer, using SDP-formatted descriptions. - * RtpTransmissionManager takes care of the lists of RtpSenders, - RtpReceivers and RtpTransceivers that form the heart of the transmission - service. - * DataChannelController takes care of managing the PeerConnection's - DataChannels and its SctpTransport. - * JsepTransportController takes care of configuring the details of senders - and receivers. - * Call does management of overall call state. - * RtcStatsCollector (and its obsolete sibling, StatsCollector) collects - statistics from all the objects comprising the PeerConnection when - requested. +- SdpOfferAnswerHandler takes care of negotiating configurations with a remote + peer, using SDP-formatted descriptions. +- RtpTransmissionManager takes care of the lists of RtpSenders, RtpReceivers and + RtpTransceivers that form the heart of the transmission service. +- DataChannelController takes care of managing the PeerConnection's DataChannels + and its SctpTransport. +- JsepTransportController takes care of configuring the details of senders and + receivers. +- Call does management of overall call state. +- RtcStatsCollector (and its obsolete sibling, LegacyStatsCollector) collects + statistics from all the objects comprising the PeerConnection when requested. -There are a number of other smaller objects that are also owned by -the PeerConnection, but it would take too much space to describe them -all here; please consult the .h files. +There are a number of other smaller objects that are also owned by the +PeerConnection, but it would take too much space to describe them all here; +please consult the .h files. -PeerConnectionFactory owns an object called ConnectionContext, and a -reference to this is passed to each PeerConnection. It is referenced -via an webrtc::scoped_refptr, which means that it is guaranteed to be -alive as long as either the factory or one of the PeerConnections -is using it. - +PeerConnectionFactory owns an object called ConnectionContext, and a reference +to this is passed to each PeerConnection. It is referenced via an +webrtc::scoped_refptr, which means that it is guaranteed to be alive as long as +either the factory or one of the PeerConnections is using it.
diff --git a/pc/g3doc/rtp.md b/pc/g3doc/rtp.md index 83b5223..b2264fd 100644 --- a/pc/g3doc/rtp.md +++ b/pc/g3doc/rtp.md
@@ -1,5 +1,6 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-06-03'} *--> + +<!--* freshness: {owner: 'perkj' reviewed: '2026-06-17'} *--> # RTP in WebRTC @@ -27,9 +28,11 @@ ## Allocation of audio payload types -Audio payload types are assigned from a table by the [PayloadTypeMapper][2] -class. New audio codecs should be allocated in the lower dynamic range [35,63], -starting at 63, to reduce collisions with payload types +Audio payload types are assigned from a table by the [PayloadTypePicker][2] +class. Audio codecs generally prefer the upper dynamic range [96,127] to +maintain compatibility with older WebRTC versions. Redundancy formats like RED +are allocated in the lower dynamic range [35,63], starting at 63, to reduce +collisions with video payload types. ## Allocation of video payload types @@ -47,53 +50,58 @@ Due to the requirement that payload types must be uniquely identifiable when using [BUNDLE](https://datatracker.ietf.org/doc/html/rfc8829) collisions between the assignments of the audio and video payload types may arise. These are -resolved by the [PayloadTypeSuggester][4] interface which will reassign payload type -numbers descending from 127. +resolved by the [PayloadTypeSuggester][4] interface which will reassign payload +type numbers descending from 127. # Bitrate probing Bandwidth estimation sometimes requires sending RTP packets to ramp up the estimate above a certain treshold. WebRTC uses two techniques for that: -* Packets that only consist of RTP padding -* RTX packets +- Packets that only consist of RTP padding +- RTX packets -At the receiving end, both types of probing packets do not interfere with media processing. -After being taken into account for bandwidth estimation, probing packets only consisting -of padding can be dropped and RTX packets act as redundancy. +At the receiving end, both types of probing packets do not interfere with media +processing. After being taken into account for bandwidth estimation, probing +packets only consisting of padding can be dropped and RTX packets act as +redundancy. -Using RTX for probing is generally preferred as padding probes are limited to 256 bytes -of RTP payload which results in a larger number of packets being used for probing which -is a disadvantage from a congestion control point of view. +Using RTX for probing is generally preferred as padding probes are limited to +256 bytes of RTP payload which results in a larger number of packets being used +for probing which is a disadvantage from a congestion control point of view. ## Padding probes -Padding probes consist of RTP packets with header extensions (either abs-send time or -the transport-wide-cc sequence number) and set the RTP "P" bit. The last byte of the -RTP payload which specifies the amount of padding is set to 255 and preceeded by 255 -bytes of all zeroes. See [section 5.1 of RFC3550][1]. -Padding probes use the RTX RTP stream (i.e. payload type, sequence number and timestamp) -when RTX is negotiated or share the same RTP stream as the media packets otherwise. +Padding probes consist of RTP packets with header extensions (either abs-send +time or the transport-wide-cc sequence number) and set the RTP "P" bit. The last +byte of the RTP payload which specifies the amount of padding is set to 255 and +preceeded by 255 bytes of all zeroes. See [section 5.1 of RFC3550][1]. Padding +probes use the RTX RTP stream (i.e. payload type, sequence number and timestamp) +when RTX is negotiated or share the same RTP stream as the media packets +otherwise. Padding probes are used either when -* RTX is not negotiated (such as for audio, less commonly for video) or -* no suitable original packet is found for RTX probing. + +- RTX is not negotiated (such as for audio, less commonly for video) or +- no suitable original packet is found for RTX probing. Padding probes should not be interleaved with packets of a video frame. ## RTX probes -RTX probes are resends of previous packets that use RTX retransmissions specified in -[RFC4588](https://www.rfc-editor.org/rfc/rfc4588) as payload format when negotiated with -the peer. These packets will have a different abs-send-time or transport-wide-cc sequence -number and use the RTX RTP stream (i.e. RTX payload type, sequence number and timestamp) -associated with the media RTP stream. +RTX probes are resends of previous packets that use RTX retransmissions +specified in [RFC4588](https://www.rfc-editor.org/rfc/rfc4588) as payload format +when negotiated with the peer. These packets will have a different abs-send-time +or transport-wide-cc sequence number and use the RTX RTP stream (i.e. RTX +payload type, sequence number and timestamp) associated with the media RTP +stream. -RTX probing uses recently sent RTP packets that have not yet been acknowledged by -the remote side. Sending these packets again has a small chance of being useful when the -original packet is lost and will not affect RTP processing at the receiver otherwise. +RTX probing uses recently sent RTP packets that have not yet been acknowledged +by the remote side. Sending these packets again has a small chance of being +useful when the original packet is lost and will not affect RTP processing at +the receiver otherwise. [1]: https://datatracker.ietf.org/doc/html/rfc3550#section-5.1 -[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/engine/payload_type_mapper.cc;l=25;drc=4f26a3c7e8e20e0e0ca4ca67a6ebdf3f5543dc3f -[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/engine/webrtc_video_engine.cc;l=119;drc=b412efdb780c86e6530493afa403783d14985347 -[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/call/payload_type.h;l=25 +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/call/payload_type_picker.h;l=35;drc=031d798a20cc5d9c867598a38632accb20c6effe +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/engine/webrtc_video_engine.cc;l=206;drc=031d798a20cc5d9c867598a38632accb20c6effe +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/call/payload_type.h;l=26;drc=031d798a20cc5d9c867598a38632accb20c6effe
diff --git a/pc/g3doc/sctp_transport.md b/pc/g3doc/sctp_transport.md index 4bb4912..3dd5fe3 100644 --- a/pc/g3doc/sctp_transport.md +++ b/pc/g3doc/sctp_transport.md
@@ -1,40 +1,38 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-04-13'} *--> + +<!--* freshness: {owner: 'danilchap' reviewed: '2026-06-17'} *--> # SctpTransport ## webrtc::SctpTransport -The [`webrtc::SctpTransport`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/sctp_transport.h;l=33?q=class%20webrtc::SctpTransport) class encapsulates an SCTP association, and exposes a -few properties of this association to the WebRTC user (such as Chrome). +The +[`webrtc::SctpTransport`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/sctp_transport.h;l=40;drc=031d798a20cc5d9c867598a38632accb20c6effe) +class encapsulates an SCTP association, and exposes a few properties of this +association to the WebRTC user (such as Chrome). -The SctpTransport is used to support Datachannels, as described in the [WebRTC -specification for the Peer-to-peer Data -API](https://w3c.github.io/webrtc-pc/#peer-to-peer-data-api). +The SctpTransport is used to support Datachannels, as described in the +[WebRTC specification for the Peer-to-peer Data API](https://w3c.github.io/webrtc-pc/#peer-to-peer-data-api). -The public interface ([`webrtc::SctpTransportInterface`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/sctp_transport_interface.h?q=webrtc::SctpTransportInterface)) exposes an observer -interface where the user can define a callback to be called whenever the state -of an SctpTransport changes; this callback is called on the network thread (as -set during PeerConnectionFactory initialization). +The public interface +([`webrtc::SctpTransportInterface`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/sctp_transport_interface.h;l=143;drc=031d798a20cc5d9c867598a38632accb20c6effe)) +exposes an observer interface where the user can define a callback to be called +whenever the state of an SctpTransport changes; this callback is called on the +network thread (as set during PeerConnectionFactory initialization). The implementation of this object lives in pc/sctp_transport.{h,cc}, and is basically a wrapper around a `webrtc::SctpTransportInternal`, hiding its implementation details and APIs that shouldn't be accessed from the user. -The `webrtc::SctpTransport` is a ref counted object; it should be regarded -as owned by the PeerConnection, and will be closed when the PeerConnection -closes, but the object itself may survive longer than the PeerConnection. +The `webrtc::SctpTransport` is a ref counted object; it should be regarded as +owned by the PeerConnection, and will be closed when the PeerConnection closes, +but the object itself may survive longer than the PeerConnection. ## webrtc::SctpTransportInternal -[`webrtc::SctpTransportInternal`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/sctp/sctp_transport_internal.h?q=webrtc::SctpTransportInternal) owns two objects: The SCTP association object -and the DTLS transport, which is the object used to send and receive messages -as emitted from or consumed by the sctp library. +[`webrtc::SctpTransportInternal`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/media/sctp/sctp_transport_internal.h;l=32;drc=031d798a20cc5d9c867598a38632accb20c6effe) +owns two objects: The SCTP association object and the DTLS transport, which is +the object used to send and receive messages as emitted from or consumed by the +sctp library. See header files for details. - - - - - -
diff --git a/pc/g3doc/srtp.md b/pc/g3doc/srtp.md index cdc1311..0e581fb 100644 --- a/pc/g3doc/srtp.md +++ b/pc/g3doc/srtp.md
@@ -1,5 +1,6 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2021-05-13'} *--> + +<!--* freshness: {owner: 'danilchap' reviewed: '2026-06-17'} *--> # SRTP in WebRTC @@ -8,9 +9,9 @@ [RFC 3711](https://datatracker.ietf.org/doc/html/rfc3711). The key negotiation in WebRTC happens using DTLS-SRTP which is described in -[RFC 5764](https://datatracker.ietf.org/doc/html/rfc5764). The older -[SDES protocol](https://datatracker.ietf.org/doc/html/rfc4568) is implemented -but not enabled by default. +[RFC 5764](https://datatracker.ietf.org/doc/html/rfc5764). The legacy +[SDES protocol](https://datatracker.ietf.org/doc/html/rfc4568) is no longer +supported. Unencrypted RTP can be enabled for debugging purposes by setting the PeerConnections [`disable_encryption`][1] option to true. @@ -19,14 +20,14 @@ The implementation supports the following cipher suites: -* SRTP_AES128_CM_HMAC_SHA1_80 -* SRTP_AEAD_AES_128_GCM -* SRTP_AEAD_AES_256_GCM +- SRTP_AES128_CM_HMAC_SHA1_80 +- SRTP_AEAD_AES_128_GCM +- SRTP_AEAD_AES_256_GCM -The SRTP_AES128_CM_HMAC_SHA1_32 cipher suite is not enabled by default and -off in Chromium. When enabled, it is accepted for audio-only connections if -offered by the other side. It is not actively supported, see [SelectCrypto][2] -for details. +The SRTP_AES128_CM_HMAC_SHA1_32 cipher suite is not enabled by default and off +in Chromium. When enabled, it is accepted for audio-only connections if offered +by the other side. See [`webrtc::CryptoOptions`][2] for details on how to enable +it. The cipher suite ordering allows a non-WebRTC peer to prefer GCM cipher suites, however they are not selected as default by two instances of the WebRTC library. @@ -36,7 +37,7 @@ The [`webrtc::SrtpSession`][3] is providing encryption and decryption of SRTP packets using [`libsrtp`](https://github.com/cisco/libsrtp). Keys will be provided by `SrtpTransport` or `DtlsSrtpTransport` in the [`SetSend`][4] and -[`SetRecv`][5] methods. +[`SetReceive`][5] methods. Encryption and decryption happens in-place in the [`ProtectRtp`][6], [`ProtectRtcp`][7], [`UnprotectRtp`][8] and [`UnprotectRtcp`][9] methods. The @@ -55,14 +56,14 @@ in its base class. It will also become writable only once the DTLS handshake is done. -[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/peer_connection_interface.h;l=1413;drc=f467b445631189557d44de86a77ca6a0c3e2108d -[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/media_session.cc;l=297;drc=3ac73bd0aa5322abee98f1ff8705af64a184bf61 -[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=33;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=40;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=51;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=62;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=69;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[8]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=72;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[9]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=73;drc=be66d95ab7f9428028806bbf66cb83800bda9241 -[10]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_transport.h;l=37;drc=a4d873786f10eedd72de25ad0d94ad7c53c1f68a -[11]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=31;drc=2f8e0536eb97ce2131e7a74e3ca06077aa0b64b3 +[1]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/peer_connection_interface.h;l=1511;drc=031d798a20cc5d9c867598a38632accb20c6effe +[2]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/crypto/crypto_options.h;l=28;drc=031d798a20cc5d9c867598a38632accb20c6effe +[3]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=39;drc=031d798a20cc5d9c867598a38632accb20c6effe +[4]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=53;drc=031d798a20cc5d9c867598a38632accb20c6effe +[5]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=62;drc=031d798a20cc5d9c867598a38632accb20c6effe +[6]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=71;drc=031d798a20cc5d9c867598a38632accb20c6effe +[7]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=74;drc=031d798a20cc5d9c867598a38632accb20c6effe +[8]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=77;drc=031d798a20cc5d9c867598a38632accb20c6effe +[9]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_session.h;l=78;drc=031d798a20cc5d9c867598a38632accb20c6effe +[10]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/srtp_transport.h;l=39;drc=031d798a20cc5d9c867598a38632accb20c6effe +[11]: https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/pc/dtls_srtp_transport.h;l=33;drc=031d798a20cc5d9c867598a38632accb20c6effe
diff --git a/stats/g3doc/stats.md b/stats/g3doc/stats.md index 7fb8934..fccab5a 100644 --- a/stats/g3doc/stats.md +++ b/stats/g3doc/stats.md
@@ -1,9 +1,9 @@ <!-- go/cmark --> -<!--* freshness: {owner: 'hta' reviewed: '2024-01-08'} *--> + +<!--* freshness: {owner: 'hbos' reviewed: '2026-06-17'} *--> # getStats in WebRTC -The WebRTC getStats API is specified in - https://w3c.github.io/webrtc-stats/ -and allows querying information about the current state of a RTCPeerConnection -API and some of its member objects. +The WebRTC getStats API is specified in https://w3c.github.io/webrtc-stats/ and +allows querying information about the current state of a RTCPeerConnection API +and some of its member objects.