laantungir/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2026-07-22 07:48:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
nips/71.md
fiatjaf 999f9bfbf5 ``jsonc -> ``yaml everywhere.
2026-06-13 09:19:49 -03:00

234 lines
9.5 KiB
Markdown
Raw Permalink Blame History

NIP-71
======
Video Events
------------
`draft` `optional`
This specification defines _video_ events representing a dedicated post of externally hosted content.
Unlike 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.
## Video Events
There 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).
Nothing 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.
#### Format
The format uses a _regular event_ kind `21` for _normal_ videos and `22` for _short_ videos.
## Addressable Video Events
For content that may need updates after publication (such as correcting metadata, descriptions, or handling URL migrations), addressable versions are available:
- Kind `34235` for _addressable normal videos_
- Kind `34236` for _addressable short videos_
These 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:
- Metadata corrections (descriptions, titles, tags) without republishing
- Preservation of imported content IDs from legacy platforms
- URL migration when hosting changes
- Platform migration tracking
The `.content` of these events is a summary or description on the video content.
The primary source of video information is the `imeta` tags which is defined in [NIP-92](92.md)
Each `imeta` tag can be used to specify a variant of the video by the `dim` & `m` properties, as well as multiple audio tracks (languages).
Clients should check if audio tracks are available and prefer them over in-video audio
to allow smooth resolution switching without interrupting audio. The `ov` (original version) flags the original language track.
This NIP defines the following additional `imeta` properties aside from those listed in [NIP-92](92.md) & [NIP-94](94.md):
* `duration` (recommended) the duration of the video/audio in seconds (floating point number)
* `bitrate` (recommended) the average bitrate of the video/audio in bits/sec
* `waveform` (optional, audio only) amplitude values over time, space separated full integers, less than 100 values should be enough to render a nice visual
Example:
```json
[
["imeta",
"dim 1920x1080",
"url https://myvideo.com/1080/12345.mp4",
"x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc",
"m video/mp4",
"image https://myvideo.com/1080/12345.jpg",
"image https://myotherserver.com/1080/12345.jpg",
"fallback https://myotherserver.com/1080/12345.mp4",
"fallback https://andanotherserver.com/1080/12345.mp4",
"service nip96",
"bitrate 3000000",
"duration 29.223"
],
["imeta",
"dim 1280x720",
"url https://myvideo.com/720/12345.mp4",
"x e1d4f808dae475ed32fb23ce52ef8ac82e3cc760702fca10d62d382d2da3697d",
"m video/mp4",
"image https://myvideo.com/720/12345.jpg",
"image https://myotherserver.com/720/12345.jpg",
"fallback https://myotherserver.com/720/12345.mp4",
"fallback https://andanotherserver.com/720/12345.mp4",
"service nip96",
"bitrate 2000000",
"duration 29.24"
],
["imeta",
"dim 1280x720",
"url https://myvideo.com/720/12345.m3u8",
"x 704e720af2697f5d6a198ad377789d462054b6e8d790f8a3903afbc1e044014f",
"m application/x-mpegURL",
"image https://myvideo.com/720/12345.jpg",
"image https://myotherserver.com/720/12345.jpg",
"fallback https://myotherserver.com/720/12345.m3u8",
"fallback https://andanotherserver.com/720/12345.m3u8",
"service nip96",
"duration 29.21"
],
["imeta",
"url https://myaudio.com/audio/en/12345.mp3",
"x b2e0a7a82ac9f3f3a71f1d9a78c381d5be9d1cf19dce258765c17c8a76287c93",
"m audio/mp3",
"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",
"l en ISO-639-1 ov",
"fallback https://myotherserver.com/audio/en/12345.mp3",
"fallback https://andanotherserver.com/audio/en/12345.mp3",
"service nip96",
"bitrate 320000",
"duration 29.24"
],
]
```
Where `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.
The `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`.
Additionally `service nip96` may be included to allow clients to search the authors NIP-96 server list to find the file using the hash.
### Required tags for addressable events:
* `d` - Unique identifier for this video (user-chosen string, required for kinds 34235, 34236)
### Other tags:
* `title` (required) title of the video
* `published_at`, for the timestamp in unix seconds (stringified) of the first time the video was published
* `text-track` (optional, repeated) link to WebVTT file for video, type of supplementary information (captions/subtitles/chapters/metadata), optional language code
* `content-warning` (optional) warning about content of NSFW video
* `alt` (optional) description for accessibility
* `segment` (optional, repeated) start timestamp in format `HH:MM:SS.sss`, end timestamp in format `HH:MM:SS.sss`, chapter/segment title, chapter thumbnail-url
* `t` (optional, repeated) hashtag to categorize video
* `p` (optional, repeated) 32-bytes hex pubkey of a participant in the video, optional recommended relay URL
* `r` (optional, repeated) references / links to web pages
### Optional tags for imported content:
* `origin` - Track original platform and ID: `["origin", "<platform>", "<external-id>", "<original-url>", "<optional-metadata>"]`
```yaml
{
"id": "<32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>",
"pubkey": "<32-bytes lowercase hex-encoded public key of the event creator>",
"created_at": <Unix timestamp in seconds>,
"kind": 21 | 22,
"content": "<summary / description of video>",
"tags": [
["title", "<title of video>"],
["published_at", "<unix timestamp>"],
["alt", "<description>"],
// video Data
["imeta",
"dim 1920x1080",
"url https://myvideo.com/1080/12345.mp4",
"x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc",
"m video/mp4",
"image https://myvideo.com/1080/12345.jpg",
"image https://myotherserver.com/1080/12345.jpg",
"fallback https://myotherserver.com/1080/12345.mp4",
"fallback https://andanotherserver.com/1080/12345.mp4",
"service nip96",
],
["text-track", "<encoded `kind 6000` event>", "<recommended relay urls>"],
["content-warning", "<reason>"],
["segment", <start>, <end>, "<title>", "<thumbnail URL>"],
// participants
["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],
["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],
// hashtags
["t", "<tag>"],
["t", "<tag>"],
// reference links
["r", "<url>"],
["r", "<url>"]
]
}
```
## Addressable Event Example
```yaml
{
"id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,
"pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
"created_at": <Unix timestamp in seconds>,
"kind": 34235 | 34236,
"content": "<summary / description of video>",
"tags": [
["d", "<unique-identifier>"],
["title", "<title of video>"],
["published_at", "<unix timestamp>"],
["alt", "<description for accessibility>"],
// video data
["imeta",
"url https://example.com/media.mp4",
"m video/mp4",
"dim 480x480",
"blurhash eVF$^OI:${M{%LRjWBoLoLaeR*",
"image https://example.com/thumb.jpg",
"x 3093509d1e0bc604ff60cb9286f4cd7c781553bc8991937befaacfdc28ec5cdc"
],
// audio data
["imeta",
"url https://example.com/audio.mp3",
"x b2e0a7a82ac9f3f3a71f1d9a78c381d5be9d1cf19dce258765c17c8a76287c93",
"m audio/mp3",
"l en ISO-639-1 ov"
],
["duration", <duration in seconds>],
["content-warning", "<reason>"],
// origin tracking for imported content
["origin", "<platform>", "<external-id>", "<original-url>", "<optional-metadata>"],
// participants
["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"],
// hashtags
["t", "<tag>"],
["t", "<tag>"],
// reference links
["r", "<url>"]
]
}
```
## Referencing Addressable Events
To reference an addressable video:
```
["a", "34235:<pubkey>:<d-tag-value>", "<relay-url>"] // for normal videos
["a", "34236:<pubkey>:<d-tag-value>", "<relay-url>"] // for short videos
```
Reference in New Issue View Git Blame Copy Permalink