@dolby-optiview/ads-sdk 1.1.0 → 1.1.1

package/ai/reference/error-codes.md

@@ -25,6 +25,8 @@ of the public contract and are never renamed.
 | `DA-ANVATO-CUE-OBSERVED` | break | info | ptsSource: 'anvatoCue' — an Anvato break-signaling (type=cue) frame was observed in the stream; context carries the cue's pts, the media time it landed at, whether the tracker recorded it, and the raw payload — so a manifest-PTS vs in-stream-PTS misalignment is observable in the field. |
 | `DA-ANVATO-CUE-SEGMENT-ANCHORED` | break | warn | ptsSource: 'anvatoCue' — an Anvato emsg cue arrived without a ptsOffset from the adapter, so its break is scheduled at the cue's carrying segment start, which can be up to one segment early. Emitted once per session; context: pts, mediaTime. |
 | `DA-ANVATO-CUE-OFFSET-REJECTED` | break | warn | ptsSource: 'anvatoCue' — the adapter's ptsOffset placed an Anvato cue outside its carrying segment's window (more than 0.1s before or 15s after the cue startTime), so the cue's startTime is used instead. Emitted once per cue pts; context: pts, startTime, ptsOffset, mappedTime. |
+| `DA-ANVATO-CUE-END-MATCHED` | break | info | ptsSource: 'anvatoCue' — the active break's Anvato type=cue_end was observed and its length on the stream clock (cue_end pts minus the break start pts) is within 2s of the break duration. Emitted once per break; context: breakId, mediaTime (where the player reported the cue_end), lengthSec, durationSec. |
+| `DA-ANVATO-CUE-END-REJECTED` | break | warn | ptsSource: 'anvatoCue' — an Anvato type=cue_end was observed for the active break but its stream-clock length differs from the break duration by more than 2s, so it is ignored and the resume keeps its computed target. Emitted once per break; context: breakId, mediaTime, lengthSec, durationSec. |
 | `DA-PRELOAD-FAILED` | preload | warn | Ad preload failed; the asset will be loaded on demand at break start. |
 | `DA-PRELOAD-MODE-RESOLVED` | preload | info | The configured ad preload mode was resolved for this session; context carries both the configured and the resolved mode. |
 | `DA-PRELOAD-PATH` | preload | info | The preload path actually taken for a break's ad (parallel buffer / detached prefetch / none) and the creative container (stream vs progressive). |
@@ -103,8 +105,15 @@ of the public contract and are never renamed.
 | `DA-LIVE-START-PUSHBACK-LANDED` | playback | info | Measured initial-live seek landing. Context includes the requested target and targetDurationSec, landed, errorSec, liveEdgeAtLanding, landedOffsetSec and landedOffsetTargetDurations. A timeout or failed seek reports landed=null, never an inferred success. |
 | `DA-RESUME-SEEK` | playback | info | Content was resume-seeked to the resolved post-break position (insertion type policy). |
 | `DA-RESUME-UNADDRESSABLE` | playback | warn | A break played through the content player (picture-in-picture), so content came back on a reloaded source whose timeline has its own origin, and that source published neither a program-date-time nor a seekable range to re-address the resume point against. Content stays where the reload left it — near the live edge — rather than being seeked to a position that does not exist on the new timeline. Context carries breakId, target (the position on the pre-borrow timeline) and offset. |
-| `DA-RESUME-LANDED` | playback | info | Where the post-break resume-seek actually landed, measured on the seeked event rather than inferred: context carries breakId, target (the position requested), landed and errorSec (landed - target; negative means the player settled EARLIER than asked). landed is null with a reason when no seeked event arrived, which is normal for a seek to the position the playhead already holds. Report-only: the SDK does not correct the position. |
+| `DA-RESUME-LANDED` | playback | info | Where the post-break resume-seek actually landed, measured on the seeked event rather than inferred: context carries breakId, target (the position requested), landed and errorSec (landed - target; negative means the player settled EARLIER than asked). errorSec only says whether the SEEK did what it was asked: when the live-window clamp moved the seek, policyTarget is the resume point before the clamp and policyErrorSec (landed - policyTarget) is how far the viewer really is from it. landed is null with a reason when no seeked event arrived, which is normal for a seek to the position the playhead already holds. Report-only: the SDK does not correct the position. |
+| `DA-RESUME-PREPARED` | playback | info | Android, live break that resumes at its end — the paused content was parked exactly on the resume point before the hand-back, so the hand-back only plays (DA-RESUME-SEEK then reports prepared=true and issues no seek). Context carries breakId, target, source (cue_end when the stream's matched type=cue_end was known, else cue+duration) leadMs (how long before the expected hand-back it was parked) and refresh (true when content parked long before the hand-back was seeked onto the same point again, 4.5s before it). A later cue_end parks content again. |
 | `DA-RESUME-PREPOSITIONED` | playback | info | The break resumed without a seek: content was moved onto its resume position DURING the break, so the transition needed no jump. Context carries breakId, target, prepositionedTo, landed, shortfallSec and exact. exact=true means it reached the policy target. exact=false means the live window never published those frames, so content was moved as close as exists — the viewer lands short, but arrives already in place rather than via a visible seek at the cut. |
+| `DA-RESUME-PTS-MAP` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and web — the live resume point was mapped onto currentTime through the stream's own clock: the Anvato type=beacon tags delivered since the run-up's last seek give the currentTime ↔ stream-clock offset, and the resume point (the matched cue_end, else the cue plus the break duration) is converted with it. Reported when a mapping is first available after a seek and whenever the mapped target moves by 0.1s or more. Context carries breakId, target, landingStreamSec, landingSource (cue_end or cue+duration), offsetSec, beacons (beacons averaged), generation (how often the mapping started over since the session began), currentTime, and computedTarget with deltaSec (target - computedTarget) when a currentTime-based target exists. |
+| `DA-RESUME-PTS-REMAP` | playback | warn | ptsSource: 'anvatoCue', iOS/tvOS and web — a stream beacon disagreed with the currentTime ↔ stream-clock mapping by more than 0.2s, so the player re-anchored currentTime (a variant switch or a buffer restart); the mapping starts over from that beacon and the resume point is mapped again. Reported during the resume run-up and after the hand-back. Context carries breakId, fromOffsetSec, toOffsetSec, deltaSec, currentTime and stage (run-up or after-hand-back). |
+| `DA-RESUME-PTS-CORRECTED` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and web — once per break at the hand-back, on a stream that carries Anvato beacons: whether the stream clock placed the live resume point, and by how much it moved it. applied=true: streamClockTarget is the resume point mapped through the beacons, correctionSec is streamClockTarget - computedTarget (the currentTime target, cue plus duration), and currentTimeShiftSec is how far the same stream instant moved in currentTime between the pause and the hand-back (negative: it now sits earlier), null when no beacon mapped the stream before the pause. Context also carries breakId, landingSource (cue_end or cue+duration), landingStreamSec, offsetSec, beacons, remaps (DA-RESUME-PTS-REMAP during the break) and cueEndTarget when a cue_end was matched. applied=false with a reason means no beacon arrived after the run-up's last seek, so the cue_end or currentTime target applied. |
+| `DA-RESUME-PTS-LANDED` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and web — where a stream-clock resume landed, measured on the stream's own clock from the beacons delivered after the hand-back: landedStreamSec is the position content resumed from (resumedAt, the seek landing or the playhead at a seek-free hand-back) converted with that mapping, and errorSec is landedStreamSec - landingStreamSec (negative: content resumed before the stream's resume point, so slate is shown). Context carries breakId, landingStreamSec, landingSource, resumedAt, sinceHandBackSec and, when measured, landedStreamSec, errorSec, offsetSec and beacons; reason when no beacon arrived within 15s. Report-only: the SDK does not correct the position from it. |
+| `DA-RESUME-CUE-END` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS, web and Android — the stream's matched type=cue_end replaced the computed resume target: the slate under the ad ends there, not at cue plus the advertised duration (150.206s for a 150s break on NFL Channel), and the player can remap its timeline while content is held, so the cue_end is reported in the current mapping. Context carries breakId, computedTarget, cueEndTarget, deltaSec (cueEndTarget - computedTarget), stage (hold, playing or hand-back; Android: always hand-back) and corrected (whether an in-buffer correction seek ran). Only a policy that resumes at the break end is replaced; otherwise applied=false and only the delta is reported. |
+| `DA-RESUME-CUE-END-LATE` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and Android — the break's type=cue_end was matched only after the hand-back. When it is more than 1s ahead of the playhead and buffered, content is seeked forward to it once (corrected=true); content is never seeked backward. Context carries breakId, cueEndTarget, currentTime, deltaSec (cueEndTarget - currentTime) and corrected. |
 | `DA-RESUME-CATCHUP` | playback | info | Content began playing behind the ad to reach its resume point. Context carries breakId, startPos, target, remainingAdSec, publishedEnd and clampedStart — clampedStart true means the stream had not published the ideal start position, so playback began late and the alignment loop must make up the difference (the zero-live-headroom case). Its ABSENCE on a live break that resumed short means catch-up never ran at all, which is a different fault from it running and falling short. |
 | `DA-RESUME-TARGET-CLAMPED` | playback | warn | The computed resume position sat outside the held live window and was clamped to the nearest end of it; context carries breakId, requested, clamped, shortfallSec and bound — 'end' when the target is ahead of the published edge, 'start' when it is behind the live window start (already evicted) — applied only when the gap is at most half the held window, otherwise DA-RESUME-START-CLAMP-SKIPPED is emitted instead. Distinct from DA-RESUME-OFFSET-CLAMPED, which shortens the OFFSET to the ad seconds actually played. |
 | `DA-RESUME-START-CLAMP-SKIPPED` | playback | info | The resume target sat behind the element's live seekable start by more than half the held window, which cannot be DVR eviction (the element's seekable range disagrees with the adapter timeline); the target was left unchanged and the engine resolved the seek itself. Context carries breakId, requested, seekableStart, behindSec, windowSec and maxBehindSec. |

package/ai/reference/knowledge-base.md

@@ -158,6 +158,18 @@ difference — expected for a viewer riding the live edge. The end-of-break code
 then carries `alignCorrections` and `alignCorrectionsMs`: shrinking values mean
 the loop converged; similar-magnitude ones mean it chased without settling.
 
+## DA-RESUME-PREPARED
+
+**Cause:** Informational (Android, a live break that resumes at its end). The
+paused content was parked exactly on its resume point before the hand-back, so
+the hand-back only plays (`context`: `breakId`, `target`, `source` — `cue_end`
+or `cue+duration` — `leadMs` before the expected hand-back, and `refresh`: content
+parked long before the hand-back is seeked onto the same point again 4.5 s before
+it); the following
+`DA-RESUME-SEEK` reports `prepared: true` and issues no seek. **Fix:** None. A
+`DA-RESUME-SEEK` with `prepared: false` on such a break means the resume point
+was not known or published early enough, so the hand-back paid for a seek.
+
 ## DA-RESUME-PREPOSITIONED
 
 **Cause:** Informational. Content was moved onto its resume position _while the
@@ -179,17 +191,22 @@ has no headroom and cannot be returned to the exact frame they left.
 
 **Cause:** Informational. Reports where the post-break resume-seek actually
 landed, measured on the `seeked` event rather than inferred from a later
-sample (`context` carries `breakId`, `target`, `landed`, `errorSec`).
-`errorSec` is `landed - target`, so a **negative** value means the player
-settled closer to the live edge than the SDK asked for. **Fix:** None on its
-own — it is a measurement. Read it against `DA-RESUME-SEEK` (where the resume
-policy aimed) and `DA-RESUME-TARGET-CLAMPED` (what the engine would allow): a
-consistent negative `errorSec` on live means the engine is overriding the seek
-with its own minimum live offset, and seeing a clamp alongside an `errorSec`
-near zero means the clamp is absorbing it correctly. `landed: null` with a
-`reason` is normal rather than a fault — a seek to the position the playhead
-already holds fires no `seeked` event on several engines. The SDK never
-corrects the landing position.
+sample (`context` carries `breakId`, `target`, `landed`, `errorSec`, and
+`policyTarget` / `policyErrorSec`). `errorSec` is `landed - target`: it only
+says whether the **seek** did what it was asked, so a **negative** value means
+the player settled closer to the live edge than the SDK asked for.
+`policyTarget` is the resume point before the live-window clamp, and
+`policyErrorSec` (`landed - policyTarget`) is how far the viewer really is from
+it. **Fix:** None on its own — it is a measurement. A consistent negative
+`errorSec` on live means the engine is overriding the seek with its own minimum
+live offset. An `errorSec` near zero alongside `DA-RESUME-TARGET-CLAMPED` does
+**not** mean the resume was on target: read `policyErrorSec`, which is the
+seconds of the ad window (slate, on an SGAI feed) the viewer still sees —
+typically a viewer riding the live edge with no headroom. Both values are in
+the player's `currentTime`, so they cannot reveal a timeline remap. `landed:
+null` with a `reason` is normal rather than a fault — a seek to the position
+the playhead already holds fires no `seeked` event on several engines. The SDK
+never corrects the landing position.
 
 ## DA-LIVE-START-PUSHBACK
 
@@ -498,7 +515,10 @@ early. Content then resumes the same amount early, showing the end of the slate.
 Emitted once per session; `context` carries `pts` and the `mediaTime` used.
 **Fix:** Use an adapter that supplies `ptsOffset` (THEOplayer web and Android,
 Shaka). A custom adapter sets `ptsOffset` on emsg cues to
-`Period@start - presentationTimeOffset / timescale` from the MPD.
+`Period@start - presentationTimeOffset / timescale` from the MPD, or, as the
+THEOplayer Android adapter does, measures it from the stream's Anvato beacons
+(`type=beacon&pts=…`): the median of `startTime - pts` over the beacons that
+agree. On Android the first few seconds of a source have no beacon clock yet.
 
 ## DA-ANVATO-CUE-OFFSET-REJECTED
 
@@ -510,6 +530,101 @@ SDK ignored it and used the segment-start `startTime`. `context` carries `pts`,
 player time for media time `t` must be `t + ptsOffset`. A multi-Period MPD or a
 player that counts time from `availabilityStartTime` can produce a wrong offset.
 
+## DA-ANVATO-CUE-END-MATCHED
+
+**Cause:** Informational (`ptsSource: 'anvatoCue'`). The stream's own end of the
+active break (Anvato `type=cue_end`) was observed, and its length on the stream
+clock is within 2s of the break duration. `context` carries `breakId`,
+`mediaTime` (where the player reported it), `lengthSec` and `durationSec`.
+**Fix:** None needed. On iOS/tvOS and Android this marker is the live resume point.
+
+## DA-ANVATO-CUE-END-REJECTED
+
+**Cause:** Warning (`ptsSource: 'anvatoCue'`). A `type=cue_end` was observed for
+the active break, but its stream-clock length differs from the break duration by
+more than 2s, so it is ignored and the computed resume point is kept.
+**Fix:** Compare `context.lengthSec` with `context.durationSec` and check that
+the manifest duration matches what the broadcaster signals for that break.
+
+## DA-RESUME-CUE-END
+
+**Cause:** Informational (iOS/tvOS, web and Android, `ptsSource: 'anvatoCue'`).
+The matched `cue_end` replaced the computed live resume target. The slate under
+the ad ends there, not at the cue plus the advertised duration (150.206s for a
+150s break on NFL Channel), and the player can move its timeline while content
+is held behind the ad, so the `cue_end` is reported in the current mapping.
+`context` carries `breakId`, `computedTarget`, `cueEndTarget`, `deltaSec`,
+`stage` (`hold`, `playing` or `hand-back`; Android always `hand-back`), `applied`
+and `corrected`. **Fix:** None needed. A `deltaSec` of a fraction of a second is
+the splice segment at the break end; a large one means the marker prevented a
+resume inside the slate. `applied: false` means the resume policy (early
+return, `insertion`, or a `resumeOffset` different from the duration) keeps its
+own target.
+
+## DA-RESUME-CUE-END-LATE
+
+**Cause:** Informational (iOS/tvOS and Android, `ptsSource: 'anvatoCue'`). The
+`cue_end` arrived only after content was handed back. `corrected: true` means
+content was more than 1s short and buffered, and was moved forward onto it;
+content is never moved backward. `context` carries `breakId`, `cueEndTarget`,
+`currentTime`, `deltaSec` and `corrected`. **Fix:** None for a single break.
+Frequent late arrivals with `AVPlayer` suggest the metadata look-ahead is not
+delivering; on Android, the Media3 adapter delivers markers at presentation only,
+so it always arrives late there.
+
+## DA-RESUME-PTS-MAP
+
+**Cause:** Informational (iOS/tvOS and web, `ptsSource: 'anvatoCue'`). The live resume
+point was placed through the stream's own clock: the Anvato `type=beacon` tags
+delivered since the run-up's last seek give the currentTime offset, and the
+resume point (`landingSource`: the matched `cue_end`, else `cue+duration`) is
+converted with it. `context` carries `breakId`, `target`, `landingStreamSec`,
+`landingSource`, `offsetSec`, `beacons`, `generation` (how often the mapping
+started over), `currentTime`, and
+`computedTarget` with `deltaSec`. **Fix:** None needed. A large `deltaSec` is
+the player's timeline having moved during the break, which this mapping
+corrects. A stream without beacons never reports it and keeps the currentTime
+resume.
+
+## DA-RESUME-PTS-REMAP
+
+**Cause:** Warning (iOS/tvOS and web, `ptsSource: 'anvatoCue'`). A beacon showed the
+player re-anchored currentTime against the stream clock by more than 0.2s,
+typically at a variant switch or a buffer restart. The mapping starts over from
+that beacon. `context` carries `breakId`, `fromOffsetSec`, `toOffsetSec`,
+`deltaSec`, `currentTime` and `stage` (`run-up` or `after-hand-back`).
+**Fix:** None during the run-up: the resume point is mapped again from the next
+beacons. Frequent remaps after the hand-back point to the engine re-anchoring
+content on its own.
+
+## DA-RESUME-PTS-CORRECTED
+
+**Cause:** Informational (iOS/tvOS and web, `ptsSource: 'anvatoCue'`). Once per break
+at the hand-back, on a stream with Anvato beacons: whether the stream clock
+placed the resume point (`applied`) and by how much. `correctionSec` is the
+stream-clock target minus the currentTime target (`computedTarget`, cue plus
+duration); `currentTimeShiftSec` is how far the same stream instant moved in
+currentTime during the break (negative: it now sits earlier). `context` also
+carries `breakId`, `streamClockTarget`, `landingSource`, `landingStreamSec`,
+`offsetSec`, `beacons`, `remaps` and `cueEndTarget`. **Fix:** None needed. A
+large `currentTimeShiftSec` is a player timeline re-anchor the stream clock
+corrected. `applied: false` with a `reason` means no beacon arrived after the
+run-up's last seek; frequent occurrences point at beacons not reaching the
+player.
+
+## DA-RESUME-PTS-LANDED
+
+**Cause:** Informational (iOS/tvOS and web, `ptsSource: 'anvatoCue'`). Where a
+stream-clock resume landed, on the stream's own clock, measured from the beacons
+after the hand-back. `errorSec` is `landedStreamSec - landingStreamSec`:
+negative means content resumed before the stream's resume point (that much
+slate shown), positive means content was skipped. `context` carries `breakId`,
+`landingStreamSec`, `landingSource`, `resumedAt`, `sinceHandBackSec` and, when
+measured, `landedStreamSec`, `errorSec`, `offsetSec` and `beacons`; `reason`
+when no beacon arrived within 15s. **Fix:** None for a single break. Unlike
+`DA-RESUME-LANDED` it is not measured in currentTime, so a timeline remap
+cannot hide in it.
+
 ## DA-PRELOAD-FAILED
 
 **Cause:** Preloading the next ad failed; the asset will load on demand at break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "OptiView Ads SDK entry package - OptiViewAds with a default HLS.js ad player (native fallback)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,8 +44,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@dolby-optiview/ads-sdk-adapter-hlsjs": "^1.1.0",
-    "@dolby-optiview/ads-sdk-core": "^1.1.0"
+    "@dolby-optiview/ads-sdk-adapter-hlsjs": "^1.1.1",
+    "@dolby-optiview/ads-sdk-core": "^1.1.1"
   },
   "peerDependencies": {
     "hls.js": "^1.0.0"