🎥 FleetA Video Player

A powerful React video player component designed for fleet management and dashcam footage. Features GPS tracking, G-sensor data visualization, and seamless MP4 metadata parsing.

🚀 Quick Start

Installation

npm install fleeta-video-player

Peer Dependencies

Install required peer dependencies:

npm install react react-dom mapbox-gl react-map-gl

Basic Usage

import React from 'react';
import { VideoPlayer } from 'fleeta-video-player';
import 'fleeta-video-player/dist/style.css';

function App() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <VideoPlayer
        videoUrl="https://example.com/dashcam-video.mp4"
        enableMetadataParsing={true}
        showMap={true}
        autoPlay={true}
      />
    </div>
  );
}

✨ Features

• 🎬 Advanced Video Playback - Full-featured video player with custom controls
• 🗺️ GPS Tracking - Real-time vehicle position tracking on interactive maps
• 📊 G-Sensor Visualization - Live acceleration data display
• 🔍 MP4 Metadata Parsing - Automatic extraction of GPS and sensor data
• 🎨 Customizable UI - Dark/light mode and flexible styling
• 📱 Responsive Design - Works on desktop and mobile devices
• 🌳 Tree Shaking - Import only what you need
• 🔒 TypeScript - Full type safety and excellent DX

🔧 Environment Setup

Set up Mapbox for map functionality:

# .env file
VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here

📖 Documentation

• Installation Guide
• API Documentation
• Usage Examples
• Troubleshooting

🌳 Tree Shaking

Import only what you need to reduce bundle size:

// Import specific components
import { VideoPlayer } from 'fleeta-video-player';

// Import specific utilities
import { parseGpsData } from 'fleeta-video-player';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-video-player';

📖 Documentation

Components

VideoPlayer

The main video player component with GPS and sensor data integration.

interface VideoPlayerProps {
  // Video source
  videoUrl: string | null;
  
  // Auto-parsing configuration
  enableMetadataParsing?: boolean;
  
  // GPS and sensor data (external)
  gpsPoints?: GpsPoint[] | null;
  sensorData?: IAccel[] | null;
  
  // Player configuration
  autoPlay?: boolean;
  showControls?: boolean;
  showMap?: boolean;
  speedUnit?: 'km/h' | 'mph';
  
  // Event callbacks
  onTimeUpdate?: (currentTime: number) => void;
  onDurationChange?: (duration: number) => void;
  onPlay?: () => void;
  onPause?: () => void;
  onError?: (error: string) => void;
  
  // Styling
  className?: string;
}

Example:

<VideoPlayer
  videoUrl="https://example.com/video.mp4"
  enableMetadataParsing={true}
  autoPlay={true}
  showMap={true}
  speedUnit="km/h"
  onTimeUpdate={(time) => console.log('Current time:', time)}
  onError={(error) => console.error('Video error:', error)}
/>

MapComponent

Displays GPS tracking data on an interactive map.

interface MapComponentProps {
  gpsPoints?: GpsPoint[];
  currentTime?: number;
  sensorData?: IAccel[];
  speedUnit?: 'km/h' | 'mph';
  mapStyle?: 'streets' | 'satellite' | 'outdoors' | 'light' | 'dark';
  height?: string;
  className?: string;
}

Example:

<MapComponent
  gpsPoints={gpsData}
  currentTime={30}
  speedUnit="mph"
  mapStyle="satellite"
  height="300px"
/>

EventComponent

Visualizes G-sensor acceleration data.

interface EventComponentProps {
  sensorData?: IAccel[];
  currentTime?: number;
  videoDuration?: number;
  height?: string;
  className?: string;
}

Example:

<EventComponent
  sensorData={accelerationData}
  currentTime={30}
  videoDuration={120}
  height="100px"
/>

Utilities

GPS Data Parsing

import { parseGpsData, GpsParsingStatus } from 'fleeta-video-player';

const result = parseGpsData(base64GpsData);

if (result.status === GpsParsingStatus.SUCCESS) {
  console.log('GPS points:', result.points);
}

Sensor Data Parsing

import { parseSensorData, SensorParsingStatus } from 'fleeta-video-player';

const result = parseSensorData(base64SensorData);

if (result.status === SensorParsingStatus.SUCCESS) {
  console.log('Sensor data:', result.points);
}

MP4 Metadata Extraction

import { fetchAndParseMP4 } from 'fleeta-video-player';

const metadata = await fetchAndParseMP4('https://example.com/video.mp4');

console.log('GPS data:', metadata.gps);
console.log('Sensor data:', metadata.sensor);
console.log('Thumbnail:', metadata.thumbnail);

🎨 Styling

FleetA Video Player uses Tailwind CSS classes. You can:

1. Use default styles - Include the CSS bundle
2. Custom styling - Override with your own CSS
3. Tailwind integration - Use Tailwind classes directly

// Include default styles
import 'fleeta-video-player/dist/style.css';

// Custom styling
<VideoPlayer 
  className="my-custom-player border-2 border-blue-500"
  videoUrl={url}
/>

🌳 Tree Shaking

Import only what you need to reduce bundle size:

// Import specific components
import { VideoPlayer } from 'fleeta-video-player';

// Import specific utilities
import { parseGpsData } from 'fleeta-video-player';

// Import only types (zero runtime cost)
import type { VideoPlayerProps } from 'fleeta-video-player';

Bundle size savings:

• VideoPlayer only: ~40% smaller
• GPS parsing only: ~80% smaller
• Utilities only: ~90% smaller
• Types only: 100% smaller (no runtime cost)

🔧 Configuration

Environment Variables

Set up Mapbox for map functionality:

VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here

TypeScript

FleetA Video Player includes complete TypeScript definitions:

import type { 
  VideoPlayerProps,
  GpsPoint,
  IAccel,
  ExtractedMetadata 
} from 'fleeta-video-player';

📱 Responsive Design

The components are fully responsive and work on all screen sizes:

<div className="w-full h-screen lg:h-96">
  <VideoPlayer
    videoUrl={url}
    showMap={true}
    className="w-full h-full"
  />
</div>

🚗 Fleet Management Features

GPS Tracking

• Real-time vehicle position
• Route visualization
• Speed display (km/h or mph)
• Heading direction

G-Sensor Data

• Acceleration visualization
• Event detection
• Synchronized with video playback

MP4 Metadata

• Automatic data extraction
• GPS and sensor parsing
• Thumbnail generation

🔍 Advanced Examples

Custom GPS Data

const customGpsPoints: GpsPoint[] = [
  {
    timestamp: 0,
    lat: 37.7749,
    lng: -122.4194,
    relativeTime: 0,
    speedKmh: 50,
    speedKnots: 27,
    course: 90
  }
];

<VideoPlayer
  videoUrl={url}
  gpsPoints={customGpsPoints}
  showMap={true}
/>

Event Handling

<VideoPlayer
  videoUrl={url}
  onTimeUpdate={(time) => {
    console.log(`Video time: ${time}s`);
  }}
  onPlay={() => {
    console.log('Video started playing');
  }}
  onError={(error) => {
    console.error('Playback error:', error);
  }}
/>

Dark Mode

// Manual dark mode
<div className="dark">
  <VideoPlayer
    videoUrl={url}
    mapStyle="dark"
  />
</div>

🛠️ Development

Building from Source

git clone https://github.com/your-org/fleeta-video-player.git
cd fleeta-video-player
npm install
npm run build:lib

Running Tests

npm run test:treeshaking
npm run validate:full

📄 Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📝 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 API Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ by the FleetA Team