bitvid/docs/nip71-migration-plan.md

# NIP-71 Interop Plan for bitvid

Status: **planning / spec** (no code yet). Last updated 2026-06-22.

Goal: let a publisher **opt in** to making a bitvid video fully NIP-71 compliant so
it (a) shows up on other Nostr video clients (Nostube, Amethyst, Flare, zap.stream
recordings, …) and (b) still carries bitvid's extra data (WebTorrent, flags) for a
richer experience inside bitvid. Eventually bitvid also **ingests** other clients'
NIP-71 videos. Decisions below were made with the maintainer; see "Decisions".

---

## Decisions (locked)

1. **Kind: addressable `34235` (normal) / `34236` (short).**
2. **Opt-in, off by default** — per-video toggle; private videos never mirrored.
3. **Scope: outbound first, inbound later** (Phase 1 vs Phase 2).
4. **Dual-event model (decided 2026-06-22), NOT single-canonical.** Considered
   collapsing to one note type by making bitvid's canonical video event itself
   kind 34235/36. Verdict: keep kind 30078 canonical + an additive mirror.
   - *Why a single note is appealing:* one event, no drift, fully discoverable.
   - *Why we're not doing it (yet):* (a) **private videos can't be public NIP-71**
     (no encryption) so they'd stay 30078 regardless — "one note for everything"
     is impossible, only "one note for public"; (b) **kind 30078 is the addressing
     root** — `30078:pubkey:d` is referenced by watch-history pointers, comments,
     reactions, view counts, playlists, naddr deep-links, and moderation, plus
     hardcoded video subscription filters (`nostrService.VIDEO_KIND`,
     `videoPointer.DEFAULT_VIDEO_KIND`, `kinds:[30078]` across client/channel/
     search). Switching the canonical kind ripples through all of them and needs a
     forward-only dual-read migration. Not worth the risk for the interop win.
   - *Accepted trade-off:* two events per shared video; the mirror can drift from
     the canonical, so the lifecycle must keep them in sync (auto re-publish on
     edit / remove on delete) — see Phase 1 polish.
   - The Phase 0/1 builder+parser are reusable if we ever revisit single-canonical
     (they'd become bitvid's native 34235 read/write layer).

### Why 34235/34236 (research-validated)

The earlier assumption that 34235/36 were "deprecated legacy" was **wrong**. The
current NIP-71 (master) defines **all four** kinds and explicitly designates the
addressable pair for editable content:

> "For content that may need updates after publication (such as correcting
> metadata, descriptions, or handling URL migrations), addressable versions are
> available: Kind `34235` … Kind `34236` … include a `d` tag as a unique
> identifier and can be updated while maintaining the same addressable reference."

That is **exactly** bitvid's model (replaceable kind 30078, edit-in-place via
`d` = `videoRootId`). So 34235/36 is not a compromise — it's the spec-recommended
kind for what bitvid does, and it's what Nostube/Goblinbox consume today.

> Hedge: keep the builder **kind-parameterized** so we can also emit / switch to
> `21`/`22` (regular) later without a rewrite if the ecosystem leans that way.

---

## Architecture: dual-event, additive

- **Canonical stays kind 30078** (NIP-78 app-data), unchanged. Source of truth for
  WebTorrent, private videos, moderation, view counts — none of which NIP-71 models.
- **Mirror = kind 34235/34236**, addressable with **`d` = `videoRootId`** (same
  d-tag as the 30078), so the mirror edits/deletes in **lockstep** with the canonical.
- Correlation is automatic via `(pubkey, videoRootId)`. We also set:
  - `["origin", "bitvid", "<videoRootId>", "https://bitvid.network/?v=<nevent|naddr>"]`
    so other clients can attribute + deep-link back ("watch on bitvid").
  - Optionally `["a", "30078:<pubkey>:<videoRootId>"]` back-pointer (harmless elsewhere).
- **bitvid never double-renders its own mirror.** Inside bitvid the 34235/36 is
  merged onto its 30078 by `videoRootId` (`nip71Cache` already keys on it) — it is
  metadata enrichment, never a second feed card. This dedup applies from Phase 1
  (our own mirror), not just Phase 2 (foreign videos).

---

## Field mapping: 30078 JSON → 34235/36 tags

Sourced against NIP-71 + NIP-92 (`imeta`) + NIP-94 (file metadata fields).

| bitvid (30078 content) | NIP-71 / imeta | notes |
|---|---|---|
| — | `["d", videoRootId]` | required for addressable; lockstep with 30078 |
| `title` | `["title", …]` | required |
| `description` | `.content` (full description) | |
| short text | `["alt", …]` | accessibility text — title / first line, NOT a dump of the full description |
| first publish time | `["published_at", …]` | read from the ORIGINAL 30078 (root `created_at`/`published_at`); **stable across edits** so foreign clients don't reorder |
| `url` (HTTPS) | `imeta url <…>` | primary playable source for foreign clients |
| derived MIME | `imeta m <…>` | not stored today → derive from extension, default `video/mp4` |
| `thumbnail` | `imeta image <…>` | |
| `duration` (upload `#input-duration`) | `imeta duration <sec>` | already collected at upload — wire it through |
| dimensions (probe at upload) | `imeta dim <w>x<h>` **+ 34235-vs-34236 selection** | not captured today → add a `loadedmetadata` probe |
| `fileSha256` | `imeta x <…>` | |
| `originalFileSha256` | `imeta ox <…>` | |
| `magnet` | `imeta magnet <magnet:?xt=…&ws=…&xs=…>` | **standard NIP-94 field** — torrent-aware clients can use it |
| `infoHash` | `imeta i <infohash>` | **standard NIP-94 field** |
| `ws` / `xs` | encoded into the `magnet` URI (`&ws=`/`&xs=`) | also kept on 30078 canonical |
| `isNsfw` | `["content-warning", "<reason>"]` | standard |
| hashtags | `["t", <tag>]` (repeated) | written to **both** 30078 and the mirror; see "Hashtags & the feed" |
| `isForKids`, `mode`, etc. | bitvid-namespaced extra tags | ignored by other clients |
| — | `["client", "bitvid"]` | |

**Two hard rules that fall out of this:**

1. **Private videos are never mirrored.** NIP-71 has no encryption; mirroring would
   leak them. The toggle is disabled (with explanation) for private videos.
2. **A hosted HTTPS `url` is required to mirror.** Foreign clients can't play a
   magnet-only video; bitvid's magnet still rides along (`magnet`/`i`) for
   torrent-aware clients, but `url` must be present or the toggle is disabled.
3. **The `url` must be publicly reachable** (CORS + range requests) so other
   clients can actually play it. Gate the toggle on bitvid's existing public-access
   verification (`verifyPublicAccess`) — don't advertise a video elsewhere that
   only bitvid can fetch.

**Timestamp hygiene:** `created_at` = actual signing time; `published_at` = display
time. (Avoids the future-`created_at` weirdness seen in some published events.)

---

## Hashtags & the feed (no algo changes)

The explore/kids feed scoring **already** consumes NIP-71 hashtags:
`js/feedEngine/exploreScoring.js` builds each video's tag vector from **both** the
raw `["t", …]` tags on the event **and** `video.nip71.hashtags`, then matches it
against the user's interests/disinterests vector. `nip71.js` already parses `t`
tags into `metadata.hashtags` and merges NIP-71 metadata onto videos by
`videoRootId` (`nip71Cache`). So a native 30078 video, a 34235/36 mirror, and an
ingested foreign NIP-71 video all slot into the **same** hashtag-driven scoring —
**the feed algorithm needs zero changes.**

The only gap is **capture**: bitvid's current 30078 content schema has no per-video
hashtags field (videos only get the topic tag `["t","video"]`). So the work is to
add a hashtags input and emit `["t", tag]` on **both** events. This is part of
Phase 1.

## Converting existing videos (the edit/upgrade flow)

Opting an existing video into NIP-71 is just an **edit**. When the publisher toggles
the mirror on (or edits an already-mirrored video), bitvid maps every available
30078 field into its NIP-71 home per the table above — title→`title`,
description→`.content`/`alt`, url→`imeta url`, thumbnail→`imeta image`,
magnet/infoHash→`imeta magnet`/`i`, nsfw→`content-warning`, hashtags→`t`, etc. —
and writes the 34235/36 mirror with `d` = `videoRootId` so it stays addressable and
lockstep-editable.

Practical notes for conversion:
- Existing videos have **no user hashtags yet**, so the edit form surfaces the new
  hashtags input; tags the publisher adds are written to **both** the 30078 and the
  mirror (keeping the feed unified, native + mirrored).
- Conversion is non-destructive: the 30078 stays canonical; the mirror is additive.
- Re-editing later updates both in lockstep (same `d`-tag); toggling off NIP-09s the
  mirror only.

---

## Discovery & relays (the part that decides if anyone sees it)

A format-perfect mirror is **invisible** if it isn't on the relays other clients
read. This is the #1 thing that makes or breaks interop, and it's a *relay* problem,
not a format problem.

- bitvid already has NIP-65 (`relayManager.publishRelayList`, kind 10002, + outbox
  reads), and `publishVideo` targets `this.writeRelays`. The mirror must publish to
  the user's **NIP-65 write relays (outbox model)** — that's where outbox-aware
  clients (Amethyst, etc.) look for that author's content.
- **Ensure the user has a published, accurate NIP-65 list** when they first enable
  the mirror (publish kind 10002 if missing). Without it, outbox clients can't find
  the video regardless of correctness.
- Consider also fanning the mirror out to a small set of **well-known general/video
  relays** so non-outbox clients (and search) can discover it. Keep this list short
  and configurable; respect the relay-fan-out cap lessons (don't storm).
- Relay reads for any future ingest go through the subscription manager
  (lint:pool-access), never `pool.list` directly.

---

## Phases

### Phase 0 — Retarget builders (no UX; flag stays off)
- Point existing `buildNip71VideoEvent` at **34235/36 + `d`=`videoRootId`** (it
  currently targets 21/22). Implement the field mapping incl. `magnet`/`i`/`ox`/
  `duration` (already collected at upload).
- Normal-vs-short selection: default 34235; choose 34236 when known-portrait
  (from captured dimensions; otherwise a manual "short" toggle).
- Cheat-resistant tests: bitvid video → spec-valid 34235 event → round-trips back
  via `convertEventToVideo`; magnet/infohash present; private refused; url-less refused.
- **Interop golden test**: assert the produced event matches the spec shape
  (`d`/`title`/`published_at`/`imeta url`+`image`) so a foreign parser (Nostube-style)
  can read it — guards against silent shape drift.

### Phase 1 — Outbound publish/edit/delete (the headline feature)
- Edit form toggle: **"Also publish to other Nostr video apps (NIP-71)"** — off by
  default, gated to **public + HTTPS-url + public-access-verified** videos, and
  **not offered for `isNsfw` videos when `ALLOW_NSFW_CONTENT=false`** (see
  "Moderation, web-of-trust, mute/block & NSFW").
- Surface the same control in the **My Videos tab** (per-video mirror status +
  toggle; it already lists owned videos with action buttons). Optional bulk
  "make discoverable" there later.
- **Capture dimensions at upload** (`loadedmetadata` probe) for 34235-vs-34236
  selection + `imeta dim`; wire the existing `duration` through.
- **Add a hashtags input**; write `["t", tag]` on **both** the 30078 and the mirror
  (the feed already scores these — no algo change).
- **Field conversion on edit/upgrade**: map all available 30078 fields into their
  NIP-71 homes per the mapping table (see "Converting existing videos").
- Publish: 30078 (as today) **+** the 34235/36 mirror to the user's **outbox
  (NIP-65 write) relays**; publish a kind-10002 list first if the user has none
  (see "Discovery & relays"). Reuse the publish-outcome toast.
- Lifecycle parity: **edit** updates both (same d-tag); **delete** publishes a
  NIP-09 (`kind 5`) referencing the mirror's `["a","34235:<pubkey>:<d>"]` (+ `k`),
  AND empties the addressable event (empty-replace, the watch-history/encrypted-sync
  lesson) so clients that ignore NIP-09 still see it cleared; **toggle-off** does the
  same for the mirror only.
- Mutation-verified lifecycle tests, then flip `FEATURE_PUBLISH_NIP71` on.

### Phase 1.5 — Discoverability glue (cheap, high interop value)
- **NIP-89 handler registration** (kind `31990`): publish once that bitvid handles
  video kinds `21/22/34235/34236` with a `web` URL template. Result: other clients
  (Amethyst, etc.) can show **"Open in bitvid"** when they encounter a video event.
- **NIP-51 video curation sets** (kind `30005`): publish/read bitvid playlists as
  portable video sets so playlists interop across clients. (Sets reference videos
  by `e`/`a` tags.)

### Phase 2 — Inbound ingest (separate, bigger)
- Feed source querying `34235/36` (and `21/22`) from relays; map via
  `convertEventToVideo`.
- Dedup vs bitvid-native (by `a`-address / `x` hash / `url`), moderation + trust
  gating (reuse blacklist / NIP-51 mute), and a **distinct discovery surface** so
  foreign videos read as "from the wider Nostrverse," not bitvid-native.
- Honor `origin` for attribution; respect the no-URL-allowlist rule but apply
  existing moderation.
- (Cross-client comments/zaps via NIP-22 `kind:1111` addressed to the 34235 event
  is a further follow-on — bitvid comments currently target 30078.)

---

## Moderation, web-of-trust, mute/block & NSFW (audited 2026-06-22)

The existing controls key on **author pubkey** and **event id**, so they apply to
NIP-71 videos automatically — *as long as ingested videos flow through the same feed
pipeline*. One real gap (inbound NSFW) + one config-respect (outbound).

**Outbound (Phase 1):**
- [ ] Respect the site `ALLOW_NSFW_CONTENT` config (`config/instance-config.js`,
      default `false`): when false, **do not offer/allow the mirror for `isNsfw`
      videos** — an instance that won't surface NSFW shouldn't publish it outward.
      The pure builder stays config-agnostic and always sets `content-warning` when
      NSFW; gate at the call site.
- Mute/block/WoT/admin-blacklist don't newly apply outbound — it's the user's own
  content (a blacklisted user can't publish anyway).

**Inbound (Phase 2) — the real moderation work:**
- [ ] **`content-warning` → `isNsfw`**: `mergeNip71MetadataIntoVideo` does NOT
      currently map a NIP-71 `content-warning` to `video.isNsfw`. The site NSFW
      filter keys on `isNsfw`, so foreign NSFW would bypass it. Map it in the ingest
      path so `ALLOW_NSFW_CONTENT=false` filters foreign NSFW too.
- [ ] **Same pipeline, no bypass**: route every ingested video through the existing
      stages — `blacklist-filter` (`shouldIncludeVideo`: admin/event-id blacklist +
      blocked authors), `moderation` (admin whitelist/blacklist + trusted-mute /
      trusted-report thresholds = web-of-trust), watch-history suppression,
      kids-audience, NSFW. These key on pubkey/id, so mute lists (NIP-51 kind 10000),
      blocks, admin lists, and WoT thresholds catch foreign authors automatically.
- [ ] **Trust gate for strangers**: don't surface unknown/untrusted foreign authors
      by default — apply the same trust-seed / web-of-trust gating native videos get
      (consider requiring author ∈ WoT, or a stricter default threshold for ingest).
- **Kids feed is already safe**: `kidsAudienceFilterStage` is allowlist-based
  (`isForKids !== true` ⇒ excluded) and also drops `isNsfw` + disallowed
  content-warnings, so foreign videos (no `isForKids`) never enter the kids feed.

---

## Enrichment backlog (nice-to-have, not v1)
`bitrate`, `waveform`, multiple resolution `imeta` variants + multi-audio
(`ov`/language) tracks, `text-track` (WebVTT captions/subtitles/chapters),
`segment` (chapters) — all need more captured/transcoded at upload time. v1 ships
spec-valid imeta with `url`/`m`/`image`/`dim`/`duration`/`x` + `magnet`/`i`, and
grows from there. (`dim`/`duration` are pulled into v1 — see Phase 1.)

---

## Risks / watch-items
- **Editing addressable events across foreign clients**: some cache aggressively;
  edits may lag elsewhere. Acceptable; document it.
- **Magnet-only catalogs**: those videos simply won't appear on non-torrent clients
  (by design — they still work in bitvid).
- **Kind drift**: if the ecosystem consolidates on 21/22, add/dual-emit later
  (builder stays kind-parameterized).
- **Ingest safety (Phase 2)**: arbitrary foreign media + metadata → keep moderation,
  no autoplay of untrusted sources, sanitize before render.

---

## Sources
- NIP-71 Video Events (current): https://github.com/nostr-protocol/nips/blob/master/71.md (vendored at `docs/nips/71.md`)
- NIP-92 inline metadata (`imeta`): https://github.com/nostr-protocol/nips/blob/master/92.md
- NIP-94 file metadata (`magnet`, `i`, `x`, `ox`, `fallback`, …): https://github.com/nostr-protocol/nips/blob/master/94.md
- NIP-89 recommended application handlers (`31989`/`31990`): https://github.com/nostr-protocol/nips/blob/master/89.md
- NIP-51 lists/sets incl. kind `30005` video curation: https://github.com/nostr-protocol/nips/blob/master/51.md
- Existing bitvid code: `js/nostr/nip71.js` (builders/parser), `js/nostrEventSchemas.js` (`NIP71_VIDEO`/`NIP71_SHORT_VIDEO`), `js/constants.js` (`FEATURE_PUBLISH_NIP71`).