Skip to content

docs: write the guides in shorter sentences - #595

Merged
devopvoid merged 37 commits into
docs/restructurefrom
docs/plain-language
Nov 13, 2026
Merged

devopvoid merged 37 commits into
docs/restructurefrom
docs/plain-language

Conversation

@devopvoid

@devopvoid devopvoid commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Builds on #594. Rewrites the guides in shorter sentences, with sequences as numbered lists and rules as bullet lists. One commit per page; code blocks are unchanged. The conclusion sections, which restated the page, are gone; the advice two of them held stays as Best Practices.

Corrections found along the way:

  • H.265 is offered by the hardware factories on every platform where the GPU handles it, not only on Macs.
  • The audio of a media file is pushed audio, which works in every audio mode, not only CUSTOM and HEADLESS.
  • The warning against injecting audio through a factory that sends device audio is gone, here and in the Javadoc of RTCRtpSender: since feat: send device-captured and pushed audio from one factory #571 every audio sender gets the audio of its own track.
  • A failed device query, also for an unavailable audio backend, throws MediaException rather than coming back empty (Client API Design).

Same content: long sentences split, sequences as numbered lists, rules as bullet lists.
Same content: platforms and measurements as tables, rules as lists, and the page names its client API counterpart.
Same content: long sentences split, rules and failure cases as lists.
Long sentences split. Also corrects which factories offer H.265: the hardware factories on every platform where the GPU handles it, not only on Macs.
Same content, with one point made exact: a video track without a key frame within three seconds starts the new segment at its next key frame.
Same content: long table cells and rules moved into lists below the tables.
Also corrects the audio of a media file: it is pushed audio, which works in every audio mode, not only CUSTOM and HEADLESS.
Same content: recovery rules and JSON rules as lists.
Same content: rules as lists, long paragraphs split.
Same content: the rules of disposal as a list.
Same content: the exceptions of the thread table as a list below it, and screens() and windows() named as asking the system on every call.
Same content: the memory rules of the video views and the speech detection settings as lists.
Since #571 every audio sender gets the audio of its own track, so captured audio no longer reaches an injecting sender.
Same content: the client API first, the core API after it, and the rules of starting, stopping and feedback as lists.
Same content: content hints and layers as lists.
Same content, rules about buffers as a list.
Same content, long paragraphs split.
Same content, long table cells and paragraphs split.
Same content, long paragraphs split.
Same content, the effects of the old capture path as a list.
Same content, long paragraphs split.
Same content, the receive limit and message previews as lists.
@devopvoid
devopvoid added this pull request to stack #596 November 13, 2026 00:54
A failed device query, also for an unavailable audio backend, throws MediaException; it does not come back empty. Also names screens() and windows() as asking the system on every call, and lists the blocking calls below the thread table.
They restated the page. The advice two of them held stays as Best Practices, and the CPU note of audio processing joins its Best Practices.
@devopvoid
devopvoid merged commit fde815a into main Nov 13, 2026
27 checks passed
@devopvoid
devopvoid deleted the docs/plain-language branch November 13, 2026 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant