1NIP-712======34Video Events5------------67`draft` `optional`89This specification defines _video_ events representing a dedicated post of externally hosted content.1011Unlike a `kind:1` event with a video attached, video events are meant to contain all additional metadata concerning the subject media and to be surfaced in video-specific clients rather than general micro-blogging clients. The thought is for events of this kind to be referenced in a Netflix, YouTube, or TikTok like nostr client where the video itself is at the center of the experience.1213## Video Events1415There are two types of video events represented by different kinds: _normal_ and _short_ video events. This is meant to allow clients to cater to each as the viewing experience for longer, mostly horizontal (landscape) videos is often different than that of short-form, mostly vertical (portrait), videos ("stories", "reels", "shorts" etc).1617Nothing except cavaliership and common sense prevents a _short_ video from being long, or a _normal_ video from being vertical, and that may or may not be justified, it's mostly a stylistic qualitative difference, not a question of actual raw size.1819#### Format2021The format uses a _regular event_ kind `21` for _normal_ videos and `22` for _short_ videos.2223## Addressable Video Events2425For content that may need updates after publication (such as correcting metadata, descriptions, or handling URL migrations), addressable versions are available:2627- Kind `34235` for _addressable normal videos_28- Kind `34236` for _addressable short videos_2930These addressable events follow the same format as their regular counterparts but include a `d` tag as a unique identifier and can be updated while maintaining the same addressable reference. This is particularly useful for:3132- Metadata corrections (descriptions, titles, tags) without republishing33- Preservation of imported content IDs from legacy platforms34- URL migration when hosting changes35- Platform migration tracking3637The `.content` of these events is a summary or description on the video content.3839The primary source of video information is the `imeta` tags which is defined in [NIP-92](92.md)4041Each `imeta` tag can be used to specify a variant of the video by the `dim` & `m` properties, as well as multiple audio tracks (languages).4243Clients should check if audio tracks are available and prefer them over in-video audio 44to allow smooth resolution switching without interrupting audio. The `ov` (original version) flags the original language track.4546This NIP defines the following additional `imeta` properties aside from those listed in [NIP-92](92.md) & [NIP-94](94.md):4748* `duration` (recommended) the duration of the video/audio in seconds (floating point number)49* `bitrate` (recommended) the average bitrate of the video/audio in bits/sec50* `waveform` (optional, audio only) amplitude values over time, space separated full integers, less than 100 values should be enough to render a nice visual5152Example:53```json54[55 ["imeta",56 "dim 1920x1080",57 "url https://myvideo.com/1080/12345.mp4",58 "x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc",59 "m video/mp4",60 "image https://myvideo.com/1080/12345.jpg",61 "image https://myotherserver.com/1080/12345.jpg",62 "fallback https://myotherserver.com/1080/12345.mp4",63 "fallback https://andanotherserver.com/1080/12345.mp4",64 "service nip96",65 "bitrate 3000000",66 "duration 29.223"67 ],68 ["imeta",69 "dim 1280x720",70 "url https://myvideo.com/720/12345.mp4",71 "x e1d4f808dae475ed32fb23ce52ef8ac82e3cc760702fca10d62d382d2da3697d",72 "m video/mp4",73 "image https://myvideo.com/720/12345.jpg",74 "image https://myotherserver.com/720/12345.jpg",75 "fallback https://myotherserver.com/720/12345.mp4",76 "fallback https://andanotherserver.com/720/12345.mp4",77 "service nip96",78 "bitrate 2000000",79 "duration 29.24"80 ],81 ["imeta",82 "dim 1280x720",83 "url https://myvideo.com/720/12345.m3u8",84 "x 704e720af2697f5d6a198ad377789d462054b6e8d790f8a3903afbc1e044014f",85 "m application/x-mpegURL",86 "image https://myvideo.com/720/12345.jpg",87 "image https://myotherserver.com/720/12345.jpg",88 "fallback https://myotherserver.com/720/12345.m3u8",89 "fallback https://andanotherserver.com/720/12345.m3u8",90 "service nip96",91 "duration 29.21"92 ],93 ["imeta",94 "url https://myaudio.com/audio/en/12345.mp3",95 "x b2e0a7a82ac9f3f3a71f1d9a78c381d5be9d1cf19dce258765c17c8a76287c93",96 "m audio/mp3",97 "waveform 0 7 35 8 100 100 49 8 4 16 8 10 7 2 20 10 100 100 100 100 100 100 15 100 100 100 25 60 5 4 3 1 0 100 100 15 100 29 88 0 33 11 39 100 100 19 4 100 42 35 5 0 1 5 0 0 11 38 100 94 17 11 44 58 5 100 100 100 55 14 72 100 100 57 6 1 14 2 16 100 100 40 16 100 100 6 32 14 13 41 36 16 14 6 3 0 1 2 1 6 0",98 "l en ISO-639-1 ov",99 "fallback https://myotherserver.com/audio/en/12345.mp3",100 "fallback https://andanotherserver.com/audio/en/12345.mp3",101 "service nip96",102 "bitrate 320000",103 "duration 29.24"104 ],105]106```107108Where `url` is the primary server url and `fallback` are other servers hosting the same file, both `url` and `fallback` should be weighted equally and clients are recommended to use any of the provided video urls.109110The `image` tag contains a preview image (at the same resolution). Multiple `image` tags may be used to specify fallback copies in the same way `fallback` is used for `url`.111112Additionally `service nip96` may be included to allow clients to search the authors NIP-96 server list to find the file using the hash.113114### Required tags for addressable events:115* `d` - Unique identifier for this video (user-chosen string, required for kinds 34235, 34236)116117### Other tags:118* `title` (required) title of the video119* `published_at`, for the timestamp in unix seconds (stringified) of the first time the video was published120* `text-track` (optional, repeated) link to WebVTT file for video, type of supplementary information (captions/subtitles/chapters/metadata), optional language code121* `content-warning` (optional) warning about content of NSFW video122* `alt` (optional) description for accessibility123* `segment` (optional, repeated) start timestamp in format `HH:MM:SS.sss`, end timestamp in format `HH:MM:SS.sss`, chapter/segment title, chapter thumbnail-url124* `t` (optional, repeated) hashtag to categorize video125* `p` (optional, repeated) 32-bytes hex pubkey of a participant in the video, optional recommended relay URL126* `r` (optional, repeated) references / links to web pages127128### Optional tags for imported content:129* `origin` - Track original platform and ID: `["origin", "<platform>", "<external-id>", "<original-url>", "<optional-metadata>"]`130131```yaml132{133 "id": "<32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>",134 "pubkey": "<32-bytes lowercase hex-encoded public key of the event creator>",135 "created_at": <Unix timestamp in seconds>,136 "kind": 21 | 22,137 "content": "<summary / description of video>",138 "tags": [139 ["title", "<title of video>"],140 ["published_at", "<unix timestamp>"],141 ["alt", "<description>"],142143 // video Data144 ["imeta",145 "dim 1920x1080",146 "url https://myvideo.com/1080/12345.mp4",147 "x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc",148 "m video/mp4",149 "image https://myvideo.com/1080/12345.jpg",150 "image https://myotherserver.com/1080/12345.jpg",151 "fallback https://myotherserver.com/1080/12345.mp4",152 "fallback https://andanotherserver.com/1080/12345.mp4",153 "service nip96",154 ],155156 ["text-track", "<encoded `kind 6000` event>", "<recommended relay urls>"],157 ["content-warning", "<reason>"],158 ["segment", <start>, <end>, "<title>", "<thumbnail URL>"],159160 // participants161 ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],162 ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],163164 // hashtags165 ["t", "<tag>"],166 ["t", "<tag>"],167168 // reference links169 ["r", "<url>"],170 ["r", "<url>"]171 ]172}173```174175## Addressable Event Example176177```yaml178{179 "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,180 "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,181 "created_at": <Unix timestamp in seconds>,182 "kind": 34235 | 34236,183 "content": "<summary / description of video>",184 "tags": [185 ["d", "<unique-identifier>"],186 ["title", "<title of video>"],187 ["published_at", "<unix timestamp>"],188 ["alt", "<description for accessibility>"],189190 // video data191 ["imeta",192 "url https://example.com/media.mp4",193 "m video/mp4",194 "dim 480x480",195 "blurhash eVF$^OI:${M{%LRjWBoLoLaeR*",196 "image https://example.com/thumb.jpg",197 "x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc"198 ],199 // audio data200 ["imeta",201 "url https://example.com/audio.mp3",202 "x b2e0a7a82ac9f3f3a71f1d9a78c381d5be9d1cf19dce258765c17c8a76287c93",203 "m audio/mp3",204 "l en ISO-639-1 ov"205 ],206207 ["duration", <duration in seconds>],208 ["content-warning", "<reason>"],209210 // origin tracking for imported content211 ["origin", "<platform>", "<external-id>", "<original-url>", "<optional-metadata>"],212213 // participants214 ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],215216 // hashtags217 ["t", "<tag>"],218 ["t", "<tag>"],219220 // reference links221 ["r", "<url>"]222 ]223}224```225226## Referencing Addressable Events227228To reference an addressable video:229230```231["a", "34235:<pubkey>:<d-tag-value>", "<relay-url>"] // for normal videos232["a", "34236:<pubkey>:<d-tag-value>", "<relay-url>"] // for short videos233```