docs: film-set multi-camera preview link - capacity, latency budget, ecosystem gaps

[josephnef]

Conceptual design note for a film-set multi-camera preview link — the request relayed from a film-production contact: HDMI/SDI in at each camera, 2–25 cameras simultaneously into one video village, ~100 ms camera-to-screen, 1–1.5 km, 1080p60.

What the note establishes, each figure paired with what it does not prove:

• Twenty-five cameras at a kilometre is a 10–25-channel plan with one receiving radio per channel, not a bigger dongle. A receiving USB adapter has the same ~50–60 Mbps airtime ceiling as a transmitting one; 25 CSMA transmitters on a shared channel defer rather than add. The EPIC: 5G-NR-style scheduled RAN on devourer (multi-user + multi-cell) #254 slot arithmetic confirms it independently (25 UEs on one channel = 125 ms superframe; 2–4 UEs = 10–20 ms).
• The 100 ms budget is decided at the HDMI ingest and the monitor, not in the radio. Radio + encoder legs measure under 20 ms; a USB HDMI capture dongle alone was reported at +66–99 ms. Only a bridge chip straight into the encoder SoC fits.
• Range at a kilometre is unmeasured anywhere in the project and is the dominant risk.
• What the measured primitives buy for this case (hardware timebase = timecode-grade sync, per-frame rate/power/channel, channel migration, FHSS), what devourer does not have (video pipeline, video-plane encryption, multi-receiver story, range data), how the case maps onto the EPIC: 5G-NR-style scheduled RAN on devourer (multi-user + multi-cell) #254 milestones (uplink-heavy M1/M4/M5/M6, SPIKE: ARM cell-node feasibility for warehouse-scale RAN (PTP quality, vfio/SMMU, USB-tier PinBeaconTbtt discipline) #381), and the ranked ecosystem gap list.

Docs only; no code. Written per the design-doc rule: no paths, APIs or config constants, competitors as balanced peers, current-state only. Adds one line to the README doc index.

Companion filings: #254 comment, #457 (multi-receiver ground station), widgetii/majestic#924 (HDMI/SDI ingest).

🤖 Generated with Claude Code

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

PR Summary by Qodo

Document film-set multi-camera preview link feasibility and gaps

📝 Documentation 🕐 20-40 Minutes

AI Description

• Map the 25-camera requirement to a multi-channel receiving plan rather than one shared radio.
• Break down the 100 ms latency budget and distinguish bench evidence from unmeasured range
 assumptions.
• Rank missing video, coordination, and validation work for a staged build.

Diagram

graph TD
  A["HDMI or SDI"] --> B["Bridge ingest"] --> C["Hardware encoder"] --> D["Camera radios"] --> E["Channel receivers"] --> F["Video decoders"] --> G["Village monitors"]
  H["Channel planner"] --> E

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Centralized ground-station decoding

• ➕ Simplifies central recording and monitor-wall composition.
• ➖ Concentrates many receiving radios and up to 25 video streams on a small number of hosts.

Recommendation: The note's staged, per-monitor receive-and-decode option is a sensible starting point because it avoids requiring one host to handle every radio and stream. Reconsider centralized decoding once multi-stream capacity and recording needs are measured.

Files changed (2) +258 / -0

Documentation (2) +258 / -0

README.mdIndex the film-set preview-link note +3/-0

Index the film-set preview-link note

• Adds the new note to the timing and coordination documentation index, highlighting its channel-plan, latency, and ecosystem-gap analysis.

README.md

film-set-preview-link.mdAssess multi-camera preview feasibility and staged validation +255/-0

Assess multi-camera preview feasibility and staged validation

• Documents the 25-camera capacity and 100 ms latency budgets, separating measured bench results from estimates and untested kilometre-scale range. Relates the proposed system to the scheduled-network roadmap, ranks missing components, and outlines a staged build and measurement plan.

docs/film-set-preview-link.md

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

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Jaguar2 control commands can be lost ✓ Resolved 🐞 Bug ☼ Reliability

Description

The document describes hardware acknowledgements and transmit reports as a reliable control/return
plane, but Jaguar2 measurements show only 0.91 ACK rate normally, 0.64 after retargeting, and 0.86
report coverage. Control traffic using this path can therefore lose acknowledgements or reports,
especially during retargeting, and the claim is also not applicable to TX-only sessions where
Jaguar1/Jaguar2 reports are absent.

Code

docs/film-set-preview-link.md[R158-162]

+- **Hardware acknowledgement and per-frame transmit reports** as a link
+  sensor and a reliable control/return plane (camera control, tally, timecode),
+  though not for the video plane itself.
+
+What it does **not** have for this job, plainly: no packaged low-latency

Evidence

The new document makes an unqualified reliability claim. The scheduled-MAC measurement table records
Jaguar2 ACK rates of 0.91 and 0.64 after retargeting with 0.86 report coverage, while the
surrounding documentation says Jaguar1/Jaguar2 TX-only sessions receive no reports.

docs/film-set-preview-link.md[158-165]
docs/scheduled-mac.md[185-203]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The document labels hardware ACKs and transmit reports a reliable control/return plane despite measured Jaguar2 ACK and report loss and the absence of reports in TX-only sessions.
## Fix Focus Areas
- docs/film-set-preview-link.md[158-165]
- docs/scheduled-mac.md[185-203]
## Recommended Fix
Call these mechanisms control-plane sensing and delivery feedback rather than a reliable control plane, and state the measured generation/session limitations. If reliable control is required, document the retry, timeout, and end-to-end acknowledgement layer that provides it.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Camera slots can miss their deadlines ✓ Resolved 🐞 Bug ≡ Correctness

Description

The document derives a 5 ms scheduled slot from a measured submit-to-air guard of up to 3.2 ms and
uses it to calculate a 125 ms 25-camera superframe. The scheduled-MAC contract recommends sizing
slots at approximately twice the measured p99.9 guard, so the cited worst case implies roughly 6.4
ms per slot and about 160 ms for 25 cameras unless the design explicitly accepts deadline misses.

Code

docs/film-set-preview-link.md[R174-181]

+- The measured submit-to-air guard (1–3 ms at the 99.9th percentile) sizes a
+  slot at about 5 ms. With one or two cameras per channel, a cell of two to
+  four stations has a 10–20 ms superframe, comfortably inside the budget. With
+  twenty-five stations on one channel it would be a 125 ms superframe — which
+  independently confirms the channel-plan conclusion of §2.
+- The single-cell scheduled MAC milestone is the per-channel cell: one ground
+  radio, one or two camera stations, collision-free uplink where carrier-sense
+  between two mutually hidden cameras would not be.

Evidence

The new document uses 5 ms slots and derives 125 ms for 25 stations. The scheduled-MAC measurements
reach a 3.2 ms p99.9 guard and the contract recommends slots at least approximately twice the
measured guard, with deadline-miss acceptance as a separate alternative.

docs/film-set-preview-link.md[174-181]
docs/scheduled-mac.md[30-44]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The 5 ms slot and 125 ms 25-camera superframe do not follow the scheduled-MAC sizing guidance for the measured 3.2 ms p99.9 submit-to-air guard.
## Fix Focus Areas
- docs/film-set-preview-link.md[174-181]
- docs/scheduled-mac.md[30-44]
## Recommended Fix
Use the documented slot-sizing margin when presenting the arithmetic, or explicitly state that 5 ms assumes a bounded deadline-miss rate rather than the normal p99.9 contract. Recalculate the 25-camera superframe consistently with that assumption.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. 6 GHz plans can understate channel width 🐞 Bug ≡ Correctness

Description

The document limits the 6 GHz tri-band option to 80 MHz even though the supported RTL8832CU and
RTL8852CU hardware is documented as 160 MHz capable. This misstates the available channel plan and
conflicts with the document's own statement that 160 MHz can tune and transmit.

Code

docs/film-set-preview-link.md[R65-67]

+The 5 GHz band offers about two dozen non-overlapping 20 MHz channels if the
+DFS ranges are usable where the shoot happens; 6 GHz adds more on the one
+tri-band part, at 80 MHz maximum and with no range evidence at all. So

Evidence

The new document says 6 GHz is limited to 80 MHz, while the supported-hardware table identifies both
relevant tri-band parts as 160 MHz capable. The same new document separately lists 80/160 MHz as
tunable and airable.

docs/film-set-preview-link.md[65-67]
docs/film-set-preview-link.md[49-51]
README.md[108-109]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The 6 GHz capability statement says the tri-band hardware has an 80 MHz maximum, contradicting the repository's supported-hardware documentation and the document's own 160 MHz entry.
## Fix Focus Areas
- docs/film-set-preview-link.md[65-67]
- README.md[108-109]
## Recommended Fix
Describe 6 GHz as offering additional channels with hardware-dependent widths, including 160 MHz support on the documented RTL8832CU/RTL8852CU parts, while retaining the caveat that range has not been measured.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Preview streams have no timecode output ✓ Resolved 🐞 Bug ≡ Correctness

Description

The document calls sub-microsecond radio-clock alignment “timecode-grade synchronisation of every
preview stream” even though no implementation maps that clock to SMPTE timecode or provides LTC
output. The measured primitive can support future synchronization work, but the current preview path
does not deliver the claimed timecode capability.

Code

docs/film-set-preview-link.md[R143-147]

+- **A hardware timebase across all radios.** Beacon-stamped hardware time is
+  held to a fraction of a microsecond between nodes with carrier-sense off and
+  to about a hundred microseconds software-stamped. On a set that is
+  timecode-grade synchronisation of every preview stream, and the shared clock
+  a channel scheduler needs. Commercial systems sell timecode passthrough as a

Evidence

The document claims timecode-grade synchronization in the measured-primitives section but later
explicitly identifies SMPTE/LTC mapping as unbuilt. Repository timing measurements establish
TSF/beacon-clock alignment, not timecode carriage through the video stream.

docs/film-set-preview-link.md[143-148]
docs/film-set-preview-link.md[228-230]
docs/time-distribution.md[130-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The document presents the hardware timebase as timecode-grade synchronization, but the current project has no SMPTE timecode mapping or LTC output.
## Fix Focus Areas
- docs/film-set-preview-link.md[143-148]
- docs/film-set-preview-link.md[228-230]
- docs/time-distribution.md[130-138]
## Recommended Fix
Describe the feature as synchronized radio or capture clocks, and state that it is a foundation for timecode alignment rather than timecode-grade preview synchronization until SMPTE/LTC carriage exists.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗