mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 16:02:26 +00:00
54 lines
2.7 KiB
Markdown
54 lines
2.7 KiB
Markdown
# NIP-71 Video Events Module (`js/nostr/nip71.js`)
|
|
|
|
This module implements the **NIP-71** specification for video events in BitVid. It handles the lifecycle of video metadata, including creation, parsing, caching, and association with playable video notes (Kind 30078).
|
|
|
|
## Core Responsibilities
|
|
|
|
1. **Event Building**: Constructs NIP-71 events (Kind 22/21) with standardized tags (`imeta`, `segment`, `p`, etc.).
|
|
2. **Parsing**: Extracts structured metadata from raw Nostr events.
|
|
3. **Caching**: Manages a memory cache of NIP-71 metadata, indexed by video root ID, event ID, and `d` tags.
|
|
4. **Hydration**: Merges cached NIP-71 metadata into legacy or standard video objects for the UI.
|
|
|
|
## Typical Data Flow
|
|
|
|
### 1. Publishing a Video
|
|
When a user uploads a video, `Nip71FormManager` (in `js/ui/`) collects metadata and calls:
|
|
```javascript
|
|
import { buildNip71VideoEvent } from './js/nostr/nip71.js';
|
|
|
|
const event = buildNip71VideoEvent({
|
|
metadata: { ... }, // title, summary, imeta, etc.
|
|
pubkey: userPubkey,
|
|
title: "My Video",
|
|
pointerIdentifiers: { videoRootId: "..." }
|
|
});
|
|
// Sign and publish `event`
|
|
```
|
|
|
|
### 2. Viewing the Feed
|
|
The app fetches video notes (Kind 30078) and potential NIP-71 metadata events (Kind 22/21).
|
|
1. **Ingestion**: `processNip71Events(events, { nip71Cache })` parses incoming NIP-71 events and updates the cache.
|
|
2. **Hydration**: `mergeNip71MetadataIntoVideo(video, { nip71Cache })` attaches the best available metadata to the video object.
|
|
- It checks `videoRootId` -> `eventId` -> `d` tag priority.
|
|
- Falls back to the most recent metadata if specific pointers miss.
|
|
|
|
## Key Exports
|
|
|
|
| Function | Purpose |
|
|
|----------|---------|
|
|
| `buildNip71VideoEvent` | Creates a signed-ready NIP-71 event object. |
|
|
| `extractNip71MetadataFromTags` | Parses a raw event into `{ metadata, pointers }`. |
|
|
| `processNip71Events` | Updates the global `nip71Cache` with new events. |
|
|
| `mergeNip71MetadataIntoVideo` | Enriches a video object with cached metadata. |
|
|
| `populateNip71MetadataForVideos` | Batch-fetches metadata for a list of videos (if missing). |
|
|
|
|
## Invariants & Assumptions
|
|
|
|
- **Video Root ID**: The stable identifier for a video series/content, usually the `d` tag of the first Kind 30078 note.
|
|
- **Cache Structure**: The `nip71Cache` is a `Map<VideoRootId, CacheEntry>`.
|
|
- **Immutability**: Metadata objects in the cache are cloned before being attached to video objects to prevent mutation side-effects.
|
|
|
|
## When to Refactor
|
|
- If the cache logic becomes too complex or memory-intensive, move `nip71Cache` to a dedicated `Nip71Service` or `CacheService`.
|
|
- If NIP-71 spec changes significantly, versioning logic in `extractNip71MetadataFromTags` may need expansion.
|