Kind 21: Video Event

Overview

Video Events (kind 21) are designed for sharing externally hosted video content with rich metadata. Unlike a regular text note with a video link, these events are specifically created for video-centric clients that place the video at the center of the user experience, similar to platforms like YouTube or Netflix.

Specification

Property	Value
Kind Number	21
Event Range	Regular
Defined in	NIP-71

Content Format

The content field contains a summary or description of the video content.

Schema

"content": "A documentary exploring the natural landscape of the Amazon rainforest, showcasing its diverse wildlife and ecosystem."

Tags

Tag Name	Description	Format	Required
title	Title of the video	["title", "Amazon Rainforest Documentary"]	Yes
imeta	Video metadata	["imeta", "url https://example.com/video.mp4", "m video/mp4", ...]	Yes (at least one)
published_at	Original publication timestamp	["published_at", "1671217000"]	Recommended
duration	Video length in seconds	["duration", "3600"]	Recommended
text-track	Links to WebVTT files	["text-track", "<encoded event>", "<relay-url>"]	No
content-warning	Warning for sensitive content	["content-warning", "violence"]	Conditionally
alt	Accessibility description	["alt", "Documentary about Amazon rainforest"]	Recommended
segment	Chapter markers	["segment", "00:05:20.000", "00:12:15.500", "Wildlife", "https://example.com/thumb1.jpg"]	No
t	Hashtags	["t", "documentary"]	Recommended
p	Participants in the video	["p", "<pubkey-hex>", "<relay-url>"]	No
r	Web references	["r", "https://example.com/article"]	No

Video Metadata (imeta)

The imeta tag can contain several attributes:

• url: URL to the video (required)
• m: MIME type (required)
• dim: Dimensions in format "widthxheight" (recommended)
• x: SHA-256 hash for verification (recommended)
• image: Preview image URL (recommended)
• fallback: Alternative video URLs (optional)
• service: Service type, e.g., "nip96" (optional)

Multiple imeta tags can be used to provide different quality levels or formats of the same video.

Client Behavior

Clients should:

1. Display videos as the primary content, with description as secondary
2. Offer appropriate playback controls based on the video type and size
3. Support selection between different quality levels when multiple imeta tags are present
4. Display preview images while the video is loading
5. Show chapter markers when segment tags are available
6. Make proper use of fallback URLs when the primary URL is unavailable
7. Support subtitles and captions via WebVTT when available

Relay Behavior

Relays should:

1. Store these events like other regular events
2. Support queries by kind 21, by hashtags, and by video hashes

Use Cases

• Long-form video content
• Movie or TV show sharing
• Educational videos
• Documentaries
• Horizontal/landscape aspect ratio videos
• High-resolution video content

Example

{
  "id": "4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65",
  "pubkey": "79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3",
  "created_at": 1671217411,
  "kind": 21,
  "content": "My documentary about the Amazon rainforest explores the incredible biodiversity and the challenges faced by this unique ecosystem.",
  "tags": [
    ["title", "Amazon Rainforest: A Journey Into the Wild"],
    ["published_at", "1671190000"],
    ["alt", "A documentary exploring the Amazon rainforest, its wildlife and conservation challenges"],
    ["imeta",
      "dim 1920x1080",
      "url https://videos.example.com/amazon-doc-1080p.mp4",
      "x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc",
      "m video/mp4",
      "image https://videos.example.com/amazon-doc-thumb.jpg",
      "fallback https://mirror.example.org/amazon-doc-1080p.mp4",
      "service nip96"
    ],
    ["imeta",
      "dim 1280x720",
      "url https://videos.example.com/amazon-doc-720p.mp4",
      "x e1d4f808dae475ed32fb23ce52ef8ac82e3cc760702fca10d62d382d2da3697d",
      "m video/mp4",
      "image https://videos.example.com/amazon-doc-thumb-720p.jpg",
      "fallback https://mirror.example.org/amazon-doc-720p.mp4",
      "service nip96"
    ],
    ["duration", "3600"],
    ["text-track", "eyJpZCI6ImEyOWI...hI6ImVuIn0=", "wss://relay.example.com"],
    ["segment", "00:00:00.000", "00:05:30.000", "Introduction", "https://videos.example.com/thumb1.jpg"],
    ["segment", "00:05:30.000", "00:20:15.000", "Biodiversity", "https://videos.example.com/thumb2.jpg"],
    ["segment", "00:20:15.000", "00:35:45.000", "Indigenous Communities", "https://videos.example.com/thumb3.jpg"],
    ["segment", "00:35:45.000", "01:00:00.000", "Conservation Efforts", "https://videos.example.com/thumb4.jpg"],
    ["p", "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca", "wss://relay.example.com"],
    ["t", "documentary"],
    ["t", "amazon"],
    ["t", "conservation"],
    ["t", "wildlife"],
    ["r", "https://example.com/amazon-conservation"]
  ],
  "sig": "908a15e46fb4d8675bab026fc230a0e3542bfade63da02d542fb78b2a8513fcd0092619a2c8c1221e581946e0191f2af505dfdf8657a414dbca329186f009262"
}

Multi-Quality Support

Video Events support multiple quality options through additional imeta tags. This allows:

1. Different resolutions (e.g., 1080p, 720p, 480p)
2. Different formats (e.g., mp4, HLS streams with .m3u8)
3. Adaptive streaming options
4. Different source servers

Clients should offer quality selection to users based on their connection speed and preferences.

References

• NIP-71: Video Events
• NIP-92: Media Attachments
• NIP-96: HTTP File Storage Integration

Related Kinds

• Kind 1: Short Text Note - Text-focused content that might include video links
• Kind 20: Picture - Image-focused content
• Kind 22: Short-form Portrait Video - Vertical short-form video content

Notes

• While video content is externally hosted, the event includes comprehensive metadata to enhance the viewing experience.
• The distinction between kind 21 (regular videos) and kind 22 (short-form portrait videos) allows clients to provide appropriate viewing experiences.
• Quality variants through multiple imeta tags enable adaptive viewing across different devices and connection speeds.
• Chapter markers via segment tags can enhance navigation for longer content.
• WebVTT support via text-track enables subtitles, captions, and other text-synchronized features.