docs(millicast): document enableUTCInsertion publishing parameter

[bcostdolby]

Summary

Documents the new enableUTCInsertion ingest option (media-server OPTI-3526) in the public Millicast docs. The feature stamps H.264 media with an unregistered SEI carrying the server's UTC receive time (Unix epoch ms), for RTMP/SRT passthrough and transcoded H.264 layers, without re-encoding, and only when the ingest doesn't already provide an onFi/AMF sender time.

Two files change:

1. millicast/broadcast/publishing-parameters.md — new enableUTCInsertion row in the parameters table (alphabetical, after audioOnly). Covers: what it does, H.264-only + RTMP/SRT scope (not WebRTC ingest passthrough, not H.265), the onFi/AMF preservation + mixed-clock caveat, seiKeyFrameOnly interaction (passthrough limited to keyframes; transcoded layers always per-frame), and configuration surfaces/precedence (URL param > publishing-token setting > account-level default). Links to the frame-metadata page for the consumer/verification path.

2. millicast/playback/frame-metadata.md — new "Server-Inserted UTC Timecode" section under Timecode Metadata. Explains that the SEI reuses the same UUID as onFi (9a21f3be-…) so players parse it identically (no player-side change), and documents behavior across the three processing modes:

Processing mode	Default (seiKeyFrameOnly=false)	seiKeyFrameOnly=true
Passthrough layer	Every frame	Keyframes only
Transcoded layer	Every frame	Every frame (setting does not apply)

Also covers transcode-with-a-passthrough-layer (mix of the two), the per-frame fresh timestamp value, and the onFi/AMF non-overwrite guarantee.

The parameters-table column padding was re-flowed by prettier (repo version) because the new row is the widest cell — hence whitespace-only churn on surrounding rows. prettier --check passes.

Notes for reviewers

• Precedence, UUID reuse, and per-mode SEI behavior were verified against the merged media-server implementation (RtmpValidator.js, H264Packetizer.cpp, rtmppacketizer.cpp, h264encoder.cpp). The admin feature flag (highest priority in the media server) is internal-only and intentionally omitted from customer docs.
• WebRTC/WHIP ingest passthrough is intentionally called out as unsupported; H.265 is unaffected.

Link to Devin session: https://dolby.devinenterprise.com/sessions/b635c9bf3add4fd393c2280136e1c01f
Requested by: @bcostdolby

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[bcostdolby]

The default of what is false? enableUTCInsertion or seiKeyFrameOnly?

Are there docs for the seiKeyFrameOnly already we can link to or should we add some for that here too?

[devin-ai-integration]

Good catches — both addressed in the latest push:

1. Which default is false? It's enableUTCInsertion (this row's parameter). Reworded to enableUTCInsertion defaults to false. to remove the ambiguity.

2. seiKeyFrameOnly docs. There's no dedicated page for it — it's only documented as its own row in this same table (it predates this PR). So I've changed the reference to "the seiKeyFrameOnly parameter (also in this table)" rather than link to a non-existent page. Docusaurus doesn't generate anchors for individual table rows, so an in-page link to a specific row isn't possible without adding markup. If you'd like, I can promote seiKeyFrameOnly (and enableUTCInsertion) to short dedicated sub-sections under this page so they get linkable anchors — happy to do that as a follow-up if you think it's worth it.

[dcoffey3296]

@bcostdolby can we also add a detail on how this is applied at the publishing token?

[devin-ai-integration]

Happy to add this. The row currently notes only that a token-level setting takes precedence over the URL param. Before documenting how it's applied at the token, we should confirm the customer-facing mechanism, since the utcInsertion feature flag is set on the token via internal admin tooling today — I want to avoid documenting a self-serve path that doesn't exist publicly.

@bcostdolby — is enabling utcInsertion on a publishing token something customers do themselves (dashboard / Customer API when creating a token), or is it applied by Dolby/support on request? Once you confirm, I'll add a short sentence (or a "Publishing token" subsection) describing the exact steps.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔍 Tri-state token behavior vs. documented boolean type in the parameters table

The frame-metadata page documents enableUTCInsertion on a publish token as tri-state (true/false/null to inherit the account default), while the publishing-parameters table lists the type as Boolean with default false. These are consistent for the URL parameter (which is boolean-only), but readers may conflate them; verifying that the Token API schema actually accepts null (and that omission means inherit rather than false) would be worthwhile before publishing, since the API reference pages are generated from OpenAPI and could contradict this.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Verified against the Customer API implementation (millicast/Millicast.DashApi #1582): on a publish token enableUTCInsertion is persisted as a nullable bool (bool? / enable_utc_insertion tinyint(1) NULL DEFAULT NULL). Create treats null/omitted as inherit; update uses the repo's PropertyValue<bool?>/IsSet idiom so an explicit null clears the value back to inherit while an omitted key means "no change". So the tri-state described here is correct.

You're right that the two pages describe different surfaces: the publishing-parameters table row is the URL parameter, which is boolean-only (present/1/true → on), whereas the tri-state applies only to the token setting. That's intentional and now called out on both pages.

Note the API reference pages are generated from an OpenAPI spec that is not in this repo, so it's out of scope for this docs PR — I've flagged separately that the publish-token create/update spec should be updated to include enableUTCInsertion (nullable) so the generated reference stays consistent with this guide.

[bcostdolby]

The word "these" in this context sounds like it is talking about the onFi/AMF timecodes as that is what was just mentioned.

Please make this more explicit something like, when more than one method is used to configure the enableUTCInsertion flag, ...

Feel free to change the wording of what I just entered there to fit the document.

[devin-ai-integration]

Fixed — reworded to remove the ambiguous "these" (which did read as onFi/AMF). It now says: "When more than one method is used to configure the enableUTCInsertion flag, the URL parameter takes precedence over the publishing-token setting, which in turn overrides the account-level default." (commit 6420abd)

[bcostdolby]

Also mention it is typically recommended that customers use the token or account level setting and only use the URL param for quick testing but not permanent ingest. This allows control and visibility through the dashboard.

[devin-ai-integration]

Added a recommendation right after the precedence line: "It is generally recommended to configure the flag at the publishing-token or account level rather than via the URL parameter. This keeps the setting controllable and visible through the dashboard. The URL parameter is best reserved for quick testing, not for permanent ingest configurations." (commit 6420abd)

[bcostdolby]

Also mention that the token specific value can be easily updated in the dasboard GUI as well if you are manually creating tokens.

[devin-ai-integration]

Added a note at the top of the token subsection: "If you create and manage tokens manually, you can also set this per-token value directly in the dashboard — open the token's details and use the Insert UTC timestamp control (Default / On / Off), which maps to the same tri-state described below." (commit 0967e60)