docs(media-player): document how duration_secs is resolved and add the 1.1.0 migration entry

[snowplow-claude-review]

What

The media-player data model resolves duration_secs from a play's own reported value, falling back to a media-level maximum when the play reported none. That resolution has never been documented — duration does not appear anywhere on the data-model page today — which is why users have had to ask how the number is derived.

Two pages updated, paired with the package change that makes the play-first resolution correct.

Changes

• Media Player data model page — new How the media duration is resolved section (after Identifiers), covering the play-first resolution, the media-level fallback, the columns derived from it (is_complete_play, content_watched_percent, and the media_stats rollups), and a note that the fallback is scoped to the events in a single run while media_stats.duration_secs is not.
• Media Player migration guide — new Upgrading to 1.1.0 entry matching the existing per-version format: a bolded full-refresh recommendation for snowplow_media_player_base and snowplow_media_player_media_stats, justified by snowplow__upsert_lookback_days and the cross-run weighted average in media_stats; a behavior-changes list; an explicit statement that media_stats.duration_secs is unchanged; and a note that no configuration or schema change is required. It cross-links to the new section.

Notes for the reviewer

• The 1.1.0 heading is taken from the package's minor bump (latest shipped schema file is dbtMediaPlayer_1.0.1.json). It needs to match whatever version the package repo actually releases.
• No dbtMediaPlayer_1.1.0.json schema file or version-list entry is included: git history shows those arrive via the automated release PR rather than being hand-authored. Flagged rather than silently omitted.

Verification

yarn install --immutable then yarn build, exit 0. docusaurus.config.ts sets onBrokenLinks and onBrokenAnchors to throw, so every internal link and the cross-page anchor is validated at build time, and the built HTML renders the new section anchor as linked.

---

Draft PR opened for review — please verify and run CI before merging.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	b24cc52	Commit Preview URL Branch Preview URL	Aug 21 2026, 06:47 AM

[Snowplow CLA bot (snowplowcla)]

Thanks for your pull request. Is this your first contribution to a Snowplow open source project? Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://docs.snowplowanalytics.com/docs/contributing/contributor-license-agreement/ to learn more and sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.