NIP-53
======

Live Activities
---------------

`draft` `optional`

Service providers want to offer live activities to the Nostr network in such a way that participants can easily log and query by clients. This NIP describes a general framework to advertise the involvement of pubkeys in such live activities.

## Concepts

### Live Event

A special event with `kind:30311` "Live Event" is defined as an _addressable event_ of public `p` tags. Each `p` tag SHOULD have a **displayable** marker name for the current role (e.g. `Host`, `Speaker`, `Participant`) of the user in the event and the relay information MAY be empty. This event will be constantly updated as participants join and leave the activity.

For example:

```jsonc
{
  "kind": 30311,
  "tags": [
    ["d", "<unique identifier>"],
    ["title", "<name of the event>"],
    ["summary", "<description>"],
    ["image", "<preview image url>"],
    ["t", "hashtag"]
    ["streaming", "<url>"],
    ["recording", "<url>"], // used to place the edited video once the activity is over
    ["starts", "<unix timestamp in seconds>"],
    ["ends", "<unix timestamp in seconds>"],
    ["status", "<planned, live, ended>"],
    ["current_participants", "<number>"],
    ["total_participants", "<number>"],
    ["p", "91cf9..4e5ca", "wss://provider1.com/", "Host", "<proof>"],
    ["p", "14aeb..8dad4", "wss://provider2.com/nostr", "Speaker"],
    ["p", "612ae..e610f", "ws://provider3.com/ws", "Participant"],
    ["relays", "wss://one.com", "wss://two.com", /*...*/],
    ["pinned", "<event id of pinned live chat message>"],
  ],
  "content": "",
  // other fields...
}
```

A distinct `d` tag should be used for each activity. All other tags are optional.

Providers SHOULD keep the participant list small (e.g. under 1000 users) and, when limits are reached, Providers SHOULD select which participants get named in the event. Clients should not expect a comprehensive list. Once the activity ends, the event can be deleted or updated to summarize the activity and provide async content (e.g. recording of the event).

Clients are expected to subscribe to `kind:30311` events in general or for given follow lists and statuses. Clients MAY display participants' roles in activities as well as access points to join the activity.

Live Activity management clients are expected to constantly update `kind:30311` during the event. Clients MAY choose to consider `status=live` events after 1hr without any update as `ended`. The `starts` and `ends` timestamp SHOULD be updated when the status changes to and from `live`

The activity MUST be linked to using the [NIP-19](19.md) `naddr` code along with the `a` tag.

### Proof of Agreement to Participate

Event owners can add proof as the 5th term in each `p` tag to clarify the participant's agreement in joining the event. The proof is a signed SHA256 of the complete `a` Tag of the event (`kind:pubkey:dTag`) by each `p`'s private key, encoded in hex.

Clients MAY only display participants if the proof is available or MAY display participants as "invited" if the proof is not available.

This feature is important to avoid malicious event owners adding large account holders to the event, without their knowledge, to lure their followers into the malicious owner's trap.

### Live Chat Message

Event `kind:1311` is live chat's channel message. Clients MUST include the `a` tag of the activity. An `e` tag denotes the direct parent message this post is replying to. 

```jsonc
{
  "kind": 1311,
  "tags": [
    ["a", "30311:<Community event author pubkey>:<d-identifier of the community>", "<Optional relay url>", "root"],
  ],
  "content": "Zaps to live streams is beautiful.",
  // other fields...
}
```

`q` tags MAY be used when citing events in the `.content` with [NIP-21](21.md).

```json
["q", "<event-id> or <event-address>", "<relay-url>", "<pubkey-if-a-regular-event>"]
```

Hosts may choose to pin one or more live chat messages by updating the `pinned` tags in the live event kind `30311`.

### Stream Raids

Event `kind:1312` is a live stream raid (redirect viewers to another stream).

Clients MUST include two `a` tags, one marked as `from` and the other marked as `to` which redirects viewers to a new live stream.
The `content` MAY contain a raid message.

Clients SHOULD automatically redirect viewers from one stream to another. 
This is a similar function used on Twitch also called raids.

```jsonc
{
  "kind": 1312,
  "tags": [
    ["a", "30311:<Community event author pubkey>:<d-identifier of the community>", "<Optional relay url>", "from"],
    ["a", "30311:<Community event author pubkey>:<d-identifier of the community>", "<Optional relay url>", "to"],
  ],
  "content": "Zap this epic streamer!",
  // other fields...
}
```

### Stream Clips

Event `kind:1313` is a live stream clip.

A clip is a small video clip taken from the live stream used to highlight a specific memorable or entertaining part of the stream.

Clients MUST include one `a` tag which points to the live stream event which the clip was taken from.

Clients MUST include one `r` tag which is a URL pointing to the video clip file, preferably in MP4 format for maximum compatibility.

Clients MAY also include a message about the clip in the `title` tag.

```jsonc
{
  "kind": 1313,
  "tags": [
    ["a", "30311:<Community event author pubkey>:<d-identifier of the community>", "<Optional relay url>", "root"],
    ["r", "https://example.com/my-clip.mp4"],
    ["title", "Streamer gets rekt by bot!"]
  ],
  "content": "",
  // other fields...
}
```

### Stream Timeout

Event `kind:1314` is a live chat moderation event that temporarily mutes a user from chatting.

Clients MUST include one or more `p` tags of the timed out users.

Clients MUST include a [NIP-40](./40.md) expiration timestamp which signals when the timeout will end.

Clients SHOULD enfore timeouts by disabling chat functions in their apps and not displaying any chat messages from the user during their timeout.

Clients SHOULD listen for timeout events published by the stream host.

Clients MAY include a reason for the timeout in the `content` field.

```jsonc
{
  "kind": 1314,
  "tags": [
    ["p", "<pubkey-of-muted-user>"],
    ["expiration", "1747658333"]
  ],
  "content": "Rude",
  // other fields...
}
```

## Use Cases

Common use cases include meeting rooms/workshops, watch-together activities, or event spaces, such as [zap.stream](https://zap.stream).

## Example

### Live Streaming

```json
{
  "id": "57f28dbc264990e2c61e80a883862f7c114019804208b14da0bff81371e484d2",
  "pubkey": "1597246ac22f7d1375041054f2a4986bd971d8d196d7997e48973263ac9879ec",
  "created_at": 1687182672,
  "kind": 30311,
  "tags": [
    ["d", "demo-cf-stream"],
    ["title", "Adult Swim Metalocalypse"],
    ["summary", "Live stream from IPTV-ORG collection"],
    ["streaming", "https://adultswim-vodlive.cdn.turner.com/live/metalocalypse/stream.m3u8"],
    ["starts", "1687182672"],
    ["status", "live"],
    ["t", "animation"],
    ["t", "iptv"],
    ["image", "https://i.imgur.com/CaKq6Mt.png"]
  ],
  "content": "",
  "sig": "5bc7a60f5688effa5287244a24768cbe0dcd854436090abc3bef172f7f5db1410af4277508dbafc4f70a754a891c90ce3b966a7bc47e7c1eb71ff57640f3d389"
}
```

### Live Streaming chat message

```json
{
  "id": "97aa81798ee6c5637f7b21a411f89e10244e195aa91cb341bf49f718e36c8188",
  "pubkey": "3f770d65d3a764a9c5cb503ae123e62ec7598ad035d836e2a810f3877a745b24",
  "created_at": 1687286726,
  "kind": 1311,
  "tags": [
    ["a", "30311:1597246ac22f7d1375041054f2a4986bd971d8d196d7997e48973263ac9879ec:demo-cf-stream", "", "root"]
  ],
  "content": "Zaps to live streams is beautiful.",
  "sig": "997f62ddfc0827c121043074d50cfce7a528e978c575722748629a4137c45b75bdbc84170bedc723ef0a5a4c3daebf1fef2e93f5e2ddb98e5d685d022c30b622"
}
```