nips/71.md

NIP-71
======

Video Events
---------------

`draft` `optional`

This specification defines video events representing a dedicated post of externally hosted content. These video events are _parameterized replaceable_ and deletable per [NIP-09](09.md). The content of a video event is the stringified JSON of a `kind 1063` File metadata event as described in [NIP-94](94.md).

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: horizontal and vertical video events. This is meant to allow clients to cater to each as the viewing experience for horizontal (landscape) videos is often different than that of vertical (portrait) videos (Stories, Reels, Shorts, etc).

#### Format

The format uses a parameterized replaceable event kind `34235` for horizontal videos and `34236` for vertical videos.

The `.content` of these events is the stringified JSON of a `kind 1063` file metadata event.

The list of tags are as follows:
* `d` (required) universally unique identifier (UUID). Generated by the client creating the video event.
* `e` (required, repeated) reference tag to kind 1063 file metadata event being posted, optional relay information for the file metadata event, optional quality value (low|medium|high)
* `title` (required) title of the video
* `summary` (optional) summary/description of the video
* `url` (optional) a default link to the video data
* `text-track` (optional, repeated) link to WebVTT file for video, type of supplementary information (captions/subtitles/chapters/metadata), optional language code
* `thumb` (optional) url of thumbnail with same aspect ratio
* `content-warning` (optional) warning about content of NSFW video
* `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

```json
{
  "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": "<stringified JSON of kind 1063 event>",
  "tags": [
    ["d", "<UUID>"],
    ["e", "<hex-id>", "<relay-url>", "<optional quality value>"],

    ["title", "<title of video>"],
    ["summary", "<summary of video>"],
    ["thumb", "<thumbnail image for video>"],

    // Video Data
    ["url", "<optional recommended url>"]
    ["text-track", "<url>", "<text track type>", "<optional language>"],
    ["content-warning", "<reason>"],

    // 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>"]
  ]
}
```

## Video View

A video event view is a response to a video event to track a user's view or progress viewing the video.

### Format

The format uses a parameterized replaceable event kind `34237`.

The `.content` of these events is optional and could be a free-form note that acts like a bookmark for the user.

The list of tags are as follows:
* `a` (required) reference tag to kind `34235` or `34236` video event being viewed
* `d` (required) same as `a` reference tag value
* `viewed` (optional, repeated) timestamp of the user's start time in `HH:MM:SS.sss`, timestamp of the user's end time in `HH:MM:SS.sss` 


```json
{
  "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": 34237,
  "content": "<note>",
  "tags": [
    ["a", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>", "<optional relay url>"],
    ["d", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>"],
    ["viewed", <start>, <end>],
  ]
}
```