Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/.vitepress/nav.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ export const navbar: DefaultTheme.NavItem[] = [
link: '/tools',
},
{
text: 'Client API Design',
link: '/guide/client-api-design',
text: 'Client API',
link: '/guide/client-api',
},
{
text: IS_NEXT ? PROJECT_VARS.VERSION_SNAPSHOT : PROJECT_VARS.VERSION,
Expand Down
30 changes: 26 additions & 4 deletions docs/.vitepress/sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,24 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
text: 'Introduction',
collapsed: false,
items: [
{ text: 'What is webrtc-java?', link: '/introduction' },
{ text: 'Introduction', link: '/introduction' },
{ text: 'Getting Started', link: '/get-started' },
{ text: 'Core API', link: '/core-api' },
],
},
{
text: 'Client API',
collapsed: false,
items: [
{ text: 'Client API', link: '/client-api' },
{ text: 'Client API Design', link: '/client-api-design' },
{ text: 'Peers and Signaling', link: '/client/peers' },
{ text: 'Threads', link: '/client/threads' },
{ text: 'Sending Media', link: '/client/sending-media' },
{ text: 'Receiving Media', link: '/client/receiving-media' },
{ text: 'Transforms and Encryption', link: '/client/transforms' },
{ text: 'Data Channels', link: '/client/data-channels' },
{ text: 'WHIP and WHEP', link: '/client/whip-whep' },
{ text: 'Statistics and Call Checks', link: '/client/statistics' },
],
},
{
Expand Down Expand Up @@ -85,6 +99,14 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
{ text: 'GraalVM Native Image', link: '/advanced/native-image' },
],
},
{
text: 'Background',
collapsed: false,
items: [
{ text: 'Client API Design', link: '/client-api-design' },
{ text: 'Build Notes', link: '/build' },
],
},
]
}

Expand All @@ -97,7 +119,7 @@ function sidebarTools(): DefaultTheme.SidebarItem[] {
{ text: 'Audio Converter', link: '/audio/audio-converter' },
{ text: 'Audio Recorder', link: '/audio/audio-recorder' },
{ text: 'Audio Player', link: '/audio/audio-player' },
{ text: 'Voice Activity Detector', link: '/audio/voice-activity-detector' },
{ text: 'Voice Activity Detection', link: '/audio/voice-activity-detector' },
],
},
{
Expand All @@ -113,7 +135,7 @@ function sidebarTools(): DefaultTheme.SidebarItem[] {
collapsed: false,
items: [
{ text: 'Screen Capturer', link: '/desktop/screen-capturer' },
{ text: 'Window Capturer ', link: '/desktop/window-capturer' },
{ text: 'Window Capturer', link: '/desktop/window-capturer' },
{ text: 'Power Management', link: '/desktop/power-management' },
],
},
Expand Down
24 changes: 24 additions & 0 deletions docs/.vitepress/theme/ApiNote.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<script setup lang="ts">
import { withBase } from 'vitepress'

// Tells the reader of a page that shows only the core API which API it is, and
// where the client API page that does the same is. It goes right below the
// title of a page that shows only the core API.
defineProps<{
// The client API page or section that covers the same task.
client?: string
// Its title, as the link text.
title?: string
}>()
</script>

<template>
<div class="info custom-block">
<p class="custom-block-title">Core API</p>
<p>
This page uses the core API in <code>dev.onvoid.webrtc</code>, which leaves negotiation, threads and
cleanup to you.
<template v-if="client">For the client API, see <a :href="withBase(client)">{{ title }}</a>.</template>
</p>
</div>
</template>
2 changes: 1 addition & 1 deletion docs/.vitepress/theme/DocsHome.vue
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ async function copyDependency() {
const paths = [
{ label: 'START BUILDING', title: 'Your first connection', description: 'Install the library, connect two peers, and send your first audio and video.', link: '/guide/get-started', action: 'Get started', icon: 'code' },
{ label: 'EXPLORE MEDIA', title: 'Bring your media', description: 'Capture a camera, share a screen, play an RTSP stream, or record a call.', link: '/guide/media/media-devices', action: 'Explore media', icon: 'video' },
{ label: 'CONNECT TO MEDIA SERVERS', title: 'WHIP / WHEP', description: 'Publish live audio and video with WHIP, or receive streams with WHEP over HTTP.', link: '/guide/client-api#whip-and-whep', action: 'Explore WHIP / WHEP', icon: 'arrows' },
{ label: 'CONNECT TO MEDIA SERVERS', title: 'WHIP / WHEP', description: 'Publish live audio and video with WHIP, or receive streams with WHEP over HTTP.', link: '/guide/client/whip-whep', action: 'Explore WHIP / WHEP', icon: 'arrows' },
]
const topics = [
{ title: 'Audio & video capture', detail: 'Connect microphones, cameras, and custom sources.', link: '/guide/media/media-devices', icon: 'video' },
Expand Down
32 changes: 31 additions & 1 deletion docs/.vitepress/theme/index.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
// https://vitepress.dev/guide/custom-theme
import { h } from 'vue'
import type { Theme } from 'vitepress'
import { inBrowser, type Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import NextBanner from './NextBanner.vue'
import DocsHome from './DocsHome.vue'
import ThreadingDiagram from './ThreadingDiagram.vue'
import ApiNote from './ApiNote.vue'
import { movedSection } from './moved'
import './style.css'

export default {
Expand All @@ -19,5 +21,33 @@ export default {
enhanceApp({ app, router, siteData }) {
app.component('DocsHome', DocsHome)
app.component('ThreadingDiagram', ThreadingDiagram)
app.component('ApiNote', ApiNote)

// A link to a section that moved to a page of its own goes on to that page,
// in place of the old address, so that going back does not come here again.
if (inBrowser) {
const base = siteData.value.base
const target = (url: URL) => {
const path = '/' + url.pathname.slice(base.length)
const moved = movedSection(path, url.hash)
return moved && base + moved.slice(1)
}

// The page that was served is the old one, so the new one is loaded in its place.
const first = target(new URL(location.href))
if (first) {
location.replace(first)
}

const previous = router.onBeforeRouteChange
router.onBeforeRouteChange = (to) => {
const moved = target(new URL(to, location.href))
if (moved) {
router.go(moved, { replace: true })
return false
}
return previous?.(to)
}
}
}
} satisfies Theme
56 changes: 56 additions & 0 deletions docs/.vitepress/theme/moved.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
// Sections that moved to pages of their own. A link to one of them, from a page
// of an earlier release or from another site, is sent on to where it is now.
export const MOVED_SECTIONS: Record<string, Record<string, string>> = {
'/guide/client-api': {
'peers-and-signaling': '/guide/client/peers',
'signaling': '/guide/client/peers#signaling',
'polite-and-impolite-peers': '/guide/client/peers#polite-and-impolite-peers',
'peer-state': '/guide/client/peers#peer-state',
'automatic-ice-recovery': '/guide/client/peers#automatic-ice-recovery',
'threads': '/guide/client/threads',
'limiting-threads': '/guide/client/threads#limiting-threads',
'handlers-on-the-ui-thread': '/guide/client/threads#handlers-on-the-ui-thread',
'don-t-wait-in-a-handler': '/guide/client/threads#don-t-wait-in-a-handler',
'sending-media': '/guide/client/sending-media',
'sending-a-media-file': '/guide/client/sending-media#sending-a-media-file',
'pushing-video-and-audio': '/guide/client/sending-media#pushing-video-and-audio',
'controlling-senders-and-tracks': '/guide/client/sending-media#controlling-senders-and-tracks',
'switching-cameras': '/guide/client/sending-media#switching-cameras',
'devices': '/guide/client/sending-media#devices',
'receiving-media': '/guide/client/receiving-media',
'video-frames': '/guide/client/receiving-media#video-frames',
'audio': '/guide/client/receiving-media#audio',
'receiving-without-sending': '/guide/client/receiving-media#receiving-without-sending',
'recording': '/guide/client/receiving-media#recording',
'encoded-transforms': '/guide/client/transforms',
'data-channels': '/guide/client/data-channels',
'whip-and-whep': '/guide/client/whip-whep',
'manual-negotiation': '/guide/client/peers#manual-negotiation',
'statistics': '/guide/client/statistics',
'diagnosis-and-quality-events': '/guide/client/statistics#diagnosis-and-quality-events',
'checking-before-a-call': '/guide/client/statistics#checking-before-a-call',
},
'/guide/get-started': {
'using-the-core-api': '/guide/core-api',
'initialize-the-webrtc-library': '/guide/core-api#initialize-the-webrtc-library',
'create-a-peer-connection': '/guide/core-api#create-a-peer-connection',
'signaling': '/guide/core-api#signaling',
'letting-the-peer-connection-create-the-description': '/guide/core-api#letting-the-peer-connection-create-the-description',
'adding-candidates-and-knowing-the-outcome': '/guide/core-api#adding-candidates-and-knowing-the-outcome',
'media-streams': '/guide/core-api#media-streams',
'accessing-media-devices': '/guide/core-api#accessing-media-devices',
'creating-media-tracks': '/guide/core-api#creating-media-tracks',
'adding-tracks-to-peer-connection': '/guide/core-api#adding-tracks-to-peer-connection',
'receiving-tracks': '/guide/core-api#receiving-tracks',
'cleanup': '/guide/core-api#cleanup',
'finding-objects-that-were-never-disposed': '/guide/core-api#finding-objects-that-were-never-disposed',
},
}

// Where the section a path and hash name moved to, relative to the site's base, if it did.
export function movedSection(path: string, hash: string): string | undefined {
const page = path.replace(/\.html$/, '').replace(/\/$/, '')
const anchor = decodeURIComponent(hash.replace(/^#/, ''))

return anchor ? MOVED_SECTIONS[page]?.[anchor] : undefined
}
2 changes: 2 additions & 0 deletions docs/guide/advanced/audio-codecs.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Audio Codecs

<ApiNote client="/guide/client-api#the-runtime" title="The Runtime" />

A `PeerConnectionFactory` decides which audio codecs it can send and receive through an audio encoder factory and an audio decoder factory. Unless told otherwise it uses all codecs built into WebRTC. This guide explains how to limit them, for example to offer only Opus, or to put a codec first that a remote endpoint expects.

The API lives in the `dev.onvoid.webrtc.media.audio.codec` package.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/advanced/encoded-transforms.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ The transform belongs to the native sender or receiver, not to the Java object:

### With the Client API

The [Client API](/guide/client-api#encoded-transforms) takes the same transforms. Those of the peer options apply to every sender and remote track of the peer, and are set before the first frame passes either way:
The [Client API](/guide/client/transforms) takes the same transforms. Those of the peer options apply to every sender and remote track of the peer, and are set before the first frame passes either way:

```java
PeerOptions.builder()
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/advanced/end-to-end-encryption.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ The frame format covers VP8, VP9, AV1 and every audio codec. WebRTC's packetizer

H.264 and H.265 frames are split at their start codes before they are sent, which a ciphertext would contain anywhere, so they are dropped with `UNSUPPORTED_CODEC`. A call has to negotiate them away, which matters on macOS in particular, where WebRTC prefers H.264 through VideoToolbox:

- A peer of the client API with `e2ee(keys)` does so by itself: it offers and answers only VP8, VP9 and AV1 video, in WebRTC's order. `videoCodecs(...)` of the [WHIP and WHEP](/guide/client-api#whip-and-whep) builders still picks among them, and fails the session with a `ConfigurationException` if it names none of them.
- A peer of the client API with `e2ee(keys)` does so by itself: it offers and answers only VP8, VP9 and AV1 video, in WebRTC's order. `videoCodecs(...)` of the [WHIP and WHEP](/guide/client/whip-whep) builders still picks among them, and fails the session with a `ConfigurationException` if it names none of them.
- Without the client API, call `setCodecPreferences` on each video transceiver with the codecs for which `KeyProvider.supportsCodec(codec.getMimeType())` is true, keeping `rtx`, `red` and `ulpfec`.

## Recording
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/advanced/field-trials.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Field Trials

<ApiNote client="/guide/client-api#the-runtime" title="The Runtime" />

WebRTC uses field trials to gate experimental features and tune internal behavior (e.g. congestion control, codec selection, message interleaving) without changing the public API. This guide explains how to enable them when creating a `PeerConnectionFactory`.

Field trials are applied once, at `PeerConnectionFactory` creation, and take effect for everything created by that factory (peer connections, tracks, sources). Different `PeerConnectionFactory` instances in the same process may use different field trials.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/advanced/native-image.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ in `src/main/resources/META-INF/native-image/<group>/<artifact>/reflect-config.j

## Example

The [`NativeImageExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/NativeImageExample.java) connects two peers in one process and checks that video, audio, data channel messages, statistics and log messages arrive. It exits with status 0 only if they all did, and builds with `--exact-reachability-metadata`, which needs GraalVM 24 or later:
The [`NativeImageExample`](https://github.com/devopvoid/webrtc-java/blob/main/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/NativeImageExample.java) connects two peers in one process and checks that video, audio, data channel messages, statistics and log messages arrive. It exits with status 0 only if they all did, and builds with `--exact-reachability-metadata`, which needs GraalVM 24 or later:

```shell
mvn -pl webrtc-examples -Pnative package
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/advanced/video-codecs.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Video Codecs

<ApiNote client="/guide/client-api#the-runtime" title="The Runtime" />

A `PeerConnectionFactory` decides which video codecs it can send and receive through a video encoder factory and a video decoder factory. Unless told otherwise it uses the codecs built into the library. This guide explains how to replace or extend them: to add a codec WebRTC does not have, to use a hardware encoder reached through another library, or to limit the codecs a factory offers.

The API lives in the `dev.onvoid.webrtc.media.video.codec` package.
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/audio/audio-devices.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Audio Devices

<ApiNote client="/guide/client/sending-media#devices" title="Devices in Sending Media" />

This guide focuses on setting up a peer connection with audio device selection capabilities, which allows you to choose specific microphones and speakers for your WebRTC connection.

## Audio Device Selection
Expand Down
4 changes: 3 additions & 1 deletion docs/guide/audio/audio-processing.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Audio Processing

<ApiNote client="/guide/client-api#the-runtime" title="The Runtime" />

This guide explains how to use the audio processing capabilities provided by the `dev.onvoid.webrtc.media.audio.AudioProcessing` class. The library provides a collection of voice processing components designed for real-time communications software.

## Overview
Expand Down Expand Up @@ -313,7 +315,7 @@ factory.addVoiceActivityListener(new VoiceActivityConfig(0.5, Duration.ofMillis(
factory.removeVoiceActivityListener(listener);
```

It works with the `AudioProcessing` the factory was built with as well as with the one it builds itself. All listeners share one detector, and each decides with the threshold and hangover of its own `VoiceActivityConfig`. Audio arrives while the audio device module records, which WebRTC starts once a peer connection sends a microphone track. A listener must not add or remove a listener. Disposing of the factory removes the listeners it still has. The [Client API](/guide/client-api#audio) offers the same through `LocalAudio.onVoiceActivity`.
It works with the `AudioProcessing` the factory was built with as well as with the one it builds itself. All listeners share one detector, and each decides with the threshold and hangover of its own `VoiceActivityConfig`. Audio arrives while the audio device module records, which WebRTC starts once a peer connection sends a microphone track. A listener must not add or remove a listener. Disposing of the factory removes the listeners it still has. The [Client API](/guide/client/receiving-media#audio) offers the same through `LocalAudio.onVoiceActivity`.

## Statistics

Expand Down
2 changes: 2 additions & 0 deletions docs/guide/audio/custom-audio-source.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Custom Audio Source

<ApiNote client="/guide/client/sending-media#pushing-video-and-audio" title="Pushing Video and Audio" />

This guide explains how to use the `CustomAudioSource` class to push audio data from external sources directly to the WebRTC audio pipeline.

## Overview
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/audio/dtmf-sender.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# DTMF Sender

<ApiNote client="/guide/client/sending-media#controlling-senders-and-tracks" title="Controlling Senders and Tracks" />

This guide explains how to use the DTMF (Dual-Tone Multi-Frequency) sender functionality with the webrtc-java library. DTMF senders allow you to send DTMF tones over WebRTC audio connections, which is useful for interactive voice response (IVR) systems and telephony applications.

## Overview
Expand Down
4 changes: 3 additions & 1 deletion docs/guide/audio/headless-audio.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Headless Audio

<ApiNote client="/guide/client-api#audio-modes" title="Audio Modes" />

The `HeadlessAudioDeviceModule` is a convenience implementation of the `AudioDeviceModule` that uses WebRTC's dummy audio layer. It avoids touching real OS audio devices while still driving the WebRTC render pipeline, which is what delivers received audio to an `AudioTrackSink`. It has no capture path; audio you want to send goes through a `CustomAudioSource`.

This is ideal for:
Expand Down Expand Up @@ -130,7 +132,7 @@ factory.dispose();
- Using a standard `AudioDeviceModule` with `AudioLayer.kDummyAudio` disables actual audio I/O; the audio pipeline is not started for playout and sinks will typically not receive audio frame callbacks. Use this only when you intentionally do not want any audio delivery (e.g., video‑only or fully custom audio).

Related guides:
- [Audio Device Selection](/guide/audio/audio-devices)
- [Audio Devices](/guide/audio/audio-devices)
- [Custom Audio Source](/guide/audio/custom-audio-source)

## Limitations and notes
Expand Down
Loading
Loading