Playback Overview

The social.plus Video SDK provides robust video playback capabilities that deliver exceptional viewing experiences across all platforms. This guide covers everything from basic playback to advanced viewer features.

What is Video Playback?

Video playback in the social.plus SDK encompasses all aspects of the viewer experience, from stream discovery to interactive viewing features. Our playback system is optimized for low latency, high quality, and seamless user experience.

Key Playback Features

Adaptive Streaming

  • Automatic Quality Adjustment: Adapts to network conditions in real-time
  • Multi-bitrate Support: Multiple quality levels for optimal viewing
  • Smooth Transitions: Seamless quality switching without interruption
  • Bandwidth Optimization: Efficient streaming for all connection types

Interactive Viewing

  • Live Chat: Real-time messaging during streams
  • Reactions: Express emotions with animated reactions
  • Polls and Q&A: Participate in broadcaster interactions
  • Super Chat: Highlighted messages and donations

Cross-Platform Playback

  • Web Players: HTML5 video with WebRTC support
  • Mobile Apps: Native iOS and Android players
  • Smart TVs: Television and set-top box compatibility
  • Desktop Apps: Windows, macOS, and Linux support

Getting Started with Playback

Basic Player Setup

import { SocialPlusVideo } from '@social-plus/video-sdk';

const player = new SocialPlusVideo({
  apiKey: 'your-api-key',
  mode: 'viewer'
});

// Initialize player
await player.initialize({
  containerId: 'video-player',
  streamId: 'stream-id-to-watch',
  autoplay: true,
  muted: false
});

Stream Discovery

// Get live streams
const liveStreams = await player.getLiveStreams({
  category: 'gaming',
  limit: 20,
  sortBy: 'viewers' // 'viewers', 'recent', 'trending'
});

// Search for streams
const searchResults = await player.searchStreams({
  query: 'minecraft',
  filters: {
    live: true,
    language: 'en',
    category: 'gaming'
  }
});

// Get recommended streams
const recommendations = await player.getRecommendedStreams({
  userId: 'current-user-id',
  limit: 10
});

Joining a Stream

// Join live stream
await player.joinStream('stream-id', {
  quality: 'auto', // 'auto', '1080p', '720p', '480p'
  lowLatency: true,
  chat: true,
  notifications: true
});

// Handle stream events
player.on('streamJoined', (streamInfo) => {
  console.log('Joined stream:', streamInfo);
  updateUI(streamInfo);
});

player.on('streamEnded', () => {
  console.log('Stream has ended');
  showStreamEndedMessage();
});

Player Controls

Basic Controls

// Play/pause controls
await player.play();
await player.pause();

// Volume control
await player.setVolume(0.8); // 0.0 to 1.0
const volume = player.getVolume();

// Mute/unmute
await player.mute();
await player.unmute();
const isMuted = player.isMuted();

// Fullscreen
await player.enterFullscreen();
await player.exitFullscreen();
const isFullscreen = player.isFullscreen();

Quality Control

// Set video quality
await player.setQuality('720p');

// Get available qualities
const qualities = await player.getAvailableQualities();
// Output: ['1080p', '720p', '480p', '360p', 'auto']

// Enable adaptive streaming
await player.enableAdaptiveStreaming({
  algorithm: 'bandwidth', // 'bandwidth', 'buffer', 'hybrid'
  bufferTarget: 3000, // milliseconds
  maxBitrate: 8000000 // bits per second
});

Playback Speed

// Set playback speed (for VOD content)
await player.setPlaybackSpeed(1.5); // 0.5x to 2.0x

// Get available speeds
const speeds = player.getAvailablePlaybackSpeeds();
// Output: [0.5, 0.75, 1.0, 1.25, 1.5, 2.0]

Live Stream Features

Real-time Chat

// Enable chat
await player.enableChat({
  position: 'side', // 'side', 'overlay', 'bottom'
  moderation: true,
  emotes: true,
  mentions: true
});

// Send chat message
await player.sendChatMessage('Hello everyone!');

// Handle chat events
player.on('chatMessage', (message) => {
  displayChatMessage(message);
});

player.on('chatModerationAction', (action) => {
  handleModerationAction(action);
});

Viewer Interactions

// Send reaction
await player.sendReaction('heart'); // 'heart', 'thumbs-up', 'fire', 'wow'

// Participate in poll
await player.votePoll('poll-id', 'option-1');

// Ask question in Q&A
await player.askQuestion('What camera do you use?');

// Send super chat
await player.sendSuperChat({
  message: 'Great stream!',
  amount: 5.00,
  currency: 'USD'
});

Stream Information

// Get stream details
const streamInfo = await player.getStreamInfo();
console.log({
  title: streamInfo.title,
  description: streamInfo.description,
  category: streamInfo.category,
  viewerCount: streamInfo.viewerCount,
  duration: streamInfo.duration,
  tags: streamInfo.tags
});

// Get broadcaster info
const broadcasterInfo = await player.getBroadcasterInfo();
console.log({
  name: broadcasterInfo.name,
  avatar: broadcasterInfo.avatar,
  followers: broadcasterInfo.followers,
  isLive: broadcasterInfo.isLive
});

VOD (Video on Demand) Playback

Playing Recorded Content

// Load VOD content
await player.loadVOD('video-id', {
  startTime: 30, // Start at 30 seconds
  quality: 'auto',
  captions: true
});

// Seek controls
await player.seekTo(120); // Seek to 2 minutes
await player.seekBy(30); // Skip forward 30 seconds
await player.seekBy(-10); // Skip backward 10 seconds

// Get playback position
const currentTime = player.getCurrentTime();
const duration = player.getDuration();
const progress = currentTime / duration;

Video Chapters

// Get video chapters
const chapters = await player.getChapters();
console.log(chapters);
// Output: [
//   { id: '1', title: 'Introduction', startTime: 0, endTime: 120 },
//   { id: '2', title: 'Main Content', startTime: 120, endTime: 1800 }
// ]

// Jump to chapter
await player.jumpToChapter('chapter-2');

// Chapter navigation events
player.on('chapterChanged', (chapter) => {
  updateChapterDisplay(chapter);
});

Advanced Playback Features

Picture-in-Picture

// Enable picture-in-picture
await player.enablePictureInPicture({
  size: 'medium', // 'small', 'medium', 'large'
  position: 'bottom-right',
  draggable: true,
  controls: ['play', 'volume', 'close']
});

// Handle PiP events
player.on('pipEnabled', () => {
  console.log('Picture-in-picture enabled');
});

player.on('pipDisabled', () => {
  console.log('Picture-in-picture disabled');
});

Multi-view

// Enable multi-view for multiple streams
await player.enableMultiView({
  layout: 'grid', // 'grid', 'sidebar', 'overlay'
  streams: [
    { id: 'stream-1', position: 'main' },
    { id: 'stream-2', position: 'secondary' },
    { id: 'stream-3', position: 'tertiary' }
  ],
  audio: 'main' // Which stream's audio to play
});

// Switch main stream
await player.switchMainStream('stream-2');

Accessibility Features

// Configure accessibility
await player.configureAccessibility({
  captions: {
    enabled: true,
    language: 'en',
    fontSize: 'medium',
    color: '#ffffff',
    backgroundColor: 'rgba(0,0,0,0.8)'
  },
  
  audioDescription: true,
  
  keyboardNavigation: {
    enabled: true,
    shortcuts: {
      play: ' ', // Spacebar
      fullscreen: 'f',
      mute: 'm',
      volumeUp: 'ArrowUp',
      volumeDown: 'ArrowDown'
    }
  },
  
  screenReader: {
    enabled: true,
    announcements: true
  }
});

Performance Optimization

Buffering and Preloading

// Configure buffering
await player.configureBuffering({
  targetBuffer: 3000, // 3 seconds
  maxBuffer: 10000, // 10 seconds
  preloadStrategy: 'aggressive', // 'none', 'conservative', 'aggressive'
  adaptiveBuffer: true
});

// Preload related content
await player.preloadContent([
  'related-video-1',
  'related-video-2',
  'recommended-stream'
]);

Network Optimization

// Monitor network conditions
player.on('networkQualityChanged', (quality) => {
  console.log('Network quality:', quality); // 'excellent', 'good', 'poor'
  
  if (quality === 'poor') {
    // Reduce quality or enable data saver mode
    await player.enableDataSaver();
  }
});

// Configure data usage
await player.configureDataUsage({
  dataSaverMode: false,
  maxDataRate: 5000000, // 5 Mbps
  wifiOnly: false,
  mobileDataWarning: true
});

Player Events

Playback Events

// Core playback events
player.on('loadstart', () => console.log('Started loading'));
player.on('loadedmetadata', () => console.log('Metadata loaded'));
player.on('canplay', () => console.log('Can start playing'));
player.on('play', () => console.log('Playback started'));
player.on('pause', () => console.log('Playback paused'));
player.on('ended', () => console.log('Playback ended'));

// Quality events
player.on('qualityChanged', (quality) => {
  console.log('Quality changed to:', quality);
});

// Buffer events
player.on('buffering', () => console.log('Buffering...'));
player.on('bufferingEnd', () => console.log('Buffering ended'));

// Error events
player.on('error', (error) => {
  console.error('Player error:', error);
  handlePlayerError(error);
});

Stream-specific Events

// Live stream events
player.on('viewerCountChanged', (count) => {
  updateViewerCount(count);
});

player.on('streamQualityChanged', (quality) => {
  displayQualityIndicator(quality);
});

player.on('broadcasterOnline', (broadcaster) => {
  showNotification(`${broadcaster.name} is now live!`);
});

player.on('broadcasterOffline', (broadcaster) => {
  showNotification(`${broadcaster.name} went offline`);
});

Error Handling

Common Error Types

player.on('error', (error) => {
  switch (error.code) {
    case 'STREAM_NOT_FOUND':
      showError('Stream not found');
      break;
    case 'NETWORK_ERROR':
      showError('Network connection problem');
      break;
    case 'PLAYBACK_ERROR':
      showError('Playback failed');
      break;
    case 'PERMISSION_DENIED':
      showError('Access denied');
      break;
    default:
      showError('An unexpected error occurred');
  }
});

Automatic Error Recovery

// Configure error recovery
await player.configureErrorRecovery({
  retryAttempts: 3,
  retryDelay: 1000,
  fallbackQuality: '480p',
  errorReporting: true
});

Next Steps