mono/reference/tiktok/player

TikTok Video Player

A complete TikTok-style video player built from deobfuscated TikTok source code. Features infinite scroll, video controls, comments system, and privacy compliance - all with just React and Tailwind CSS.

🚀 Features

Core Video Player

• ✅ HTML5 Video Player with custom controls
• ✅ Infinite Scroll with snap-to-video behavior
• ✅ Auto-play/Pause based on viewport visibility
• ✅ Keyboard Navigation (Space, Arrow keys, M for mute)
• ✅ Progress Bar with click-to-seek
• ✅ Volume Control and mute functionality
• ✅ WebVTT Subtitles support with parsing
• ✅ Video Preloading and memory management

UI Components

• ✅ Action Bar (Like, Comment, Share, Bookmark, Follow)
• ✅ Video Metadata with hashtag/mention parsing
• ✅ User Avatars with verification badges
• ✅ Loading States and error handling
• ✅ Navigation Indicators (side dots)
• ✅ Responsive Design for mobile and desktop

Advanced Features

• ✅ Mock Data System for testing
• ✅ Analytics Tracking hooks
• ✅ Comment System (placeholder implementation)
• ✅ Share Functionality with clipboard copy
• ✅ Performance Optimized with throttled scroll events
• ✅ Accessibility with ARIA labels and keyboard support

📦 Installation

# Install dependencies
npm install

# Start development playground
npm run playground

# Build the library
npm run build

# Preview the built library
npm run preview

🎮 Playground

The playground demonstrates all features with mocked video data:

npm run playground

Open http://localhost:3000 to see the player in action.

Keyboard Shortcuts

• Space: Play/Pause current video
• ↑/↓: Navigate between videos
• M: Mute/Unmute audio

🔧 Usage

Basic Implementation

import React from 'react';
import { VideoFeed, generateMockVideos } from 'tiktok-video-player';

function App() {
  const videos = generateMockVideos(20);

  return (
    <VideoFeed
      videos={videos}
      onLoadMore={() => {
        // Load more videos from your API
      }}
      onVideoChange={(index) => {
        // Track video views
        console.log('Video changed to:', index);
      }}
      onLike={(videoId) => {
        // Handle like action
        console.log('Liked video:', videoId);
      }}
    />
  );
}

With Mux Integration

import { VideoFeed } from 'tiktok-video-player';
import { VideoItem } from 'tiktok-video-player/types';

// Convert Mux data to VideoItem format
const convertMuxToVideoItem = (muxAsset: any): VideoItem => ({
  id: muxAsset.id,
  video: {
    playAddr: `https://stream.mux.com/${muxAsset.playback_ids[0].id}.m3u8`,
    duration: muxAsset.duration,
    width: 720,
    height: 1280,
    ratio: '9:16'
  },
  author: {
    // Your user data
  },
  stats: {
    // Your video stats
  },
  // ... other properties
});

function MuxVideoFeed({ muxAssets }: { muxAssets: any[] }) {
  const videos = muxAssets.map(convertMuxToVideoItem);
  
  return <VideoFeed videos={videos} />;
}

Custom Video Source

import { VideoFeed } from 'tiktok-video-player';

const customVideos = [
  {
    id: 'video_1',
    video: {
      playAddr: 'https://your-cdn.com/video1.mp4',
      duration: 30,
      width: 720,
      height: 1280
    },
    author: {
      nickname: 'Creator Name',
      uniqueId: 'creator_username',
      avatarThumb: 'https://your-cdn.com/avatar.jpg'
    },
    stats: {
      diggCount: 1200,
      commentCount: 45,
      shareCount: 23
    },
    desc: 'Check out this amazing video! #awesome #content'
  }
];

<VideoFeed videos={customVideos} />

🏗️ Architecture

Based on deobfuscated TikTok source code, the player uses:

State Management

• Video Detail Atom: Central video state management
• Swiper Mode State: Navigation and interaction state
• Comment State: Comment system with ML preloading
• Privacy State: Cookie consent and network monitoring

Core Hooks

• useVideoPlayer: Video playback control and state
• useInfiniteScroll: Infinite scroll with preloading
• Custom hooks for analytics and privacy compliance

Components

• VideoFeed: Main container with infinite scroll
• VideoPlayer: HTML5 video with custom controls
• VideoActionBar: Like, comment, share buttons
• VideoMetadata: Author info and description parsing

🎨 Styling

Built with Tailwind CSS and includes TikTok's design system:

/* TikTok brand colors */
--tiktok-red: #FE2C55;
--tiktok-blue: #25F4EE;
--tiktok-dark: #161823;

/* Custom animations */
.animate-spin-slow: 3s linear infinite;
.backdrop-blur-xs: blur(2px);

📱 Mobile Support

• Touch gestures for navigation
• Responsive design for all screen sizes
• iOS/Android video playback optimization
• PWA-ready with proper meta tags

🔒 Privacy & Security

Implements TikTok's Privacy and Network Security (PNS) system:

• Cookie consent management
• Network request interception
• Web API monitoring (geolocation, camera, etc.)
• GDPR/CCPA compliance features

🧪 Testing

The playground includes:

• 50+ mock videos with realistic data
• Simulated API loading delays
• Error state demonstrations
• Analytics event logging
• Performance monitoring

📊 Analytics Integration

Built-in hooks for tracking:

const handleVideoChange = (index: number) => {
  // Track video views
  analytics.track('video_view', {
    video_id: videos[index].id,
    video_index: index,
    timestamp: Date.now()
  });
};

const handleLike = (videoId: string) => {
  // Track engagement
  analytics.track('video_like', {
    video_id: videoId,
    timestamp: Date.now()
  });
};

🔧 Configuration

Video Player Options

interface VideoPlayerOptions {
  autoplay?: boolean;        // Auto-play videos (default: true)
  muted?: boolean;          // Start muted (default: true)
  loop?: boolean;           // Loop individual videos (default: true)
  preload?: 'none' | 'metadata' | 'auto';
  controls?: boolean;       // Show native controls (default: false)
}

Infinite Scroll Options

interface InfiniteScrollOptions {
  threshold?: number;       // Load more threshold (default: 0.8)
  preloadDistance?: number; // Videos to preload (default: 6)
  hasMore?: boolean;        // More content available
}

🚀 Performance

Optimizations based on TikTok's implementation:

• Sparse Loading: Only loads visible videos
• Memory Management: Cleans up off-screen videos
• Throttled Events: 100ms scroll event throttling
• Preloading Strategy: Smart content preloading
• Video Optimization: Metadata preloading only

📝 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { 
  VideoItem, 
  VideoPlayerProps, 
  UseVideoPlayerReturn,
  CommentItem 
} from 'tiktok-video-player/types';

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built from deobfuscated TikTok source code analysis. This implementation replicates TikTok's sophisticated video player architecture while being completely independent and open-source.

---

Note: This is a reverse-engineered implementation for educational purposes. All TikTok trademarks belong to ByteDance Ltd.