NAME
Net::Nostr::LiveActivity - NIP-53 Live Activities
SYNOPSIS
use Net::Nostr::LiveActivity;
# Live streaming event (kind 30311)
my $event = Net::Nostr::LiveActivity->live_event(
pubkey => $hex_pubkey,
identifier => 'my-stream',
title => 'My Stream',
status => 'live',
);
# Live chat message (kind 1311)
my $event = Net::Nostr::LiveActivity->chat_message(
pubkey => $hex_pubkey,
activity => "30311:$author_pk:$d_id",
content => 'Hello!',
);
# Meeting space (kind 30312)
my $event = Net::Nostr::LiveActivity->meeting_space(
pubkey => $hex_pubkey,
identifier => 'main-room',
room => 'Main Conference Hall',
status => 'open',
service => 'https://meet.example.com/room',
participants => [[$host_pk, 'wss://relay.com/', 'Host']],
);
# Meeting room event (kind 30313)
my $event = Net::Nostr::LiveActivity->meeting_room(
pubkey => $hex_pubkey,
identifier => 'annual-meeting',
space_ref => ["30312:$space_pk:main-room", 'wss://relay.com'],
title => 'Annual Meeting',
starts => '1676262123',
status => 'planned',
);
# Room presence (kind 10312)
my $event = Net::Nostr::LiveActivity->room_presence(
pubkey => $hex_pubkey,
activity => "30312:$space_pk:main-room",
hand => '1',
);
# Parse any live activity event
my $parsed = Net::Nostr::LiveActivity->from_event($event);
# Validate
Net::Nostr::LiveActivity->validate($event);DESCRIPTION
Implements NIP-53 (Live Activities). Five event kinds are used:
Live Streaming Event (kind 30311) - An addressable event advertising a live stream. Contains tags for title, summary, image, streaming URL, recording URL, start/end times, status, participant counts, hashtags, participant roles, relay lists, and pinned chat messages. Updated continuously as participants join and leave.
Live Chat Message (kind 1311) - A regular event for live chat. MUST include an
atag referencing the parent live activity. MAY include anetag for replies.Meeting Space (kind 30312) - An addressable event defining a virtual interactive space. MUST have
room,status,service, and at least oneptag with a Host role.Meeting Room Event (kind 30313) - An addressable event representing a scheduled or ongoing meeting. MUST reference a parent space via
atag and havetitle,starts, andstatus.Room Presence (kind 10312) - A replaceable event signaling a user's presence in a room. Contains an
atag with the room reference and an optionalhandtag for raised hand.
CONSTRUCTOR
new
my $la = Net::Nostr::LiveActivity->new(
identifier => 'my-stream',
status => 'live',
);Creates a new Net::Nostr::LiveActivity object. Croaks on unknown arguments. Array fields (hashtags, participants, relays, pinned) default to [].
CLASS METHODS
live_event
my $event = Net::Nostr::LiveActivity->live_event(
pubkey => $hex_pubkey, # required
identifier => $id, # required (d tag)
title => $title, # optional
summary => $summary, # optional
image => $url, # optional
streaming => $url, # optional
recording => $url, # optional
starts => $timestamp, # optional
ends => $timestamp, # optional
status => $status, # optional (planned/live/ended)
current_participants => $count, # optional
total_participants => $count, # optional
hashtags => [$tag, ...], # optional (t tags)
participants => [[$pk, $relay, $role, $proof], ...], # optional (p tags)
relays => [$url, ...], # optional (relays tag)
pinned => [$event_id, ...], # optional (pinned tags)
);Creates a kind 30311 live streaming Net::Nostr::Event. Each p tag SHOULD have a displayable role name (e.g. Host, Speaker, Participant). The relay and proof fields in participant entries are optional. Content defaults to ''.
chat_message
my $event = Net::Nostr::LiveActivity->chat_message(
pubkey => $hex_pubkey, # required
activity => "30311:$pk:$d_id", # required (a tag)
relay_hint => $relay_url, # optional
reply_to => $event_id, # optional (e tag)
content => $message, # optional, defaults to ''
);Creates a kind 1311 live chat Net::Nostr::Event. The a tag references the parent live activity. When a relay hint is provided, the a tag includes a root marker.
meeting_space
my $event = Net::Nostr::LiveActivity->meeting_space(
pubkey => $hex_pubkey, # required
identifier => $id, # required (d tag)
room => $name, # required (room tag)
status => $status, # required (open/private/closed)
service => $url, # required (service tag)
participants => [[$pk, $relay, $role, $proof], ...], # required (p tags; $proof optional)
summary => $summary, # optional
image => $url, # optional
endpoint => $url, # optional
hashtags => [$tag, ...], # optional (t tags)
relays => [$url, ...], # optional (relays tag)
);Creates a kind 30312 meeting space Net::Nostr::Event. MUST have at least one provider with a Host role. Status MUST be open, private, or closed. Content defaults to ''.
meeting_room
my $event = Net::Nostr::LiveActivity->meeting_room(
pubkey => $hex_pubkey, # required
identifier => $id, # required (d tag)
space_ref => [$coord, $relay], # required (a tag)
title => $title, # required
starts => $timestamp, # required
status => $status, # required (planned/live/ended)
summary => $summary, # optional
image => $url, # optional
ends => $timestamp, # optional
current_participants => $count, # optional
total_participants => $count, # optional
participants => [[$pk, $relay, $role], ...], # optional
);Creates a kind 30313 meeting room Net::Nostr::Event. The a tag references the parent meeting space. Content defaults to ''.
room_presence
my $event = Net::Nostr::LiveActivity->room_presence(
pubkey => $hex_pubkey, # required
activity => $room_a_tag, # required (a tag)
relay_hint => $relay_url, # optional
hand => '1', # optional (hand raised)
);Creates a kind 10312 room presence Net::Nostr::Event. This is a replaceable event, so presence can only be indicated in one room at a time. The a tag always includes a root marker. When no relay hint is provided, the relay field defaults to ''.
from_event
my $la = Net::Nostr::LiveActivity->from_event($event);Parses a kind 30311, 1311, 30312, 30313, or 10312 event into a Net::Nostr::LiveActivity object. Returns undef for unrecognized kinds.
validate
Net::Nostr::LiveActivity->validate($event);Validates a NIP-53 event. Croaks if:
Kind is not 30311, 1311, 30312, 30313, or 10312
Kind 30311 missing
dtagKind 1311 missing
atagKind 30312 missing
d,room,status,service, orptagKind 30313 missing
d,a,title,starts, orstatustagKind 10312 missing
atag
Returns 1 on success.
ACCESSORS
identifier
The d tag value (kinds 30311, 30312, 30313).
title
Event title (kinds 30311, 30313).
summary
Event description.
image
Preview image URL.
streaming
Live stream URL (kind 30311).
recording
Recording URL (kind 30311).
starts
Start timestamp in seconds.
ends
End timestamp in seconds.
status
Event status. For live events: planned, live, or ended. For meeting spaces: open, private, or closed.
current_participants
Current participant count string.
total_participants
Total participant count string.
hashtags
Arrayref of hashtag strings from t tags. Defaults to [].
participants
Arrayref of arrayrefs from p tags. Each contains [$pubkey, $relay, $role] and optionally a proof field. Defaults to [].
relays
Arrayref of relay URL strings from relays tag. Defaults to [].
pinned
Arrayref of pinned event IDs from pinned tags. Defaults to [].
activity
The a tag coordinate (kinds 1311, 10312).
relay_hint
Relay hint from a tag.
reply_to
Parent event ID from e tag (kind 1311).
room
Room display name from room tag (kind 30312).
service
Service URL from service tag (kind 30312).
endpoint
API endpoint URL from endpoint tag (kind 30312).
space_ref
Arrayref [$coord, $relay] from a tag referencing parent space (kind 30313).
hand
Hand raised flag from hand tag (kind 10312).