UC_4.5.1: Live Broadcast

Document References

1. Overview

References/Wireframe/Stage 2/Community & Live Broadcast/Community (with data).webp Community page, broadcast Live — player + title header + Live badge + session schedule bar.

References/Wireframe/Stage 2/Community & Live Broadcast/Community (no data).webp Community page, broadcast Offline — countdown state.

2. Trigger

• The trader navigates to the Community page via the Community tab in the persistent sidebar (Ref: UC_4.1.2 §2 Screen Description) → frontend calls GET /community/live-broadcast.
• The client-side countdown reaches 00:00:00 → frontend calls GET /community/live-broadcast exactly once more (Ref: BR_4.5.1.3).

3. Pre-conditions

• The user is authenticated and is on the Community page. No further condition applies — account type (SIM / LIVE), level, and account status are irrelevant (Ref: BR_4.5.1.1).
• Operations has populated Zapier Table C with the current values of Active_Broadcast_URL, Broadcast_Is_Live, Broadcast_Title, and Broadcast_Schedule (Ref: BR_4.5.1.2).

4. Post-conditions

• The widget renders in exactly one of four states: Live player, Offline — countdown running, Offline — countdown held at 00:00:00, or Offline — TBD (Ref: BR_4.5.1.4).
• The Live badge and every schedule-bar dot render in the colour that matches the current broadcast state — red only while live, grey otherwise (Ref: BR_4.5.1.10).
• If the trader entered the page while a broadcast was live, the Newsquawk audio stream in the persistent header is Off (Ref: BR_4.5.1.11).

5. Basic Flow — Broadcast Live

1. The Community page renders. The frontend calls GET /community/live-broadcast.
2. The backend reads Zapier Table C and responds 200 OK with { youtube_id, is_live, title, schedule[] }. The response is returned for any authenticated user; there is no middleware gate and no SIM/LIVE branching (Ref: BR_4.5.1.1, BR_4.5.1.2).
3. is_live == true → the frontend mounts a plain HTML <iframe> populated with youtube_id, applying the required embed parameters (Ref: BR_4.5.1.5).
4. The frontend renders the title value returned by the API in the header above the player (Ref: BR_4.5.1.7) and displays the Live badge in its red live state (Ref: BR_4.5.1.10).
5. The Newsquawk audio stream in the persistent header automatically switches to Off so that it does not overlap the broadcast audio (Ref: BR_4.5.1.11).
6. The player displays the thumbnail configured on the YouTube video until the user starts playback. All playback interaction — play, volume, seek, closed captions, quality, fullscreen — is handled natively by the YouTube control bar (Ref: BR_4.5.1.5).
7. The session schedule bar renders below the player by iterating the schedule[] array, as static, non-interactive content. The dot of the block that contains the current time renders red; every other dot renders grey (Ref: BR_4.5.1.9, BR_4.5.1.10).
8. At the end of the session, Operations sets Broadcast_Is_Live = false in Table C. While the trader keeps the page open, the frontend does not detect this change and continues showing the mounted iframe, where YouTube renders its own end-of-stream overlay. The widget returns to the Offline state (Ref: §6) on the next page load or the next navigation into the Community page (Ref: BR_4.5.1.3).

6. Alternative Flow — Broadcast Offline

Applies when the response returns is_live == false. The Play component is hidden entirely and no thumbnail is rendered in any of the three sub-states below; the frame and container size stay unchanged so the page grid does not shift. The Live badge renders in its grey offline state as Live Broadcast Offline, and every schedule-bar dot renders grey (Ref: BR_4.5.1.4, BR_4.5.1.10).

6.1 — Countdown running (schedule[] contains at least one entry)

1. The frontend renders the Live Broadcast Offline state.
2. The frontend iterates schedule[], compares each entry against the current time, and selects the next upcoming slot. If every slot for the current day has already passed — including the case where the array holds a single entry — the timer rolls over and counts down to that slot on the following day. The timer is never disabled while schedule[] has data (Ref: BR_4.5.1.4).
3. The countdown is computed once, at page load, and ticks down locally.
4. The supporting lines Market opens soon and Next session starts at [hh:mm CST] are displayed, the latter showing the time value of the selected slot.
5. The session schedule bar renders below the frame with all dots grey (Ref: BR_4.5.1.9).

6.2 — Countdown reaches 00:00:00

1. The frontend calls GET /community/live-broadcast exactly once.
2. [If is_live == true] → the widget transitions to §5 step 3 and mounts the player.
3. [If is_live == false] → the countdown is held at 00:00:00, the supporting line changes to Starting soon, and the Next session starts at [hh:mm CST] line is hidden. The schedule bar stays visible with all dots grey. No further request is made until the page is reloaded.

6.3 — No session scheduled (schedule[] is empty or absent)

1. The frontend renders TBD in place of the numeric timer.
2. The supporting line reads Next session to be announced, and the Next session starts at [hh:mm CST] line is hidden.
3. The session schedule bar is hidden entirely — there is no schedule data to render (Ref: BR_4.5.1.9).

7. Exceptional Flow

• [If a client-side extension (ad-blocker) prevents the iframe from mounting] — the frontend renders a static text block inside the video frame container: Please disable ad-blockers to view the live broadcast. The title header, Live badge, and session schedule bar remain unchanged (Ref: BR_4.5.1.6).
• [If Active_Broadcast_URL holds an invalid ID or points to a deleted video] — no server-side validation is performed. The iframe mounts and YouTube displays its own "Video unavailable" error. Operations corrects the value directly in Table C (Ref: BR_4.5.1.5).
• [If the stream drops mid-session or the trader's connection is slow] — no custom detection, fallback UI, network warning, or quality downgrade is built. YouTube's native loading/error overlay and adaptive bitrate streaming handle both cases (Ref: BR_4.5.1.5).
• [If the trader switches to another browser tab while playing] — playback is not auto-paused; the iframe keeps streaming audio in the background per standard browser behaviour (Ref: BR_4.5.1.5).

8. Business Rules

BR_4.5.1.1: Universal Access — No Account-Type or Account-Status Gating

Live Broadcast is a universal community feature. GET /community/live-broadcast returns 200 OK for any authenticated user, and there is no middleware gate, no account_status field, and no SIM/LIVE differentiation logic anywhere in the request path.

• SIM (Evaluation) accounts see the widget fully unlocked — there is no hidden state, no locked state, and no upsell/"Unlock when you go Live" placeholder.
• SIM and LIVE traders watch the exact same stream. The backend serves a single global youtube_id for the entire platform; there is no per-level or per-account-type content separation.
• Account risk status does not affect this widget. A SIM trader under Soft Breach (Ref: UC_4.10.1), under Hard Breach, or who has failed the Associate Track still sees and uses Live Broadcast normally — breach enforcement restricts trading only, not community content.

BR_4.5.1.2: Manual Broadcast Control via Zapier Table C

Broadcast state is controlled entirely by manual Operations input on Zapier Table C — Global_Variables (Source: Zapier Integration V7.pdf §3.1 Table C). No automated YouTube Data API listener is built for this release.

API contract. GET /community/live-broadcast returns:

{ "youtube_id": "string", "is_live": boolean, "title": "string", "schedule": [ { "time": "string", "label": "string" } ] }

There is no next_broadcast_timestamp field and no provider field. The countdown is derived on the frontend from schedule[] (Ref: BR_4.5.1.4); the provider is hardcoded to YouTube for the day-1 launch, so no provider column is added to Table C.

• The schedule is entered manually in Table C by Operations; there is no synchronisation from Google Calendar or any external CMS. Operations is responsible for updating it when a session concludes.
• No broadcast scheduling database is built. Table C holds only the current day's programming. When the day's sessions end, Operations overwrites Broadcast_Title and Broadcast_Schedule with those of the following day.
• Whether Operations changes Active_Broadcast_URL between sessions or keeps one persistent stream key and only toggles Broadcast_Is_Live is an operational choice. The frontend renders whichever youtube_id the endpoint currently returns and does not need to distinguish the two cases.
• Only one global broadcast can exist at any moment: the endpoint returns a single JSON object containing exactly one youtube_id, so two simultaneous broadcasts are not representable.
• Automatic live-status detection through the YouTube Data API is explicitly out of scope for this release and is registered as a Day-2 item requiring its own Change Request.

BR_4.5.1.3: Two-Call API Contract — No Polling, No WebSocket

The frontend calls GET /community/live-broadcast in exactly two situations, and no others:

1. On the initial load of the Community page.
2. Exactly once, at the moment the client-side countdown reaches 00:00:00, to check whether the state has transitioned to live.

Continuous polling and a dedicated WebSocket channel for this widget are both prohibited, in order to avoid unnecessary server load.

Consequence — session end is not auto-detected mid-view. Because no further request is issued while the page stays open, the frontend cannot observe Operations setting Broadcast_Is_Live = false during a session. A trader who is watching when the session ends keeps the mounted iframe and sees YouTube's native end-of-stream overlay; the widget only returns to the Offline countdown state on the next page load or the next navigation into the Community page. This is accepted behaviour for this release, not a defect.

BR_4.5.1.4: Offline State Matrix and Countdown Computation

The countdown is derived from the schedule[] array, not from a server-supplied timestamp field. At page load the frontend iterates schedule[], compares each entry's time against the current time, selects the next upcoming slot, and counts down to it locally. It is a one-time client-side computation and is never re-synchronised with the server (Ref: BR_4.5.1.3).

• Roll-over: if every slot in schedule[] has already passed for the current day — including the case where the array holds a single entry — the timer counts down to that same slot on the following day. The timer is never disabled while schedule[] has data.
• TBD applies only when schedule[] itself is empty or absent. A schedule that is merely fully elapsed is not a TBD state; it rolls over per the rule above.

In the first two Offline sub-states the existing offline frame layout is preserved — the container keeps its size and the session schedule bar stays in place — so that the page grid does not break. No complex error state is introduced for a late broadcast.

⚠️ Open item — time basis of the schedule entries. The client's answer describes the frontend comparing each schedule[] entry against the current server time, but the replacement payload carries no server-time field, and the earlier confirmed behaviour (Trigger A2) is a one-time computation against the user's local machine time. In addition, time is a display string carrying a timezone label (08:00 CST), not an ISO-8601 UTC value, so it falls outside the project timestamp standard — Ref: CR-08. To be confirmed with the client: whether a server_time (ISO-8601 UTC) field is added to the payload, and whether time should carry an explicit offset instead of the CST label. Until confirmed, the frontend parses time as CST and counts down against local machine time, accepting clock drift.

BR_4.5.1.5: Native YouTube IFrame Embed — Player Constraints

The player is a plain HTML <iframe>. The YouTube IFrame Embed API is not used, and no custom video player UI wrapper, custom overlay, or custom control set is built. The dashboard only receives youtube_id from the endpoint and populates the iframe with it.

• Required embed parameters: ?rel=0&modestbranding=1 (Source: RFQ_ Website and Dashboard Implementation V7.pdf §Community Page Implementation). rel=0 is mandatory — it prevents competitor videos from being suggested when a broadcast ends. controls=1 is used so that the full standard YouTube control bar is displayed: volume, seek, closed captions, quality selection, and fullscreen are all handled natively by YouTube. Native controls must not be selectively hidden.
• Native YouTube chat must be completely hidden (Source: RFQ_ Website and Dashboard Implementation V7.pdf §Community Page Implementation). Chat for this page is served by the separate Discord Chat Stream component — SIM (read-only, one-way): Ref: UC_4.9.1; LIVE (two-way): Ref: UC_4.5.2 (not yet documented in this repo).
• Video quality stays auto-adaptive to the viewer's bandwidth. The resolution must not be hard-locked to 1080p, 720p, or any fixed value; YouTube's native adaptive bitrate engine manages delivery.
• No custom failure handling. Server-side validation of the video ID, custom auto-detection of a dropped stream, custom fallback UI, custom quality downgrades, and custom network warnings are all out of scope — YouTube's native loading and error overlays cover these cases (Ref: §7).
• No auto-pause on background tabs. No Intersection Observer or equivalent script is written; the iframe keeps streaming audio when the tab loses focus, which is the intended behaviour for traders watching charts in another tab.
• Mobile: the video frame keeps a standard 16:9 aspect ratio and auto-resizes. At mobile breakpoints the layout stacks vertically with the video on top and the chat panel directly below it; the horizontal session schedule bar is hidden on small screens to preserve vertical space.

BR_4.5.1.6: Ad-Blocker Fallback Container

If a client-side extension prevents the iframe from mounting, the frontend renders a basic fallback container in place of the video: a single static text block reading Please disable ad-blockers to view the live broadcast, with no icon and no action button. All surrounding elements — title header, Live badge, and session schedule bar — remain unchanged.

BR_4.5.1.7: Broadcast Title Rendering

The header text above the player is the title value returned by GET /community/live-broadcast. There is no separate CMS entry and no hardcoded label.

• Long title: the text wraps to the next line. Rendering an ellipsis (...) is forbidden; where the text is cut, it is clipped cleanly.
• Empty or null title: the text container is hidden entirely so that it leaves no blank gap — the surrounding elements close up.

BR_4.5.1.8: Session Transition — Component-Scoped Re-render

Any transition between broadcast states (Live → Offline, Offline → Live, or one session to the next) re-renders only the video component. A full page reload must not be triggered, and the sibling widgets on the Community page — Live Chat history, Pod details, and The Pit statuses — retain their active state without interruption.

There is no intermediate or post-session state: the widget moves directly between the player and the countdown state defined in BR_4.5.1.4. No Recorded / VOD badge or state exists.

BR_4.5.1.9: Session Schedule Bar — Dynamic Data, Static Behaviour

The bar below the player listing the day's sessions (for example 08:00 CST · THE OPEN and 10:00 CST · THE GAP) is a static schedule label, not a progress or seek bar. Its content is rendered dynamically by iterating the schedule[] array returned by GET /community/live-broadcast; nothing on this bar is hardcoded on the frontend.

• Data source: each element of schedule[] renders one entry as [time] · [label] preceded by its dot. time and label are both Operations-entered strings from Broadcast_Schedule on Table C (Ref: BR_4.5.1.2).
• Capacity: the bar must render up to 4 scheduled broadcasts without the layout breaking; the container has ample room for that number.
• Label overflow: because the text is Operations-entered, each label is clipped with CSS truncation (white-space: nowrap; overflow: hidden;). The label must not wrap to a second line and must not render an ellipsis-driven layout shift; each label slot allows roughly 10 characters before clipping.
• Dot colour is state-driven, never hardcoded (Ref: BR_4.5.1.10).
• Clicking a session label does not seek or jump to a timestamp in the video. Because the player is a native YouTube iframe, all video scrubbing is handled exclusively by the YouTube control bar; no custom seeking logic is built for this component.
• The bar is hidden at mobile breakpoints (Ref: BR_4.5.1.5).
• Visibility by state: the bar stays visible while the broadcast is Live and while it is Offline with a countdown — it must not be hidden just because the video is offline. It is hidden only when schedule[] is empty or absent (the TBD state), because there is no schedule data to render (Ref: BR_4.5.1.4).

Note. The truncation rule above is the opposite of the rule for the broadcast title in BR_4.5.1.7 (title = wrap to the next line, never clip to one line). Two different components, two different rules — they must not be merged.

BR_4.5.1.10: Live Indicator Colour States — Badge and Schedule Dots

Both live indicators are state-driven and never hardcoded red. Red means "on air right now"; every other situation is grey.

• At most one dot is red at any moment, since only one schedule block can contain the current time.
• If is_live == true but the current time falls outside every schedule block (Operations started the stream off-schedule), the badge is still red while all dots stay grey — the two indicators are evaluated independently.
• No third colour and no additional state (for example Recorded / VOD) exists (Ref: BR_4.5.1.8).

BR_4.5.1.11: Newsquawk Audio Auto-Off on Entering Community During a Live Session

When the trader navigates into the Community page while a broadcast is running (is_live == true), the Newsquawk audio stream in the persistent header automatically switches to Off, so that the squawk audio does not overlap the broadcast audio. The trader can re-enable it manually; the widget does not fight the user's control after the auto-off, and the On/Off state resumes normal user control after navigating away from Community.

The rule is owned by BR_4.1.4.4 (UC_4.1.4 — Newsquawk Audio Stream); this rule only states the Live Broadcast side of the interaction and adds no independent behaviour.

⚠️ Alignment note. BR_4.1.4.4 as currently written triggers the auto-off on entering the Community screen at all, without checking is_live. This rule states the narrower trigger confirmed by the BA on 2026-08-12: auto-off applies when the trader enters Community and a broadcast is live. BR_4.1.4.4 needs the same condition added so the two documents do not diverge.

9. Screen Description

Related behaviour owned elsewhere: when the trader navigates into this screen while a broadcast is live, the Newsquawk audio stream in the persistent header switches to Off automatically so that it does not overlap the broadcast audio. That rule is owned by BR_4.1.4.4; its Live Broadcast side is stated in BR_4.5.1.11.

Changelog