Live commentary

Professional commentary enhances live sports and events by providing expert insights, play-by-play descriptions, and context that enriches the viewing experience. Real-time synchronized commentary keeps fans informed and engaged while watching the action.

By the end of this document, you will understand:

• How PubNub's Pub/Sub messaging delivers real-time commentary
• How message timetokens ensure deduplication
• How to synchronize commentary with game time using PubNub

How PubNub helps

Role in the solution	PubNub feature (click to learn more!)
Deliver real-time commentary updates Synchronize with video stream	Pub/Sub
Prevent duplicate messages	Message timetokens

Use case overview

The Live Events demo showcases how PubNub's Pub/Sub messaging delivers professional commentary to all viewers simultaneously. This creates a broadcast-like experience where everyone receives the same expert insights synchronized with the game action.

The demo demonstrates these core capabilities:

• Instant commentary delivery (< 30ms within a single PubNub region)
• Commentary synchronized with game clock timestamps

Channel architecture

The Live Events demo uses a dedicated PubNub channel specifically for commentary messages:

export const liveCommentaryChannelId = "game.commentary";

This architecture decision separates commentary from other real-time features (chat, reactions, etc.), providing several benefits:

1. Commentary messages don't compete with other app communication.
2. Commentary can be one-way (broadcast only), where clients only need read permission on the channel.
3. Viewers can subscribe only to content they want - for example, to a specific game's commentary (game.commentary.123) or to all games using wildcards (game.commentary.*).

In the implementation, the demo creates a subscription to this dedicated channel:

// Create a subscription to the dedicated commentary channel
const channel = chat.sdk.channel(liveCommentaryChannelId)
const subscription = channel.subscription({ 
  receivePresenceEvents: false  // Presence is not needed on this channel because it is tracked on a different channel
})

// Subscribe to start receiving commentary
subscription.subscribe()

This subscription establishes a persistent connection to PubNub's network, enabling real-time reception of all commentary messages.

Real-time message delivery

The core of the live commentary feature is PubNub's real-time message delivery. When a commentary message is published, it reaches all viewers nearly instantly:

// Set up message handler to process incoming commentary
subscription.onMessage = messageEvent => {
  setMessages(messages => [...messages, messageEvent])
}

The onMessage handler executes whenever a new commentary message arrives through PubNub's global network. The handler adds the new message to the existing list, ensuring viewers always see the latest commentary.

Behind the scenes, PubNub's global network of data centers routes these messages to all subscribed clients with minimal latency (typically under 30ms within a single PubNub region). This creates a synchronized viewing experience where all fans receive the same commentary at virtually the same time.

Under the hood

Message timetokens

Every message published through PubNub automatically receives a unique timetoken - a 17-digit integer representing the time in microseconds when the message was published.

This timetoken serves multiple important purposes:

1. Unique identifier: Each message has a guaranteed unique timetoken, making it ideal to use as a key when rendering lists
2. Message integrity: In the rare case of network-related duplicates, timetokens can be used to identify and filter them

// Example of using timetokens as React key when rendering messages
{messages.map(message => (
  <CommentaryMessage 
    key={message.timetoken}  // Using timetoken as unique React key
    message={message} 
  />
))}

PubNub's reliable message delivery means duplicates are rare, but the uniqueness of timetokens provides an additional layer of message integrity when needed.

Time-synchronized commentary

PubNub enables real-time synchronized commentary by providing two powerful approaches to connect game time with viewer experiences:

Direct time synchronization

The most straightforward approach, implemented in the Live Events demo, includes game clock timestamps directly with each message:

// Example of a commentary message with timeCode (as used in the Live Events demo)
{
  text: "Good looking move",
  timeCode: "48:07"  // Game clock time in MM:SS format
}

This simple but effective method ensures all viewers receive commentary perfectly synchronized with their viewing experience, regardless of when they joined or their network conditions.

Server-to-server synchronization

For more complex implementations, PubNub serves as an ideal server-to-server connection:

1. Game tracking system publishes game events with timestamps to PubNub
2. Commentary system subscribes to these events and adds expert commentary
3. Combined data is then published to viewers with perfect time synchronization

This approach is valuable for organizations with separate game tracking and commentary systems.

In both scenarios, PubNub's value comes from its reliable message delivery and global infrastructure that ensures all viewers see the same commentary at the right moments. The Live Events demo leverages the first approach, displaying the timeCode alongside each commentary message to help viewers correlate comments with the action they're watching.

Implementation best practices

When implementing live commentary with PubNub, consider these best practices from the Live Events demo:

Optimize network efficiency

The commentary implementation disables presence events since they're not needed for one-way broadcast communication:

const subscription = channel.subscription({ 
  receivePresenceEvents: false
})

This reduces unnecessary network traffic and processing overhead, especially important during high-viewership events when thousands or millions of viewers might be watching simultaneously.

Presence Management

For more fine-grained control over presence events on specific channels, PubNub offers Presence Management through the Admin Portal. This allows you to selectively enable or disable presence tracking on specific channels rather than controlling it at the subscription level.

Clean subscription management

The demo properly manages subscriptions to prevent memory leaks and unnecessary background processing:

useEffect(() => {
  // Create subscription and set up handlers
  const subscription = channel.subscription({ receivePresenceEvents: false })
  subscription.onMessage = messageEvent => {
    // Handle message
  }
  subscription.subscribe()
  
  // Clean up subscription when component unmounts
  return () => {
    subscription.unsubscribe()
  }
}, [chat])

This cleanup ensures that resources are properly released when viewers navigate away from the live event.

Leverage PubNub's global infrastructure

PubNub's global network of data centers ensures that commentary messages are delivered with minimal latency to viewers around the world. The demo takes advantage of this infrastructure by using standard PubNub Pub/Sub messaging without any additional complexity.

By implementing these patterns from the Live Events demo, you can create an effective, scalable live commentary system for your own sports or event streaming applications, leveraging PubNub's real-time infrastructure to keep fans engaged and informed.