bitvid/AGENTS.md

Bitvid — AI Agent Guide (AGENTS.md)

This document tells AI agents how Bitvid works now and how to extend it going forward. It focuses on the newly adopted URL‑first playback with WebTorrent fallback strategy, minimal code touchpoints, and reliable interop with the Nostr ecosystem.

As you work in the repo, please add detailed comments to help others understand what and why your code is doing.

---

1) Mission & Product Direction

Goal: Stream videos reliably and cheaply.

• Primary transport: a hosted video URL (MP4/WebM/HLS/DASH) that plays directly in the browser.
• Secondary transport (fallback & cost control): a WebTorrent magnet enhanced with ws= (web seed) and xs= (.torrent URL).
• Behavior: Try url first. If it’s missing or unreachable, fallback to WebTorrent using the same post’s magnet. If the magnet includes ws/xs, WebTorrent can bootstrap via HTTP and/or peers.
• Nostr interop: Keep existing kind 30078 events for Bitvid’s app data; optionally mirror a NIP‑94 kind 1063 event so other clients can discover the same hosted video URL.
• Resilience: Light link‑health probing to hide/flag dead URLs and avoid broken playback.

---

2) High‑Level Architecture

• Frontend app (vanilla JS + HTML/CSS)

  • Upload modal accepts: Title (required), URL or Magnet (at least one required), Thumbnail, Description. Optional fields for ws and xs help P2P bootstrap.
  • Feed / Cards render video posts, each carrying both data-play-url and data-play-magnet attributes.
  • Player uses playVideoWithFallback({ url, magnet }): probe url; if OK, play via <video>; else call torrentClient.streamVideo(magnet, videoEl).

• Nostr client

  • Publishes Bitvid’s kind 30078 events with content { version, title, url?, magnet?, thumbnail?, description?, mode }.
  • Subscribes to Bitvid video events and (optionally) NIP‑94 kind 1063 to interop with external clients.

• Optional Upload API (future): If adding server‑side upload (NIP‑96/98), the client would POST to an uploader, receive an HTTPS URL, then publish events.

---

3) Data Contracts

3.1 Bitvid app event (kind 30078)

Content JSON (superset; some fields optional):

{
  "version": 2,
  "title": "<string>",
  "url": "https://cdn.example.com/video.mp4",     // optional but recommended
  "magnet": "magnet:?xt=urn:btih:...&tr=...",      // optional but recommended
  "thumbnail": "https://.../thumb.jpg",            // optional
  "description": "<string>",                       // optional
  "mode": "live" | "dev"                          // optional
}

Validation:

• title required; at least one of url or magnet required.
• If magnet present and uploader supplied ws and/or xs, append them to the magnet before publish.

3.2 NIP‑94 mirror (kind 1063, optional but encouraged)

Tags (typical):

• ["url", "https://cdn.example.com/video.mp4"]
• ["m", "video/mp4"] (or video/webm, application/x-mpegURL, etc.)
• ["thumb", "https://.../thumb.jpg"] (optional)
• ["alt", "<title or description>"] (optional)
• ["size", "<bytes>"] (optional)
• ["x", "<sha256-of-file>"] (optional integrity)
• ["magnet", "magnet:?xt=...&ws=...&xs=..."] (optional for P2P aware clients)

Agents SHOULD keep Bitvid’s 30078 as the source of truth, and publish a lossless mirror into 1063 when possible.

---

4) UI & UX Flows

4.1 Upload Flow (author)

1. Author opens Upload modal.
2. Inputs Title, plus either Hosted URL or Magnet (or both). Optionally adds Web seed base (ws) and .torrent URL (xs).
3. Client augments magnet with ws/xs and publishes a kind 30078 event (and optionally a NIP‑94 1063).

4.2 Consumption Flow (viewer)

1. Feed renders cards with data-play-url + data-play-magnet.

2. On click: playVideoWithFallback()

   • probeUrl(url) → If reachable, set <video>.src = url and play.
   • Else: torrentClient.streamVideo(magnet, videoEl).

3. UI hides or badges items whose probeUrl() fails consistently (cached temporarily).

---

5) Key Client Functions (reference)

5.1 normalizeAndAugmentMagnet(raw, { webSeed?, torrentUrl?, xs?, extraTrackers? })

• Accepts a magnet URI or bare hex info hash and returns a sanitized magnet.
• Fixes accidentally encoded xt=urn%3Abtih: segments and tolerates bare hashes by promoting them to magnet:?xt=urn:btih:<hash>.
• Appends only browser-safe WSS trackers plus optional extras, avoiding mixed content.
• Adds HTTPS web seeds (ws=) and torrent hints (xs=) when provided, skipping insecure http:// web seeds unless the app itself is served via HTTP.
• Preserves existing parameters in their original form—no new URL() usage and no percent re-encoding of the xt payload.

5.2 probeUrl(url)

• HEAD request to check availability; expects 2xx and (ideally) Accept-Ranges: bytes.
• Fallback small GET with Range: bytes=0-1023 can be used if certain hosts block HEAD.
• Returns boolean ok.

5.3 playVideoWithFallback({ url, magnet })

• Try playHttp(url) if probeUrl(url) passes.
• Else try playViaWebTorrent(magnet).
• Show UI error if neither source available.

5.4 playViaWebTorrent(magnet)

• Uses existing torrentClient.streamVideo(magnet, videoEl) under the hood.
• Benefits if magnet contains ws/xs for bootstrap.

---

6) Markup Contracts

• Cards: add both attributes where applicable:

  • data-play-url="<encoded URL or empty>"
  • data-play-magnet="<raw magnet or empty>"

• Click delegate: look for a closest element bearing either attribute; decode both data-play-url and data-play-magnet (if encoded upstream) before passing them to playback logic. Never double-encode magnets when writing them into the DOM.

---

7) Main vs Unstable — legacy WebTorrent compatibility lessons

Legacy Bitvid posts (v1 / magnet-only) still play on Main. They broke on Unstable because of double-encoded magnets, URL constructors, and strict filters. Apply these rules to stay compatible:

• Raw magnets end-to-end. Store the literal magnet:?xt=urn:btih:... in the DOM and feed that same string into WebTorrent. If you must encode for transport, be sure to decode once when handling clicks.
• No new URL() for magnets. Appending params with URLSearchParams or new URL percent-encodes the xt value and can corrupt legacy hashes. When you need to add trackers or cache-busting params, concatenate plain text (or use normalizeAndAugmentMagnet, which already preserves the payload).
• Converters should allow magnet-only posts. A note is playable when it exposes either a usable magnet or a direct url. Don’t require version >= 2 to keep legacy uploads alive.
• Browser-safe announce list. Ship WSS trackers for browser playback. Skip UDP trackers in the client path and only add ws= hints when they’re HTTPS on HTTPS pages (mixed content gets blocked anyway).

---

8) Server Requirements for Hosted URLs

• CORS: allow the app origin (or *).
• Range requests: ensure Accept-Ranges: bytes.
• Correct MIME: video/mp4, video/webm, application/x-mpegURL, etc.
• Optional: expose Content-Length for better UX/progress.

---

9) P2P Notes for Agents

• ws= (web seed): HTTP(S) base path where the file is fetchable; enables WebTorrent to download pieces even with zero peers.
• xs=: HTTP(S) URL of the .torrent metadata so the client can start promptly without DHT/peer discovery.
• Trackers: Keep WSS trackers for peer discovery; they reduce CDN load when peers exist.

---

10) Interop & Extensions

• Live streams: future option via HLS URLs (MIME application/x-mpegURL). For Nostr live presence, consider NIP‑53 events alongside VOD 1063 entries.
• Adaptive Bitrate + P2P: if ABR is needed with P2P, consider a segment‑sharing overlay (e.g., p2p segment loaders) rather than WebTorrent.
• Uploads (optional): NIP‑96/NIP‑98 flow to obtain a hosted URL, then publish Bitvid/NIP‑94 events.

---

11) Testing Checklist (agents)

• Form validation: title present; ensure (url || magnet) is true; ws and xs appended only for magnet.
• Probe: healthy URL returns ok=true; dead URL hides/badges card; cache prevents re‑probing every render.
• Playback: URL path plays successfully; disconnect network to force WebTorrent path; verify video plays via magnet.
• CORS & Range: verify no console CORS errors; confirm seeking works.
• Events: verify kind 30078 contains url and/or magnet; optional 1063 mirror created correctly.
• Cards: both data-play-url and data-play-magnet present; click handler calls fallback player.

---

12) Guardrails & Do/Don’t

Do

• Fail soft: when URL fails, fall back to magnet without blocking UI.
• Prefer standards: URL + NIP‑94 mirror when possible.
• Degrade gracefully when ws/xs missing; torrent should still work with peers.

Don’t

• Don’t require magnet if URL is provided (and vice versa).
• Don’t assume CORS/Range are configured—probe and message helpfully.
• Don’t block the main thread with large HEAD/GETs; keep probes lightweight with timeouts.

---

13) Quick Reference (snippets)

Bitvid content object (30078)

const content = {
  version: 2,
  title,
  url,            // optional but preferred
  magnet,         // optional but preferred
  thumbnail,      // optional
  description,    // optional
  mode            // "live" | "dev"
};

Magnet normalization & augmentation

import { normalizeAndAugmentMagnet } from "./js/magnetUtils.js";

const { magnet } = normalizeAndAugmentMagnet(inputMagnetOrInfoHash, {
  webSeed: hostedUrl ? [hostedUrl] : [],
  torrentUrl: xsHint,
  extraTrackers: ["wss://tracker.openwebtorrent.com"],
});

// Feed `magnet` directly to playVideoWithFallback / WebTorrent.

Playback with fallback

async function playVideoWithFallback({ url, magnet }) {
  if (url && await probeUrl(url)) return playHttp(url);
  if (magnet) return playViaWebTorrent(magnet);
  throw new Error("No playable source");
}

---

14) Roadmap Hooks (where to extend)

• Analytics: Keep using your existing 30078 analytics/logging. Add fields for play_source: "url"|"torrent" to measure cost savings.
• Integrity: Optionally compute SHA‑256 of the hosted file (off‑thread) and publish as NIP‑94 ["x", hash] tag.
• Moderation: Add a background task to periodically probe and mark dead links; publish a lightweight status event so other Bitvid clients learn from each other.

---

End of AGENTS.md