Usage & Configuration

Learn how to use and configure the Smart TV Player components for your specific needs.

Basic Usage

The simplest way to get started with the Smart TV Player:

Minimal Setup

import React from 'react';
import { VideoPlayer, MediaProvider } from '@smart-tv/player';
import '@smart-tv/player/styles.css';

function BasicPlayer() {
  return (
    <MediaProvider>
      <VideoPlayer
        src="https://example.com/video.m3u8"
        autoPlay={false}
      />
    </MediaProvider>
  );
}

MediaProvider Configuration

The MediaProvider component manages the player state and provides context to all child components. It should wrap all player-related components.

import React from 'react';
import { MediaProvider, VideoPlayer, PlayerController } from '@smart-tv/player';

function ConfiguredPlayer() {
  return (
    <MediaProvider
      // Optional: Configure default player settings
      defaultSettings={{
        volume: 0.8,
        muted: false,
        autoPlay: false,
        loop: false,
      }}
      // Optional: Handle global player events
      onPlayerReady={(player) => {
        console.log('Player ready:', player);
      }}
      onError={(error) => {
        console.error('Player error:', error);
      }}
    >
      <div className="relative">
        <VideoPlayer
          src="https://example.com/video.m3u8"
          poster="https://example.com/poster.jpg"
        />
        <PlayerController layoutStyle="youtube" />
      </div>
    </MediaProvider>
  );
}

VideoPlayer Configuration

The VideoPlayer component supports various configuration options:

import React from 'react';
import { VideoPlayer, MediaProvider } from '@smart-tv/player';

function AdvancedVideoPlayer() {
  return (
    <MediaProvider>
      <VideoPlayer
        // Required: Video source
        src="https://example.com/video.m3u8"

        // Optional: Poster image
        poster="https://example.com/poster.jpg"

        // Playback options
        autoPlay={false}
        muted={false}
        loop={false}
        preload="metadata" // 'none' | 'metadata' | 'auto'

        // Player configuration
        className="w-full h-full"
        controls={false} // Hide native controls

        // DRM Configuration (for protected content)
        drm={{
          servers: {
            'com.widevine.alpha': 'https://widevine-license-server.com/',
            'com.microsoft.playready': 'https://playready-license-server.com/',
          },
          advanced: {
            'com.widevine.alpha': {
              videoRobustness: 'SW_SECURE_CRYPTO',
              audioRobustness: 'SW_SECURE_CRYPTO',
            }
          }
        }}

        // Event handlers
        onReady={(player) => console.log('Player ready')}
        onPlay={() => console.log('Started playing')}
        onPause={() => console.log('Paused')}
        onEnded={() => console.log('Playback ended')}
        onError={(error) => console.error('Error:', error)}
        onTimeUpdate={(currentTime, duration) => {
          console.log(`Time: ${currentTime}s / ${duration}s`);
        }}
        onVolumeChange={(volume, muted) => {
          console.log(`Volume: ${volume}, Muted: ${muted}`);
        }}
        onFullscreenChange={(isFullscreen) => {
          console.log(`Fullscreen: ${isFullscreen}`);
        }}
      />
    </MediaProvider>
  );
}

PlayerController Configuration

The PlayerController provides customizable video controls with multiple layout styles:

Predefined Layout Styles

import React from 'react';
import { PlayerController } from '@smart-tv/player';

// YouTube-style layout
<PlayerController
  layoutStyle="youtube"
  title="Video Title"
  subtitle="Episode 1"
/>

// Netflix-style layout
<PlayerController
  layoutStyle="netflix"
  title="Series Name"
  subtitle="Season 1, Episode 1"
/>

// Minimal layout
<PlayerController layoutStyle="minimal" />

// TV Remote layout (optimized for TV apps)
<PlayerController
  layoutStyle="tv-remote"
  title="TV Show"
  subtitle="Premium Channel"
/>

// Mobile-optimized layout
<PlayerController layoutStyle="mobile" />

Custom Layout Configuration

import React from 'react';
import { PlayerController, PlayerControllerLayout } from '@smart-tv/player';

const customLayout: PlayerControllerLayout = {
  name: 'Custom Layout',
  description: 'My custom player layout',
  showOnHover: true,
  autoHide: true,
  autoHideDelay: 5000,
  background: 'player-bg-black player-bg-opacity-80',
  padding: 'player-p-6',
  gap: 'player-gap-4',
  buttons: [
    {
      action: 'playpause',
      position: 'center',
      align: 'center',
      size: 'xl',
      className: 'player-bg-white player-bg-opacity-20 player-rounded-full',
    },
    {
      action: 'progressbar',
      position: 'bottom',
      align: 'top',
      className: 'player-mb-4',
    },
    // Add more buttons as needed...
  ],
};

function CustomPlayerController() {
  return (
    <PlayerController
      layout={customLayout}
      title="Custom Video"
      onButtonPress={(action, config) => {
        console.log('Button pressed:', action, config);
      }}
    />
  );
}

Custom Buttons

Add custom buttons to any layout style:

import React from 'react';
import { PlayerController, PlayerButtonConfig } from '@smart-tv/player';

const ShareIcon = () => (
  <svg viewBox="0 0 24 24" fill="currentColor">
    <path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81 1.66 0 3-1.34 3-3s-1.34-3-3-3-3 1.34-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9c-1.66 0-3 1.34-3 3s1.34 3 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.16c-.05.21-.08.43-.08.65 0 1.61 1.31 2.92 2.92 2.92 1.61 0 2.92-1.31 2.92-2.92s-1.31-2.92-2.92-2.92z" />
  </svg>
);

const customButtons: PlayerButtonConfig[] = [
  {
    action: 'custom',
    position: 'bottom',
    align: 'right',
    label: 'Share',
    icon: <ShareIcon />,
    onPress: () => {
      // Handle share functionality
      navigator.share({
        title: 'Check out this video',
        url: window.location.href,
      });
    },
    order: 0,
    className: 'player-bg-white player-bg-opacity-20 player-rounded-full',
  },
  {
    action: 'custom',
    position: 'bottom',
    align: 'left',
    label: 'Info',
    popup: true,
    content: (
      <div className="player-text-white player-p-4">
        <h3 className="player-font-bold player-mb-2">Video Information</h3>
        <p>Additional details about this video...</p>
      </div>
    ),
    order: 10,
  },
];

function PlayerWithCustomButtons() {
  return (
    <PlayerController
      layoutStyle="youtube"
      customButtons={customButtons}
      title="Video with Custom Actions"
    />
  );
}

Playlist Configuration

Configure playlist functionality for series and multiple videos:

import React from 'react';
import {
  MediaProvider,
  VideoPlayer,
  PlayerController,
  PlaylistProvider,
  PlaylistManager
} from '@smart-tv/player';

const playlistItems = [
  {
    id: '1',
    title: 'Episode 1: Pilot',
    description: 'The first episode of the series',
    src: 'https://example.com/episode1.m3u8',
    poster: 'https://example.com/episode1-poster.jpg',
    duration: 2400, // seconds
  },
  {
    id: '2',
    title: 'Episode 2: The Journey Begins',
    description: 'Our heroes start their adventure',
    src: 'https://example.com/episode2.m3u8',
    poster: 'https://example.com/episode2-poster.jpg',
    duration: 2700,
  },
  // More episodes...
];

function PlayerWithPlaylist() {
  return (
    <MediaProvider>
      <PlaylistProvider
        items={playlistItems}
        autoPlayNext={true}
        loop={false}
        onItemChange={(item) => {
          console.log('Now playing:', item.title);
        }}
      >
        <div className="flex">
          <div className="flex-1">
            <VideoPlayer />
            <PlayerController
              layoutStyle="netflix"
              customButtons={[
                {
                  action: 'custom',
                  position: 'bottom',
                  align: 'left',
                  label: 'Episodes',
                  icon: <PlaylistIcon />,
                  onPress: () => {
                    // Toggle playlist visibility
                  },
                },
              ]}
            />
          </div>

          <div className="w-80">
            <PlaylistManager />
          </div>
        </div>
      </PlaylistProvider>
    </MediaProvider>
  );
}

Responsive Design

The player automatically adapts to different screen sizes. You can also create responsive configurations:

import React, { useState, useEffect } from 'react';
import { PlayerController } from '@smart-tv/player';

function ResponsivePlayer() {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const checkMobile = () => {
      setIsMobile(window.innerWidth < 768);
    };

    checkMobile();
    window.addEventListener('resize', checkMobile);
    return () => window.removeEventListener('resize', checkMobile);
  }, []);

  return (
    <PlayerController
      layoutStyle={isMobile ? 'mobile' : 'youtube'}
      title="Responsive Video"
      customButtons={isMobile ? [] : [
        // Desktop-only buttons
        {
          action: 'custom',
          position: 'bottom',
          align: 'right',
          label: 'Share',
          onPress: () => console.log('Share'),
        },
      ]}
    />
  );
}

Focus Management (TV Apps)

For TV applications, the player includes built-in spatial navigation support:

import React from 'react';
import {
  MediaProvider,
  VideoPlayer,
  PlayerController,
  init // Initialize focus management
} from '@smart-tv/player';

// Call this once in your app initialization
init();

function TVPlayer() {
  return (
    <MediaProvider>
      <VideoPlayer
        src="https://example.com/video.m3u8"
        // TV-specific configurations
        autoPlay={true} // TVs often auto-play content
        focusable={true} // Enable focus management
      />
      <PlayerController
        layoutStyle="tv-remote"
        title="TV Show"
        subtitle="Season 1, Episode 1"
        // Focus configuration
        initialFocus="playpause" // Which button to focus first
        onFocusChange={(focusedElement) => {
          console.log('Focus changed to:', focusedElement);
        }}
      />
    </MediaProvider>
  );
}

Error Handling

Implement robust error handling for a better user experience:

import React, { useState } from 'react';
import { MediaProvider, VideoPlayer, PlayerController } from '@smart-tv/player';

function PlayerWithErrorHandling() {
  const [error, setError] = useState(null);
  const [isLoading, setIsLoading] = useState(true);

  const handleError = (error) => {
    console.error('Player error:', error);
    setError(error);
    setIsLoading(false);
  };

  const handleReady = () => {
    setError(null);
    setIsLoading(false);
  };

  if (error) {
    return (
      <div className="flex items-center justify-center h-64 bg-gray-100 rounded-lg">
        <div className="text-center">
          <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">
            Playback Error
          </h3>
          <p className="text-gray-600 dark:text-gray-300 mb-4">{error.message}</p>
          <button
            onClick={() => window.location.reload()}
            className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
          >
            Retry
          </button>
        </div>
      </div>
    );
  }

  return (
    <MediaProvider onError={handleError}>
      <div className="relative">
        {isLoading && (
          <div className="absolute inset-0 flex items-center justify-center bg-black bg-opacity-50 z-10">
            <div className="text-white">Loading...</div>
          </div>
        )}

        <VideoPlayer
          src="https://example.com/video.m3u8"
          onReady={handleReady}
          onError={handleError}
        />

        <PlayerController layoutStyle="youtube" />
      </div>
    </MediaProvider>
  );
}

Performance Optimization

Tips for optimizing player performance:

Lazy Loading

Use preload settings to control when video data is loaded:

<VideoPlayer preload="none" />

Memory Management

The player automatically cleans up resources when unmounted. Avoid creating multiple player instances unnecessarily.

Optimized Hooks

Use specific hooks instead of the general useMediaContext to prevent unnecessary re-renders.

Next Steps

→ Components

Explore all available components and their props

→ Hooks

Learn about state management hooks

→ Examples

See complete implementation examples