Skip to content

Commit 1772a81

Browse files
devopvoiddevopvoid
committed
docs: add Screen Capturer and Window Capturer guides
1 parent 7d3345b commit 1772a81

File tree

4 files changed

+223
-2
lines changed

4 files changed

+223
-2
lines changed

‎docs/_sidebar.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,10 @@
2828
- [Logging](guide/logging.md)
2929
- Utilities
3030
- [Audio Converter](guide/audio_converter.md)
31-
- [Power Management](guide/power_management.md)
31+
- [Screen Capturer](guide/screen_capturer.md)
32+
- [Window Capturer](guide/window_capturer.md)
3233
- [Voice Activity Detector](guide/voice_activity_detector.md)
34+
- [Power Management](guide/power_management.md)
3335

3436
- [**Build Notes**](build.md)
3537
- [**Changelog**](changelog.md)

‎docs/guide/overview.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,10 @@ This section provides detailed guides for various features of the webrtc-java li
3838
## Utilities
3939

4040
- [Audio Converter](guide/audio_converter.md) - Resample and remix 10 ms PCM frames between different rates and channel layouts
41-
- [Power Management](guide/power_management.md) - Prevent the display from sleeping during desktop capture or presentations
41+
- [Screen Capturer](guide/screen_capturer.md) - Enumerate and capture full desktop screens/monitors
42+
- [Window Capturer](guide/window_capturer.md) - Enumerate and capture individual application windows
4243
- [Voice Activity Detector](guide/voice_activity_detector.md) - Detect speech activity in PCM audio streams
44+
- [Power Management](guide/power_management.md) - Prevent the display from sleeping during desktop capture or presentations
4345

4446
## Additional Resources
4547

‎docs/guide/screen_capturer.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Screen Capturer
2+
3+
The `ScreenCapturer` enumerates and captures full desktop screens/monitors. Use it to list available screens and to drive screen-source selection for desktop capture workflows.
4+
5+
API: `dev.onvoid.webrtc.media.video.desktop.ScreenCapturer`
6+
7+
## Overview
8+
9+
- Purpose: Discover and capture full screens (monitors).
10+
- Pairs with: `VideoDesktopSource` to produce a capturable video track from a selected screen ID.
11+
- Common ops: list screens, select one, configure capture parameters on `DesktopCapturer`, start capture via callback, or pass the ID to `VideoDesktopSource`.
12+
- Resource management: Call `dispose()` when finished to free native resources.
13+
14+
Key methods (inherited from `DesktopCapturer`):
15+
- `List<DesktopSource> getDesktopSources()` – enumerate available screens
16+
- `void selectSource(DesktopSource source)` – choose the screen to capture
17+
- `void setFocusSelectedSource(boolean focus)` – try to focus the selected source during capture
18+
- `void setMaxFrameRate(int maxFrameRate)` – cap the capture FPS
19+
- `void start(DesktopCaptureCallback callback)` – begin capturing; frames are delivered via callback
20+
- `void captureFrame()` – request a single frame (manual capture)
21+
- `void dispose()` – release resources
22+
23+
## Typical usage: enumerate screens
24+
25+
```java
26+
import dev.onvoid.webrtc.media.video.desktop.DesktopSource;
27+
import dev.onvoid.webrtc.media.video.desktop.ScreenCapturer;
28+
import java.util.List;
29+
30+
ScreenCapturer screenCapturer = new ScreenCapturer();
31+
try {
32+
List<DesktopSource> screens = screenCapturer.getDesktopSources();
33+
for (DesktopSource s : screens) {
34+
System.out.printf("Screen: %s (ID: %d)%n", s.title, s.id);
35+
}
36+
}
37+
finally {
38+
screenCapturer.dispose();
39+
}
40+
```
41+
42+
## Selecting a screen and starting capture with a callback
43+
44+
```java
45+
import dev.onvoid.webrtc.media.video.desktop.*;
46+
import dev.onvoid.webrtc.media.video.VideoFrame;
47+
48+
ScreenCapturer capturer = new ScreenCapturer();
49+
try {
50+
// pick the first screen
51+
DesktopSource screen = capturer.getDesktopSources().stream().findFirst()
52+
.orElseThrow(() -> new IllegalStateException("No screens found"));
53+
54+
capturer.selectSource(screen);
55+
capturer.setMaxFrameRate(30);
56+
capturer.setFocusSelectedSource(false);
57+
58+
DesktopCaptureCallback callback = (result, frame) -> {
59+
if (result == DesktopCapturer.Result.SUCCESS && frame != null) {
60+
// process VideoFrame
61+
}
62+
};
63+
64+
capturer.start(callback);
65+
66+
// Optionally trigger ad-hoc capture
67+
capturer.captureFrame();
68+
}
69+
finally {
70+
capturer.dispose();
71+
}
72+
```
73+
74+
## Using with VideoDesktopSource to create a VideoTrack
75+
76+
For most WebRTC pipelines, you will create a `VideoDesktopSource` and set the selected screen ID:
77+
78+
```java
79+
import dev.onvoid.webrtc.media.video.VideoDesktopSource;
80+
import dev.onvoid.webrtc.media.video.desktop.*;
81+
82+
ScreenCapturer sc = new ScreenCapturer();
83+
DesktopSource screen = sc.getDesktopSources().get(0);
84+
85+
VideoDesktopSource vds = new VideoDesktopSource();
86+
vds.setFrameRate(30);
87+
vds.setMaxFrameSize(1920, 1080);
88+
89+
// Select the screen (isWindow = false)
90+
vds.setSourceId(screen.id, false);
91+
92+
// Start the source and use it to create a VideoTrack in your PeerConnection
93+
vds.start();
94+
95+
// ...
96+
97+
// cleanup
98+
vds.stop();
99+
vds.dispose();
100+
sc.dispose();
101+
```
102+
103+
## Integration tips
104+
105+
- If screens can change (hot‑plug monitors), refresh `getDesktopSources()` as needed.
106+
- Use `setMaxFrameRate` to limit capture load on the system.
107+
- Prefer using `VideoDesktopSource` for WebRTC pipelines; keep `ScreenCapturer` for discovery and advanced control.
108+
109+
## Related guides
110+
111+
- [Desktop Capture](guide/desktop_capture.md)
112+
- [Power Management](guide/power_management.md)

‎docs/guide/window_capturer.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Window Capturer
2+
3+
The `WindowCapturer` enumerates and captures individual application windows. Use it to list open windows and to drive window-source selection for desktop capture workflows.
4+
5+
API: `dev.onvoid.webrtc.media.video.desktop.WindowCapturer`
6+
7+
## Overview
8+
9+
- Purpose: Discover and capture specific windows.
10+
- Pairs with: `VideoDesktopSource` to create a video source capturing the chosen window ID.
11+
- Common ops: list windows, select one, configure capture parameters, start capture via callback, or pass the window ID to `VideoDesktopSource`.
12+
- Resource management: Call `dispose()` when finished to free native resources.
13+
14+
Key methods (inherited from `DesktopCapturer`):
15+
- `List<DesktopSource> getDesktopSources()` – enumerate available windows
16+
- `void selectSource(DesktopSource source)` – choose which window to capture
17+
- `void setFocusSelectedSource(boolean focus)` – attempt to focus/raise the selected window
18+
- `void setMaxFrameRate(int maxFrameRate)` – limit the capture frame rate
19+
- `void start(DesktopCaptureCallback callback)` – start capture, frames via callback
20+
- `void captureFrame()` – request a single capture
21+
- `void dispose()` – release resources
22+
23+
## Typical usage: enumerate windows
24+
25+
```java
26+
import dev.onvoid.webrtc.media.video.desktop.DesktopSource;
27+
import dev.onvoid.webrtc.media.video.desktop.WindowCapturer;
28+
import java.util.List;
29+
30+
WindowCapturer windowCapturer = new WindowCapturer();
31+
try {
32+
List<DesktopSource> windows = windowCapturer.getDesktopSources();
33+
for (DesktopSource w : windows) {
34+
System.out.printf("Window: %s (ID: %d)%n", w.title, w.id);
35+
}
36+
}
37+
finally {
38+
windowCapturer.dispose();
39+
}
40+
```
41+
42+
## Selecting a window and starting capture with a callback
43+
44+
```java
45+
import dev.onvoid.webrtc.media.video.desktop.*;
46+
import dev.onvoid.webrtc.media.video.VideoFrame;
47+
48+
WindowCapturer capturer = new WindowCapturer();
49+
try {
50+
DesktopSource window = capturer.getDesktopSources().stream().findFirst()
51+
.orElseThrow(() -> new IllegalStateException("No windows found"));
52+
53+
capturer.selectSource(window);
54+
capturer.setMaxFrameRate(30);
55+
capturer.setFocusSelectedSource(true); // optional
56+
57+
DesktopCaptureCallback callback = (result, frame) -> {
58+
if (result == DesktopCapturer.Result.SUCCESS && frame != null) {
59+
// process VideoFrame for the selected window
60+
}
61+
};
62+
63+
capturer.start(callback);
64+
capturer.captureFrame();
65+
}
66+
finally {
67+
capturer.dispose();
68+
}
69+
```
70+
71+
## Using with VideoDesktopSource to create a VideoTrack
72+
73+
```java
74+
import dev.onvoid.webrtc.media.video.VideoDesktopSource;
75+
import dev.onvoid.webrtc.media.video.desktop.*;
76+
77+
WindowCapturer wc = new WindowCapturer();
78+
DesktopSource window = wc.getDesktopSources().get(0);
79+
80+
VideoDesktopSource vds = new VideoDesktopSource();
81+
vds.setFrameRate(30);
82+
vds.setMaxFrameSize(1280, 720);
83+
84+
// Select the window (isWindow = true)
85+
vds.setSourceId(window.id, true);
86+
87+
vds.start();
88+
89+
// ...
90+
91+
vds.stop();
92+
vds.dispose();
93+
wc.dispose();
94+
```
95+
96+
## Integration tips
97+
98+
- Window availability is dynamic; refresh `getDesktopSources()` if the set of open windows changes.
99+
- Not all OSes allow focusing/raising another app’s window; `setFocusSelectedSource` behavior may vary by platform.
100+
- If the window is minimized or occluded, the captured content may be affected depending on platform.
101+
102+
## Related guides
103+
104+
- [Desktop Capture](guide/desktop_capture.md)
105+
- [Power Management](guide/power_management.md)

0 commit comments

Comments
 (0)