.mkv`. The existing file stays untouched until `stop()` has finished the recording. Only then does the recording take its place:
+
+- in one step,
+- with the permissions of the file it replaces,
+- and a symbolic link stays a link, now to the new recording.
+
+A recording that gets no media, or fails before any went into the file, leaves the existing file as it was.
-If the process ends before the stop, the existing file is still there, next to the temporary file with what was recorded so far. If the recording cannot take the place of the existing file when it stops, it stays in the temporary file: `onError` is told, the result is `PARTIAL`, and `getFile()` returns where it is.
+If the process ends before the stop, the existing file is still there. The temporary file beside it holds what was recorded so far.
+
+If the recording cannot take the place of the existing file when it stops, it stays in the temporary file. `onError` is told, the result is `PARTIAL`, and `getFile()` returns where the recording is.
## Containers
@@ -90,13 +88,13 @@ The container follows the file name:
| `.webm` | VP8, VP9, AV1 | Opus | Plays in browsers. |
| `.mp4` | VP9, AV1, H.264, H.265 | Opus | Written fragmented, so it plays up to where a recording was cut short. |
-A name FFmpeg does not know gets Matroska. A track whose codec the file cannot hold, VP8 in MP4 for example, is left out and reported as a warning, and the rest is recorded.
+A name FFmpeg does not know gets Matroska. A track whose codec the file cannot hold, such as VP8 in MP4, is left out and reported as a warning. The rest is recorded.
Matroska has no codec ID of its own for G.711, so it is stored as Windows audio (`A_MS/ACM`), the way FFmpeg itself stores it. Players built on FFmpeg, such as VLC and mpv, play it; some others do not.
## Recording in Segments
-For recordings that run for hours, such as surveillance or support sessions, a recorder can split the recording into segments: files that each play on their own, ended by duration or size, of which it keeps as many as asked.
+A recording that runs for hours, such as surveillance or a support session, can be split into segments. Each segment is a file that plays on its own, and ends at a duration or size. The recorder keeps as many segments as asked.
```java
SegmentOptions segments = SegmentOptions.builder(Paths.get("recordings", "camera-%05d.mkv"))
@@ -121,17 +119,21 @@ try (MediaRecorder recorder = new MediaRecorder(segments)) {
}
```
-The file name of the pattern holds the segment's number as `%d`, or zero-padded as `%05d`; a literal percent sign is `%%`. The extension picks the container of all segments, as for a single file. Numbering goes on from the highest number already in the directory, so a recorder started again continues after the last segment, and a segment never empties a file that exists: its number is skipped instead.
+The file name of the pattern holds the segment's number as `%d`, or zero-padded as `%05d`; a literal percent sign is `%%`. The extension picks the container of all segments, as for a single file.
+
+Numbering goes on from the highest number already in the directory, so a recorder started again continues after the last segment. A segment never empties a file that exists: its number is skipped instead.
-- **Every segment begins at a key frame.** Once a segment has reached its duration or size, the recorder asks the video tracks for key frames, and the next segment begins with the first that arrives, usually a fraction of a second later. A segment is therefore somewhat longer or larger than the limit. Without video, a segment ends right at the limit.
-- **Several video tracks lose nothing.** A video track whose key frame comes after the one that began the next segment goes on in the segment before until then, so neither file has a gap. One that sends no key frame within three seconds starts the new segment at its next.
+- **Every segment begins at a key frame.** Once a segment has reached its duration or size, the recorder asks the video tracks for key frames. The next segment begins with the first that arrives, usually a fraction of a second later. A segment is therefore somewhat longer or larger than the limit. Without video, a segment ends right at the limit.
+- **Several video tracks lose nothing.** Every other video track goes on in the segment before until its own key frame arrives, so neither file has a gap. A track that sends no key frame within three seconds starts in the new segment at its next key frame, and nothing of it is recorded until then.
- **Each segment starts at zero.** Its tracks are shifted by the same amount, so they stay in sync, and one segment follows the other without a gap. `MediaRecorderSegment.getStart()` tells where a segment lies in the recording.
-- **A codec change starts a segment.** A file cannot change the codec of a stream, so a track that changes its codec, e.g. after a renegotiation, goes on in the next segment, which begins as soon as the new codec is known. A single file leaves such a track out from then on instead.
-- **A slow disk holds nothing up.** Segments are finished and opened by the recorder's writer thread, with the frames queuing up meanwhile as always, and old segments are deleted on the listener's thread.
+- **A codec change starts a segment.** A file cannot change the codec of a stream. A track that changes its codec, for example after a renegotiation, therefore goes on in the next segment, which begins as soon as the new codec is known. A single file leaves such a track out from then on instead.
+- **A slow disk holds nothing up.** The recorder's writer thread finishes and opens segments, while the frames queue up as always. Old segments are deleted on the listener's thread.
+
+`onSegmentFinished` hears of every segment once it is finished and closed, the last one when the recorder stops. Right after it returns, the oldest segments beyond `maxSegments` or `maxTotalSize` are deleted. A segment to be kept for longer has to be moved or copied by then.
-`onSegmentFinished` hears of every segment once it is finished and closed, the last one when the recorder stops. Right after it returns, the oldest segments beyond `maxSegments` or `maxTotalSize` are deleted, so a segment to be kept for longer has to be moved or copied by then. The newest segment is always kept, and the one being written does not count toward `maxTotalSize`, so the recording takes up to that much and one segment more. `getSegments()` lists the segments that are kept, and `getFile()` returns the last one finished.
+The newest segment is always kept. The one being written does not count toward `maxTotalSize`, so the recording takes up to that much and one segment more. `getSegments()` lists the segments that are kept, and `getFile()` returns the last one finished.
-A write that fails, e.g. because the disk is full, ends the recording as it does for a single file. The segment it happened in is kept as `PARTIAL` if it holds media; one that failed before any went into it is deleted.
+A write that fails, for example because the disk is full, ends the recording as it does for a single file. The segment it happened in is kept as `PARTIAL` if it holds media. A segment that failed before any media went into it is deleted.
## Replay Buffer
@@ -150,9 +152,13 @@ try (ReplayBuffer buffer = new ReplayBuffer(Duration.ofSeconds(30))) {
}
```
-`save` creates the file at once, refusing one that exists, and the buffer's own thread writes the replay, while the buffer goes on taking frames. The future completes on the listener's thread with a `MediaRecorderSegment`, or exceptionally if nothing could be saved, and the file is then deleted. A buffer can save any number of replays, in any container; a track whose codec the container cannot hold is left out of that replay with a warning.
+`save` creates the file at once, and refuses one that exists. The buffer's own thread writes the replay, while the buffer goes on taking frames.
-A replay begins with a key frame of every video track: the last one before the window, so a replay holds at least the window, and a few seconds more. Since WebRTC rarely sends key frames of its own accord, the buffer asks its video tracks for one every third of the window, at least every two seconds and at most every ten. Besides the window, the buffer holds at most 256 MB, or what its constructor is given; beyond that, the oldest frames go first, and a replay is shorter. A track that changes its codec is kept with the new codec from then on.
+The future completes on the listener's thread with a `MediaRecorderSegment`. If nothing could be saved, it completes exceptionally, and the file is deleted. A buffer can save any number of replays, in any container. A track whose codec the container cannot hold is left out of that replay, with a warning.
+
+A replay begins with a key frame of every video track: the last one before the window. A replay therefore holds at least the window, and a few seconds more. WebRTC rarely sends key frames of its own accord, so the buffer asks its video tracks for one every third of the window, at least every two seconds and at most every ten.
+
+Besides the window, the buffer holds at most 256 MB, or what its constructor is given. Beyond that, the oldest frames go first, and a replay is shorter. A track that changes its codec is kept with the new codec from then on.
## Following a Recording
@@ -178,23 +184,30 @@ recorder.setListener(new MediaRecorderListener() {
});
```
-Calls arrive in order on a thread the recorder keeps for them, so a listener may take its time and may even stop the recorder.
+Calls arrive in order, on a thread the recorder keeps for them. A listener may therefore take its time, and may even stop the recorder.
+
+`onError` also hears of a file that cannot be finished or closed when the recorder stops, for example because the last data does not fit on the disk. The recording then ends as `PARTIAL`.
-`onError` also hears of a file that cannot be finished or closed when the recorder stops, e.g. because the last data does not fit on the disk. The recording then ends as `PARTIAL`.
+Running out of native memory while writing ends the recording the same way:
-Running out of native memory while writing ends the recording the same way: `onError` is told, the frames still waiting are dropped, and the file is finished right away, so what is in it still plays. The recording ends as `PARTIAL`, or as `FAILED` if nothing had gone into the file yet.
+- `onError` is told.
+- The frames still waiting are dropped.
+- The file is finished right away, so what is in it still plays.
+- The recording ends as `PARTIAL`, or as `FAILED` if nothing had gone into the file yet.
## How Tracks Are Recorded
-- **Video starts at a key frame.** A decoder can do nothing with the frames before one, so they are skipped. The recorder asks the sender or receiver for a key frame, so recording starts within moments instead of waiting until WebRTC sends one of its own accord, which it rarely does.
-- **The file begins once the tracks are known.** The file header describes every stream, and a stream is only known from its first frames. The file begins once every track has sent some, or once the tracks that have waited three seconds for the rest. A track that sends nothing by then is left out, with a warning.
+- **Video starts at a key frame.** A decoder can do nothing with the frames before one, so they are skipped. The recorder asks the sender or receiver for a key frame. Recording therefore starts within moments, instead of waiting until WebRTC sends one of its own accord, which it rarely does.
+- **The file begins once the tracks are known.** The file header describes every stream, and a stream is only known from its first frames. The file begins once every track has sent some, or once the tracks have waited three seconds for the rest. A track that sends nothing by then is left out, with a warning.
- **Tracks share one timeline.** Each track is placed by when its first frame arrived, and follows its own RTP timestamps from there, so its timing is exact. The tracks of one sender line up within the jitter of the network.
- **One simulcast layer.** A sender with simulcast is recorded at the layer whose frames reach the recorder first.
- **Nothing is lost to a slow disk, up to a point.** Frames queue up in memory for the writer, up to 64 MB. Beyond that, frames are dropped, and video starts over at the next key frame. `getStats()` [tells how much that cost](#measuring-what-was-lost).
## Measuring What Was Lost
-A result of `COMPLETE` means that everything the recorder took went into the file. It says nothing about frames it had to drop before that, and a video gap can come from a single one, since video only goes on from the next key frame. `getStats()` tells what happened, per track and in the order the tracks were added. It can be asked at any time, also after `close()`:
+A result of `COMPLETE` means that everything the recorder took went into the file. It says nothing about frames the recorder had to drop before that. A single dropped frame can leave a video gap, since video only goes on from the next key frame.
+
+`getStats()` tells what happened, per track, in the order the tracks were added. It can be asked at any time, also after `close()`:
```java
MediaRecorderStats stats = recorder.getStats();
@@ -215,13 +228,15 @@ System.out.println("Queue peak: " + stats.getMaxQueuedBytes() + " bytes");
| `getDroppedAwaitingKeyFrame()` | Video frames dropped on the way to the next key frame, since nothing could decode them after what was lost before. |
| `getDroppedFrames()` | All of these together. |
-`getMaxQueuedBytes()` is the most that ever waited for the writer, of all tracks together, and shows how close a recording came to the limit of 64 MB. Frames a track was never meant to record do not count, such as those before its first key frame or those of another simulcast layer.
+`getMaxQueuedBytes()` is the most that ever waited for the writer, of all tracks together. It shows how close a recording came to the limit of 64 MB.
+
+Frames a track was never meant to record do not count, such as those before its first key frame, or those of another simulcast layer.
## Recording an Encrypted Call
-A sender's frames are recorded before an [encoded transform](/guide/advanced/encoded-transforms) runs on them, and a receiver's after it. An end-to-end encrypted call would therefore be recorded in the clear, on either side, so whether it may be is up to the encryption:
+A sender's frames are recorded before an [encoded transform](/guide/advanced/encoded-transforms) runs on them, and a receiver's after it. An end-to-end encrypted call would therefore be recorded in the clear, on either side. Whether it may be is up to the encryption:
-- The transforms of a `KeyProvider` of [End-to-End Encryption](/guide/advanced/end-to-end-encryption) do not allow it by default. `addTrack` refuses their senders, receivers and tracks with an `IllegalStateException`, and a recording that is running gets no further frame of a track once such a transform is set on it.
+- The transforms of a `KeyProvider` of [End-to-End Encryption](/guide/advanced/end-to-end-encryption) do not allow it by default. `addTrack` refuses their senders, receivers and tracks with an `IllegalStateException`. A recording that is running gets no further frame of a track once such a transform is set on it.
- A key provider built with `allowPlaintextRecording(true)` allows it, for an application that records its calls on purpose:
```java
diff --git a/docs/guide/monitoring/logging.md b/docs/guide/monitoring/logging.md
index 664db325..a2f80f78 100644
--- a/docs/guide/monitoring/logging.md
+++ b/docs/guide/monitoring/logging.md
@@ -128,6 +128,3 @@ Logging.addLogSink(Logging.Severity.VERBOSE, new Slf4jLogSink());
```
This approach allows you to integrate WebRTC's native logging with your application's existing logging infrastructure.
-
-## Conclusion
-By using the provided methods and custom log sinks, you can effectively capture, process, and manage log messages to aid in debugging and monitoring your application. Whether you choose to use the native logging capabilities or integrate with existing logging frameworks, the WebRTC logging system is designed to be adaptable to your needs.
diff --git a/docs/guide/monitoring/rtc-stats.md b/docs/guide/monitoring/rtc-stats.md
index 760f6686..bf44c885 100644
--- a/docs/guide/monitoring/rtc-stats.md
+++ b/docs/guide/monitoring/rtc-stats.md
@@ -391,7 +391,3 @@ Different stat types have different attributes. Here are some common attributes
- framesPerSecond (video)
Remember that the available attributes may vary depending on the state of the connection.
-
-## Conclusion
-
-WebRTC statistics provide essential insights into the performance and health of your real-time communications. By leveraging the RTC Stats API in webrtc-java, you can monitor connection quality, diagnose issues, and optimize your application's performance. The ability to collect detailed metrics on packets, jitter, latency, and more allows you to make data-driven decisions.
\ No newline at end of file
diff --git a/docs/guide/networking/peer-connection-config.md b/docs/guide/networking/peer-connection-config.md
index b9000eea..0af54cab 100644
--- a/docs/guide/networking/peer-connection-config.md
+++ b/docs/guide/networking/peer-connection-config.md
@@ -22,7 +22,7 @@ Some settings can be changed later with `setConfiguration()`, starting from `get
| Setting | Effect |
|---|---|
| `iceCandidatePoolSize` | Gathers this many candidates before a connection needs them, so that connecting is faster. Default 0. |
-| `continualGatheringPolicy` | `GATHER_CONTINUALLY` keeps gathering after the first candidates, so that a network that comes up later gets candidates too, which lets a connection survive a network change. Default `GATHER_ONCE`. |
+| `continualGatheringPolicy` | `GATHER_CONTINUALLY` keeps gathering after the first candidates, so that a connection survives a network change (see below). Default `GATHER_ONCE`. |
| `tcpCandidatePolicy` | `DISABLED` gathers no TCP candidates. Default `ENABLED`. |
| `candidateNetworkPolicy` | `LOW_COST` leaves out cellular networks. Default `ALL`. |
| `disableIpv6OnWifi`, `maxIpv6Networks` | Limit IPv6 candidates. Default: IPv6 on Wi-Fi allowed, at most 5 IPv6 networks. |
@@ -30,6 +30,8 @@ Some settings can be changed later with `setConfiguration()`, starting from `get
| `vpnPreference` | Whether to use, avoid, prefer or require VPN connections. Default `DEFAULT`. |
| `surfaceIceCandidatesOnIceTransportTypeChanged` | Signals at once the candidates a change of `iceTransportPolicy` lets through. Default false. |
+With `GATHER_CONTINUALLY`, a network that comes up later gets candidates too, which lets a connection survive a network change.
+
To restrict ports and interfaces, see [Port Allocator Configuration](/guide/networking/port-allocator-config).
## Connectivity Checks
@@ -71,21 +73,28 @@ config.cryptoOptions = crypto;
`cryptexPolicy` encrypts the RTP header extensions and CSRCs as a whole (RFC 9335) where the peer supports it (`NEGOTIATE`) or always (`REQUIRE`).
-`certificates` takes the DTLS certificate a peer connection authenticates with, as an `RTCCertificatePEM`; without one, WebRTC generates a certificate per connection. A certificate that does not parse makes `createPeerConnection()` and `setConfiguration()` throw. The expiration time passed to its constructor is informational: WebRTC takes it from the certificate. The certificates that `getConfiguration()` and `RTCDtlsTransport.getRemoteCertificates()` return carry that time in `getExpires()`, in milliseconds since the Unix epoch, or `RTCCertificatePEM.EXPIRES_UNKNOWN` (-1) if it cannot be read.
+`certificates` takes the DTLS certificate a peer connection authenticates with, as an `RTCCertificatePEM`. Without one, WebRTC generates a certificate per connection. A certificate that does not parse makes `createPeerConnection()` and `setConfiguration()` throw.
+
+The expiration time passed to its constructor is informational: WebRTC takes it from the certificate. The certificates that `getConfiguration()` and `RTCDtlsTransport.getRemoteCertificates()` return carry that time in `getExpires()`, in milliseconds since the Unix epoch. If it cannot be read, `getExpires()` returns `RTCCertificatePEM.EXPIRES_UNKNOWN` (-1).
## Signaling
| Setting | Effect |
|---|---|
| `offerExtmapAllowMixed` | Allows one- and two-byte header extensions to be mixed in offers. Default true. |
-| `enableImplicitRollback` | Rolls a pending local offer back when a remote offer arrives, as perfect negotiation needs. Default false. Pair it with `setLocalDescription(observer)`, which creates the offer or answer itself. |
+| `enableImplicitRollback` | Rolls a pending local offer back when a remote offer arrives, as perfect negotiation needs. Default false. Pair it with `setLocalDescription(observer)`, which creates the offer or answer. |
| `alwaysNegotiateDataChannels` | Includes data channels in offers before any is created. Default false. |
## Changing a Running Connection
A few controls are methods of `RTCPeerConnection` rather than configuration fields, and can be used at any time.
-`setBitrate(min, current, max)` limits the bandwidth all streams sent by the connection may use together, in bits per second. A `null` value leaves that limit as it is, and `current` resets the bandwidth estimate to that value. Limits from the SDP and from each sender's encoding parameters still apply. Values that are negative or not ordered as min ≤ current ≤ max make it throw.
+`setBitrate(min, current, max)` limits the bandwidth that all streams sent by the connection may use together, in bits per second.
+
+- A `null` value leaves that limit as it is.
+- `current` resets the bandwidth estimate to that value.
+- Limits from the SDP and from each sender's encoding parameters still apply.
+- Values that are negative, or not ordered as min ≤ current ≤ max, make it throw.
```java
// Start from 1 Mbps and never use more than 2.5 Mbps.
diff --git a/docs/guide/video/camera-capture.md b/docs/guide/video/camera-capture.md
index 5061c370..3d872aa7 100644
--- a/docs/guide/video/camera-capture.md
+++ b/docs/guide/video/camera-capture.md
@@ -181,11 +181,15 @@ videoTrack.addSink(new VideoTrackSink() {
});
```
-WebRTC holds a lock while it hands a frame to the sinks, and adding or removing a sink takes the same lock. A change made from within a callback therefore takes effect for the sinks at once, while the native sink is added or removed on another thread right after the callback returned. Disposing the track is the one thing a callback cannot do: `dispose()` throws an `IllegalStateException` there, and belongs on another thread.
+WebRTC holds a lock while it hands a frame to the sinks, and adding or removing a sink takes the same lock. A change made from within a callback therefore takes effect for the sinks at once. The native sink is added or removed on another thread, right after the callback returned.
+
+Disposing the track is the one thing a callback cannot do: `dispose()` throws an `IllegalStateException` there, and belongs on another thread.
### Sharing Frames Between Sinks
-By default each sink gets an I420 copy of each frame of its own, which it may write into without the other sinks or the encoder seeing it. That costs a full copy of the pixels per frame and sink: at 1080p and 30 frames a second about 89 MiB a second, for each sink. A sink that only reads the frames can share them instead:
+By default, each sink gets an I420 copy of each frame of its own, which it may write into without the other sinks or the encoder seeing it.
+
+That costs a full copy of the pixels per frame and sink: at 1080p and 30 frames a second, about 89 MiB a second for each sink. A sink that only reads the frames can share them instead:
```java
import dev.onvoid.webrtc.media.video.VideoFrameAccess;
@@ -193,7 +197,10 @@ import dev.onvoid.webrtc.media.video.VideoFrameAccess;
videoTrack.addSink(previewSink, VideoFrameAccess.SHARED);
```
-A shared sink gets the pixels the source handed out, without a copy, which the other shared sinks and the encoder use as well. The planes of its `NativeI420Buffer` are read-only, so a write throws a `ReadOnlyBufferException`; a sink that wants to change a frame takes a writable copy with `frame.copy()`. The frames may come from a pool of the decoder or capturer, so a shared sink should not hold on to them for long: keep a copy instead, and release the frame.
+A shared sink gets the pixels the source handed out, without a copy. The other shared sinks and the encoder use the same pixels.
+
+- The planes of its `NativeI420Buffer` are read-only, so a write throws a `ReadOnlyBufferException`. A sink that wants to change a frame takes a writable copy with `frame.copy()`.
+- The frames may come from a pool of the decoder or capturer, so a shared sink should not hold on to them for long. Keep a copy instead, and release the frame.
### Receiving Remote Video Frames
@@ -331,7 +338,9 @@ Note that scaling is a computationally expensive operation, especially for high-
### Changing Frames Before They Are Sent
-A `VideoProcessor` sits between a camera or desktop source and its tracks, so it can change what is sent and shown: blur a background, draw an overlay, mirror the picture. The source passes each frame to `onFrameCaptured()` after adapting it to what its tracks ask for, so frames already have the size and rate that will be sent. The processor delivers the frames to send to the sink it gets in `setSink()`: the same frame, a new one, or none to drop it.
+A `VideoProcessor` sits between a camera or desktop source and its tracks, so it can change what is sent and shown: blur a background, draw an overlay, mirror the picture.
+
+The source passes each frame to `onFrameCaptured()` after adapting it to what its tracks ask for, so frames already have the size and rate that will be sent. The processor delivers the frames to send to the sink it gets in `setSink()`: the same frame, a new one, or none to drop it.
```java
videoSource.setVideoProcessor(new VideoProcessor() {
@@ -377,9 +386,3 @@ When implementing camera capture in your application, consider these best practi
5. **Properly manage resources**: Always stop and dispose of video sources when they're no longer needed.
6. **Handle device changes**: Implement device change listeners to handle cameras being connected or disconnected.
7. **Consider privacy concerns**: In some applications, you may need to request permission to use the camera.
-
-## Conclusion
-
-This guide has demonstrated how to set up a WebRTC peer connection with camera video capture capabilities and how to receive and process both local and remote video frames.
-
-Camera capture is essential for video conferencing applications, video chat, remote interviews, and any other applications where face-to-face communication is important.
\ No newline at end of file
diff --git a/docs/guide/video/custom-video-source.md b/docs/guide/video/custom-video-source.md
index 18178dc7..4a97ab1e 100644
--- a/docs/guide/video/custom-video-source.md
+++ b/docs/guide/video/custom-video-source.md
@@ -73,7 +73,13 @@ videoSource.pushFrame(frame);
frame.release();
```
-A frame can also carry a `VideoFrameBuffer` of your own. The source takes its pixels from `toI420()`: a `NativeI420Buffer` returned there is used as it is, and any other `I420Buffer` is copied, so its planes have to be direct byte buffers that are as large as their strides and the height require. A buffer that does not fit its description is rejected with a `RuntimeException`. `VideoFrame.copy()` works the same way, and always returns a frame with a `NativeI420Buffer`.
+A frame can also carry a `VideoFrameBuffer` of your own. The source takes its pixels from `toI420()`:
+
+- A `NativeI420Buffer` returned there is used as it is.
+- Any other `I420Buffer` is copied. Its planes have to be direct byte buffers, as large as their strides and the height require.
+- A buffer that does not fit its description is rejected with a `RuntimeException`.
+
+`VideoFrame.copy()` works the same way, and always returns a frame with a `NativeI420Buffer`.
## Video Format Considerations
@@ -82,7 +88,8 @@ When pushing video frames, you need to consider the following:
### Resolution
- Common resolutions: 320x240, 640x480, 1280x720, 1920x1080
- Higher resolutions require more bandwidth and processing power
-- Push frames at their full size: when the bitrate cannot carry them, the source scales them down (and, if asked, drops some) before they reach the encoder, the way a camera source does, and scales back up once the bandwidth allows. Local sinks on the track see the adapted frames too.
+- Push frames at their full size. When the bitrate cannot carry them, the source scales them down before they reach the encoder, and, if asked, drops some. It does so the way a camera source does, and scales back up once the bandwidth allows.
+- Local sinks on the track see the adapted frames too.
### Frame Rate
- Common frame rates: 15, 24, 30, 60 fps
@@ -149,7 +156,9 @@ public class VideoStreamer {
### Keeping the Source's Own Timing
-`pushFrame(VideoFrame)` treats a frame as captured at the moment of the call, so the timing that reaches the other peer is the timing of your pushing thread. For a live source such as a camera that is exactly right. For a source that has timing of its own, such as a video file, it is not: every hiccup of the executor above ends up in the stream, and audio pushed alongside drifts out of sync with the video.
+`pushFrame(VideoFrame)` treats a frame as captured at the moment of the call. The timing that reaches the other peer is therefore the timing of your pushing thread.
+
+For a live source such as a camera, that is exactly right. For a source with timing of its own, such as a video file, it is not. Every hiccup of the executor above ends up in the stream, and audio pushed alongside drifts out of sync with the video.
Pass the capture time instead:
@@ -217,9 +226,3 @@ videoSource.dispose();
// If you're using a scheduled executor for pushing frames
videoStreamer.stop();
```
-
-## Conclusion
-
-The `CustomVideoSource` provides a flexible way to integrate external video sources with WebRTC. By understanding the video format parameters and properly managing the video frame flow, you can create applications that use custom video from virtually any source.
-
-For more information on video processing and other WebRTC features, refer to the additional guides in the documentation.
\ No newline at end of file
diff --git a/docs/guide/video/desktop-capture.md b/docs/guide/video/desktop-capture.md
index 09cf1421..b9616c52 100644
--- a/docs/guide/video/desktop-capture.md
+++ b/docs/guide/video/desktop-capture.md
@@ -188,22 +188,19 @@ windowCapturer.dispose();
### Capturing on macOS
-On macOS 14 and newer, screens and windows are captured with ScreenCaptureKit; older releases use the earlier Core Graphics capture. Both need the app to have Screen Recording permission (System Settings → Privacy & Security → Screen & System Audio Recording). Without it, the windows of other apps are listed without their titles and their content cannot be captured. Windows of the app's own process need no permission, and are captured with Core Graphics.
+On macOS 14 and newer, screens and windows are captured with ScreenCaptureKit; older releases use the earlier Core Graphics capture. Both need the app to have Screen Recording permission (System Settings → Privacy & Security → Screen & System Audio Recording).
-While a captured window is minimized or hidden, its last image repeats. When it is closed, capture stops.
+Without that permission, the windows of other apps are listed without their titles, and their content cannot be captured. Windows of the app's own process need no permission, and are captured with Core Graphics.
-## Conclusion
+While a captured window is minimized or hidden, its last image repeats. When it is closed, capture stops.
-This guide has demonstrated how to set up a WebRTC peer connection with desktop video capture capabilities.
-When implementing desktop capture in your application, remember to:
+## Best Practices
- Always dispose of resources properly to prevent memory leaks
- Periodically refresh source lists to handle dynamic changes in available screens and windows
- Consider the performance implications of higher resolutions and frame rates
- Handle potential permission requirements on different operating systems
-Desktop capture is particularly useful for screen sharing applications, remote assistance tools, collaborative workspaces, and educational platforms where visual content sharing is essential.
-
## Sharing system audio
Add a [`SystemAudioSource`](/guide/audio/system-audio-source) audio track to share
diff --git a/docs/tools/audio/voice-activity-detector.md b/docs/tools/audio/voice-activity-detector.md
index f1fdd913..3a3b04f7 100644
--- a/docs/tools/audio/voice-activity-detector.md
+++ b/docs/tools/audio/voice-activity-detector.md
@@ -220,13 +220,11 @@ sinks. Its speech comes from a listener on the factory, see
[`AudioRecorder`](/tools/audio/audio-recorder) captures a microphone on its
own, apart from any peer connection.
-The adapter invokes the consumer on the thread that delivers the audio: a thread
-of the `onAudio` subscription, or the audio callback thread of a sink. Keep work
-there short. A subscription that falls behind loses the oldest audio beyond its
-buffer, so a detector that must stay live passes a short one, as in
-`onAudio(Duration.ofMillis(200), vad)`. Apply application-level timing to produce stable speech-start/speech-end
-events, rather than toggling a UI or recording for every frame. Audio format
-changes clear the adapter's partial frame and reset its detector.
+The adapter invokes the consumer on the thread that delivers the audio: a thread of the `onAudio` subscription, or the audio callback thread of a sink. Keep work there short.
+
+- A subscription that falls behind loses the oldest audio beyond its buffer. A detector that must stay live therefore passes a short one, as in `onAudio(Duration.ofMillis(200), vad)`.
+- Apply application-level timing to produce stable speech-start and speech-end events, rather than toggling a UI or recording for every frame.
+- Audio format changes clear the adapter's partial frame, and reset its detector.
## Related guides
diff --git a/docs/tools/video/video-buffer-converter.md b/docs/tools/video/video-buffer-converter.md
index 1e3b243d..84422546 100644
--- a/docs/tools/video/video-buffer-converter.md
+++ b/docs/tools/video/video-buffer-converter.md
@@ -37,7 +37,7 @@ Consult the FourCC enum in your version for the complete list.
## Buffer sizing
-Frames are stored without row padding, except where a format groups pixels in pairs: a YUY2 or UYVY row, and an NV12 or NV21 chroma row, always ends with a whole pair, so an odd width is rounded up to the next pair. A buffer must hold at least:
+Frames are stored without row padding, except where a format groups pixels in pairs. A YUY2 or UYVY row, and an NV12 or NV21 chroma row, always ends with a whole pair, so an odd width is rounded up to the next pair. A buffer must hold at least:
- `ARGB`, `BGRA`, `ABGR`, `RGBA`: `width * height * 4` bytes
- `BG24`: `width * height * 3` bytes
- `I420`, `NV12`, `NV21`: `width * height + 2 * ((width + 1) / 2) * ((height + 1) / 2)` bytes
diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java
index 4e8aa89f..b1612132 100644
--- a/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java
+++ b/webrtc/src/main/java/dev/onvoid/webrtc/RTCRtpSender.java
@@ -232,10 +232,6 @@ public RTCEncodedVideoFrameInjector createEncodedVideoFrameInjector(
/**
* Creates an injector that sends audio frames that are already encoded
* on this sender, in place of a track.
- *
- * Do not inject audio through a factory that sends audio captured by its
- * audio device module: WebRTC passes captured audio to every audio sender
- * that sends, and it would drive the injecting sender as well.
*
* @param observer The observer for the sender's target bitrate changes,
* or {@code null} for none.