From 6af953764e48db177a5f74cce4faa435a38ad68f Mon Sep 17 00:00:00 2001 From: pablop Date: Tue, 10 Nov 2026 18:57:33 +0100 Subject: [PATCH] feat(collaboration): add applyCspUpdate and buildCapReport hooks Add SFVCspFields and SFVCapReport helpers and expose applyCspUpdate, getCspFields, and buildCapReport on SFVSimulationController and SFVBrowserController. applyCspUpdate normalizes pilot CspFields and records CSP_TELEMETRY_UPDATED with triggerDecision false so B1/B2 decisions stay unchanged. buildCapReport returns the cap_reports IPC shape used by the VQEG pilot harness. Add node --test coverage in test/csp-fields.test.js and test/cap-report.test.js. Field semantics and signaling levels are defined in VQEG cap-csp-collaboration-test-pilot (signaling.md, player-api.md). Python shared-table wiring lives in that repository; it merges first, then the pilot bumps this submodule in a follow-up pull request. Co-authored-by: Cursor --- src/core/SFVCapReport.js | 60 +++++++++++++++++++++++ src/core/SFVCspFields.js | 36 ++++++++++++++ src/core/SFVRulesContext.js | 6 ++- src/dashjs/SFVBrowserController.js | 21 +++++++- src/simulation/SFVSimulationController.js | 37 +++++++++++++- test/cap-report.test.js | 41 ++++++++++++++++ test/csp-fields.test.js | 35 +++++++++++++ 7 files changed, 232 insertions(+), 4 deletions(-) create mode 100644 src/core/SFVCapReport.js create mode 100644 src/core/SFVCspFields.js create mode 100644 test/cap-report.test.js create mode 100644 test/csp-fields.test.js diff --git a/src/core/SFVCapReport.js b/src/core/SFVCapReport.js new file mode 100644 index 0000000..1a88f67 --- /dev/null +++ b/src/core/SFVCapReport.js @@ -0,0 +1,60 @@ +/** + * VQEG CAP telemetry report (pilot ``CapReport`` / ``cap_reports`` IPC). + * Co-sim today: one snapshot per collaboration tick; event-driven 1/s is future work. + */ + +const EPS = 1e-8; + +export function countSwipesInWindow(userEvents, timeS, windowS = 1, eps = EPS) { + if (!Array.isArray(userEvents)) return 0; + return userEvents.filter( + (event) => + event?.eventType === 'SWIPE' && + Number.isFinite(event.time) && + event.time > timeS - windowS && + event.time <= timeS + eps, + ).length; +} + +function playableBufferSeconds(playback) { + const positionS = playback.positionS ?? 0; + if (typeof playback.bufferEnd === 'function') { + return Math.max(0, playback.bufferEnd() - positionS); + } + const snap = typeof playback.snapshot === 'function' ? playback.snapshot() : playback; + const ranges = snap.bufferRanges ?? []; + const bufferEnd = ranges.length + ? Math.max(...ranges.map((range) => range.endS ?? range.end ?? 0)) + : 0; + return Math.max(0, bufferEnd - (snap.positionS ?? positionS)); +} + +function stallFlag(playback) { + if (typeof playback.stalled === 'boolean') return playback.stalled; + if (typeof playback.snapshot === 'function') return !!playback.snapshot().stalled; + return false; +} + +function currentVideoId(playback) { + if (playback.videoId != null && playback.videoId !== '') return String(playback.videoId); + if (typeof playback.snapshot === 'function') { + const id = playback.snapshot().videoId; + return id == null ? '' : String(id); + } + return ''; +} + +/** + * @param {{ timeS: number, playback: object, userEvents?: object[], swipeWindowS?: number }} args + */ +export function buildCapReportFromSession({ timeS, playback, userEvents = [], swipeWindowS = 1 }) { + if (!Number.isFinite(timeS) || timeS < 0) throw new TypeError('buildCapReportFromSession: invalid timeS'); + if (!playback || typeof playback !== 'object') throw new TypeError('buildCapReportFromSession: playback required'); + return Object.freeze({ + time_s: timeS, + is_stalled: stallFlag(playback), + playable_buffer_s: playableBufferSeconds(playback), + current_video_id: currentVideoId(playback), + swipe_rate_per_s: countSwipesInWindow(userEvents, timeS, swipeWindowS), + }); +} diff --git a/src/core/SFVCspFields.js b/src/core/SFVCspFields.js new file mode 100644 index 0000000..581bca3 --- /dev/null +++ b/src/core/SFVCspFields.js @@ -0,0 +1,36 @@ +/** VQEG CSP snapshot fields (aligned with pilot ``CspFields`` / ``Observation.csp_fields``). */ + +const FIELD_KEYS = [ + 'updated_at_s', + 'plan_downlink_mbps', + 'achieved_throughput_mbps', + 'rtt_ms', + 'loss_rate', + 'congestion_rate', +]; + +export function normalizeCspFields(raw) { + if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) return null; + const out = {}; + for (const key of FIELD_KEYS) { + const v = raw[key]; + out[key] = v === undefined ? null : v; + } + if (out.updated_at_s !== null && !Number.isFinite(out.updated_at_s)) { + throw new TypeError('csp_fields.updated_at_s must be a finite number when present'); + } + for (const key of FIELD_KEYS) { + if (key === 'updated_at_s') continue; + const v = out[key]; + if (v !== null && !Number.isFinite(v)) { + throw new TypeError(`csp_fields.${key} must be a finite number or null`); + } + } + return Object.freeze(out); +} + +export function cspFieldsEqual(a, b) { + if (a === b) return true; + if (a == null || b == null) return false; + return FIELD_KEYS.every((key) => a[key] === b[key]); +} diff --git a/src/core/SFVRulesContext.js b/src/core/SFVRulesContext.js index f9188df..2918586 100644 --- a/src/core/SFVRulesContext.js +++ b/src/core/SFVRulesContext.js @@ -1,6 +1,6 @@ export class SFVRulesContext { - constructor({time,session,playlist,currentVideoIndex,catalog,store,requests,playback,networkHistory,userHistory,playbackHistory}) { - Object.assign(this,{_time:time,_session:session,_playlist:playlist,_currentVideoIndex:currentVideoIndex,_catalog:catalog,_store:store,_requests:requests,_playback:playback,_networkHistory:networkHistory,_userHistory:userHistory,_playbackHistory:playbackHistory}); + constructor({time,session,playlist,currentVideoIndex,catalog,store,requests,playback,networkHistory,userHistory,playbackHistory,cspFields=null}) { + Object.assign(this,{_time:time,_session:session,_playlist:playlist,_currentVideoIndex:currentVideoIndex,_catalog:catalog,_store:store,_requests:requests,_playback:playback,_networkHistory:networkHistory,_userHistory:userHistory,_playbackHistory:playbackHistory,_cspFields:cspFields}); Object.freeze(this); } getCurrentTime(){return this._time;} @@ -14,4 +14,6 @@ export class SFVRulesContext { getUserHistory(){return structuredClone(this._userHistory);} getPlaybackHistory(){return structuredClone(this._playbackHistory);} getBufferRanges(videoId){ if(videoId!==this._playback.videoId) return []; return structuredClone(this._playback.bufferRanges); } + /** Latest CSP snapshot from collaboration IPC / live adapter; ``null`` at L0 or before first update. */ + getCspFields(){ return this._cspFields == null ? null : structuredClone(this._cspFields); } } diff --git a/src/dashjs/SFVBrowserController.js b/src/dashjs/SFVBrowserController.js index 7372762..2f1b718 100644 --- a/src/dashjs/SFVBrowserController.js +++ b/src/dashjs/SFVBrowserController.js @@ -13,6 +13,8 @@ import {SFVAbrController} from '../core/SFVAbrController.js'; import {normalizeSchedulingConfig} from '../core/SFVConfig.js'; import {ACTION,MANIFEST_STATE} from '../core/constants.js'; import {SFVSessionRecordBuilder} from '../output/SFVSessionRecordBuilder.js'; +import {cspFieldsEqual,normalizeCspFields} from '../core/SFVCspFields.js'; +import {buildCapReportFromSession} from '../core/SFVCapReport.js'; /** One browser feed/UE; B1 and B2 run unmodified against the same rules context as DES. */ export class SFVBrowserController { @@ -52,9 +54,26 @@ export class SFVBrowserController { this.autoPlayAttempted=new Set(); this.lastSamplePosition=null;this.lastSampleVideoId=null;this.seekPending=false; this.listeners=[]; + this.cspFields=null; this.#bindPlaybackEvents(); } time(){return this.now()-this.epochStart;} + + applyCspUpdate(rawFields,timeS=this.time()) { + if (!Number.isFinite(timeS) || timeS < 0) throw new TypeError('applyCspUpdate: invalid time_s'); + const next=normalizeCspFields(rawFields); + const changed=!cspFieldsEqual(this.cspFields,next); + this.cspFields=next; + if (!changed) return; + this.#observe({time:timeS,eventType:'CSP_TELEMETRY_UPDATED',cspFields:next,triggerDecision:false}); + } + + getCspFields(){return this.cspFields==null?null:structuredClone(this.cspFields);} + + buildCapReport(timeS=this.time()){ + return buildCapReportFromSession({timeS,playback:this.playback,userEvents:this.userEvents}); + } + #observe(event){ if(this.stopped)return; const e=this.abr.observe({...event,time:event.time ?? this.time()}); @@ -94,7 +113,7 @@ export class SFVBrowserController { // Avoid cloning the entire append-only history on every decision epoch. // SFVRulesContext.getNetworkHistory() still clones when the rule requests it. networkHistory:this.networkEvents, - userHistory:this.userEvents,playbackHistory:this.playbackEvents}); + userHistory:this.userEvents,playbackHistory:this.playbackEvents,cspFields:this.cspFields}); } #runtimeView(){return {requests:this.requestManager.list(),store:this.store.list(), catalogState:id=>this.catalog.getManifestState(id)};} diff --git a/src/simulation/SFVSimulationController.js b/src/simulation/SFVSimulationController.js index 992bc21..3584425 100644 --- a/src/simulation/SFVSimulationController.js +++ b/src/simulation/SFVSimulationController.js @@ -14,6 +14,8 @@ import { SFVSessionRecordBuilder } from '../output/SFVSessionRecordBuilder.js'; import { normalizeSchedulingConfig } from '../core/SFVConfig.js'; import { resolveSessionTiming } from './SFVSessionTiming.js'; import { resolveUserInteractions, resolveCapacityGenerator } from './generators/SFVGenerators.js'; +import { cspFieldsEqual, normalizeCspFields } from '../core/SFVCspFields.js'; +import { buildCapReportFromSession } from '../core/SFVCapReport.js'; export class SFVSimulationController { constructor({ dataset, rule, config = {}, transport = null, requestIdPrefix = "r" }) { @@ -103,6 +105,7 @@ export class SFVSimulationController { this.sampleIndex = 0; this.sampleStart = null; this.lastObservedPlaybackPosition = 0; + this.cspFields = null; this.requestManager = new SFVRequestManager({ catalog: this.catalog, @@ -223,6 +226,37 @@ export class SFVSimulationController { this.requestManager.processTransportEvent(event); } + /** + * Apply a filtered CSP snapshot from pilot ``network_step.collaboration`` (offline harness + * or future live adapter). Rules read via ``getCspFields()``; policy use is not enabled yet. + */ + applyCspUpdate(rawFields, timeS) { + if (!Number.isFinite(timeS) || timeS < 0) throw new TypeError('applyCspUpdate: invalid time_s'); + const next = normalizeCspFields(rawFields); + const changed = !cspFieldsEqual(this.cspFields, next); + this.cspFields = next; + if (!changed) return; + this.abr.observe({ + time: timeS, + eventType: 'CSP_TELEMETRY_UPDATED', + cspFields: next, + triggerDecision: false, + }); + } + + getCspFields() { + return this.cspFields == null ? null : structuredClone(this.cspFields); + } + + /** VQEG ``cap_reports`` payload for one UE at ``timeS`` (pilot co-sim: per network step). */ + buildCapReport(timeS = this.clock.now()) { + return buildCapReportFromSession({ + timeS, + playback: this.playback, + userEvents: this.userEvents, + }); + } + stopQueuedRequests(timeS, sessionEnded) { return this.requestManager.stopQueued(timeS, sessionEnded); } @@ -486,7 +520,8 @@ export class SFVSimulationController { .list() .filter((event) => event.eventType.startsWith('REQUEST_')), userHistory: this.userEvents, - playbackHistory: this.playbackEvents + playbackHistory: this.playbackEvents, + cspFields: this.cspFields, }); } diff --git a/test/cap-report.test.js b/test/cap-report.test.js new file mode 100644 index 0000000..881624f --- /dev/null +++ b/test/cap-report.test.js @@ -0,0 +1,41 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { buildCapReportFromSession } from '../src/core/SFVCapReport.js'; +import { SFVSimulationController } from '../src/simulation/SFVSimulationController.js'; +import { SFVCurrentVideoRule } from '../src/rules/SFVCurrentVideoRule.js'; + +test('buildCapReportFromSession matches pilot co-sim snapshot fields', () => { + const report = buildCapReportFromSession({ + timeS: 1.0, + playback: { + videoId: 'v1', + positionS: 2, + stalled: true, + bufferEnd: () => 5, + }, + userEvents: [{ eventType: 'SWIPE', time: 0.5 }], + }); + assert.equal(report.time_s, 1); + assert.equal(report.is_stalled, true); + assert.equal(report.playable_buffer_s, 3); + assert.equal(report.current_video_id, 'v1'); + assert.equal(report.swipe_rate_per_s, 1); +}); + +test('SFVSimulationController.buildCapReport delegates to core helper', () => { + const dataset = { + videos: [{ + videoId: 'v1', + representations: { video: [{ id: 'r0', bitrateKbps: 500, segments: [{ index: 0, startS: 0, durationS: 5 }] }] }, + }], + }; + const controller = new SFVSimulationController({ + dataset, + rule: new SFVCurrentVideoRule(), + config: { sessionStartTimeS: 0, sessionEndTimeS: 6, swipeTimesS: [] }, + }); + controller.startAt(0); + const report = controller.buildCapReport(0.01); + assert.equal(report.current_video_id, 'v1'); + assert.equal(typeof report.playable_buffer_s, 'number'); +}); diff --git a/test/csp-fields.test.js b/test/csp-fields.test.js new file mode 100644 index 0000000..1707ff6 --- /dev/null +++ b/test/csp-fields.test.js @@ -0,0 +1,35 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { normalizeCspFields } from '../src/core/SFVCspFields.js'; +import { SFVSimulationController } from '../src/simulation/SFVSimulationController.js'; +import { SFVCurrentVideoRule } from '../src/rules/SFVCurrentVideoRule.js'; + +test('normalizeCspFields accepts pilot-shaped snapshot', () => { + const fields = normalizeCspFields({ + updated_at_s: 0.01, + plan_downlink_mbps: 10, + achieved_throughput_mbps: null, + rtt_ms: 40, + loss_rate: 0, + congestion_rate: null, + }); + assert.equal(fields.plan_downlink_mbps, 10); + assert.equal(fields.achieved_throughput_mbps, null); +}); + +test('applyCspUpdate exposes fields on rules context without re-deciding', () => { + const dataset = { + videos: [{ + videoId: 'v1', + representations: { video: [{ id: 'r0', bitrateKbps: 500, segments: [{ index: 0, startS: 0, durationS: 5 }] }] }, + }], + }; + const controller = new SFVSimulationController({ + dataset, + rule: new SFVCurrentVideoRule(), + config: { sessionStartTimeS: 0, sessionEndTimeS: 6, swipeTimesS: [] }, + }); + controller.startAt(0); + controller.applyCspUpdate({ updated_at_s: 0, plan_downlink_mbps: 8 }, 0); + assert.equal(controller.getCspFields()?.plan_downlink_mbps, 8); +});