majestic-encoder-tuning: document the reference structure and the fpv block

[widgetii]

Closes a documentation gap that turned out to be wider than one setting.

What was missing

searched	hits before this PR
fpv.refEnhance / fpv.refPred	none
the whole fpv: section — all nine keys	none
video0.svct	none

There are two dozen FPV pages in the wiki and not one documented a single
fpv.* config key. Anyone who found these in a config dump had nothing to read.

What this adds

A new page, Majestic encoder tuning, plus commented svct and fpv: blocks
in the example config and a table-of-contents entry.

The page leads with the reference structure, because that is the setting with a
real decision behind it. refEnhance: 0 with refPred: false makes every P
frame reference the keyframe, so a lost frame costs exactly one frame rather
than corrupting everything up to the next keyframe — measured on a Hi3516CV500,
the frame after a dropped NAL is bit-exact.

What it costs is prediction efficiency, and that decays as the keyframe ages,
which makes gopSize the knob that decides whether this is cheap or ruinous.
Bitrate against keyframe interval is U-shaped, and the minimum moves with
scene motion:

gopSize	moderate motion	fast motion
0.5	0.61 Mbps	1.03 ← best
1.0	0.59 ← best	1.78
5.0	1.61	3.14

So the page says to start at 1.0 and shorten under motion — the opposite of
the usual "longer GOP saves bitrate" advice, which is exactly why it needed
writing down.

Two warnings that cost real debugging time are called out explicitly:

• refEnhance must be 0, not 1. With 1 only half the frames reference the
  keyframe and the rest still propagate errors to the end of the GOP.
• This is not a licence to drop FEC. Every P frame depends on one keyframe,
  which is ~90 packets at a 1400-byte MTU; with no FEC this loses 67% of frames
  at 1% packet loss. And losing that keyframe is silent — the decoder resolves
  against a stale reference and reports no error.

Also covered: the remaining fpv keys (including that fpv.enabled disables
userspace 3A as a side effect), svct and its per-session ?thin=1, a
per-vendor support matrix, and the fact that a config reload does not apply any
of it — the SDK only accepts these between channel creation and encoding start.

Accuracy note

Every measurement on the page is HiSilicon, and the page says so. SigmaStar
takes the identical parameters through the identical vendor call, but the
behaviour of refEnhance: 0 with refPred: false has not been confirmed there
on hardware, so the page gives readers a self-check (raise gopSize; with this
mode active the bitrate goes up) before relying on it.

HiSilicon support for these two keys lands with widgetii/majestic#283; SigmaStar
has shipped them since the fpv work.

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Document Majestic encoder tuning (reference structure, fpv, svct)

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add a new Majestic encoder tuning page documenting fpv.* and video0.svct behavior.
• Expand the example config with commented svct and fpv blocks plus usage guidance.
• Add the new page to the wiki table of contents for discoverability.

Diagram

graph TD
U([Reader]) --> R["README.md (ToC)"] --> T["Majestic encoder tuning"] --> K["Encoder keys (fpv.*, svct)"]
R --> C["Majestic example config"] --> K

Loading

High-Level Assessment

The chosen approach (a dedicated tuning page plus ToC and example-config annotations) is the most discoverable way to close the documentation gap without overloading the existing streamer/config pages. Alternatives like folding this into the existing Majestic config page would make long-form guidance (loss behavior, U-shaped bitrate curve, vendor caveats) harder to find and maintain.

Files changed (3) +197 / -0

Documentation (3) +197 / -0

README.mdAdd ToC link to Majestic encoder tuning page +1/-0

Add ToC link to Majestic encoder tuning page

• Adds a new wiki table-of-contents entry pointing to the Majestic encoder tuning documentation page to improve discoverability.

README.md

majestic-config.mdAnnotate example config with svct and fpv reference-structure block +24/-0

Annotate example config with svct and fpv reference-structure block

• Adds a commented 'video0.svct' line and a commented 'fpv:' block describing reference-structure and related encoder-tuning settings, with a pointer to the new tuning page.

en/majestic-config.md

majestic-encoder-tuning.mdNew encoder tuning guide for reference structure, svct, and fpv settings +172/-0

New encoder tuning guide for reference structure, svct, and fpv settings

• Introduces a new documentation page covering 'fpv.refEnhance'/'fpv.refPred' reference structure tradeoffs under packet loss, the interaction with 'gopSize', explicit warnings (refEnhance=0, keep FEC), and how to validate activation. Also documents 'video0.svct' and per-session thinning, the remainder of the 'fpv:' keys, vendor support notes, and the requirement to restart majestic for settings to apply.

en/majestic-encoder-tuning.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}