@cloudgpt/timeline-editor

Enhanced React Timeline Editor - A powerful and feature-rich timeline editor component for building video editing applications, animation tools, and media timeline interfaces.

✨ Key Features

• 🎨 Advanced Theme System - Dark, Light, and Ocean themes with full customization
• ⏱️ Max Duration Control - Set timeline limits and validate action boundaries
• 🎯 Custom Cursor Styling - Full control over cursor appearance and behavior
• 🎛️ Professional Handles - Pill-shaped resize handles with gradient effects
• 🎬 Video Frame Support - Extract and display video frames on timeline
• 🖼️ Image Strip Display - Tiled image previews for visual actions
• 📐 Grid Snapping - Precise alignment and positioning
• 🎮 Drag Line Assistance - Visual guides for better UX
• 🚀 Performance Optimized - Smooth animations and interactions
• 📱 Responsive Design - Works across different screen sizes

🚀 Installation

npm install @cloudgpt/timeline-editor

📖 Basic Usage

import { Timeline, TimelineEffect, TimelineRow } from '@cloudgpt/timeline-editor';
import React, { useState } from 'react';

const mockData: TimelineRow[] = [
  {
    id: "0",
    actions: [
      {
        id: "action00",
        start: 0,
        end: 2,
        effectId: "effect0",
      },
    ],
  },
  {
    id: "1", 
    actions: [
      {
        id: "action10",
        start: 1.5,
        end: 5,
        effectId: "effect1",
      }
    ],
  }
];

const mockEffect: Record<string, TimelineEffect> = {
  effect0: {
    id: "effect0",
    name: "Video Clip",
  },
  effect1: {
    id: "effect1", 
    name: "Audio Track",
  },
};

const TimelineEditor = () => {
  const [data, setData] = useState(mockData);
  
  return (
    <Timeline
      editorData={data}
      effects={mockEffect}
      onChange={setData}
      maxDuration={30} // Limit timeline to 30 seconds
      theme={{
        backgroundColor: '#191b1d',
        foregroundColor: '#ffffff',
        cursorColor: '#ff6b35',
      }}
      cursor={{
        cursorColor: '#ff6b35',
        cursorWidth: 2,
        cursorStyle: 'solid',
        showCursorHead: true,
      }}
      handles={{
        showHandles: true,
        handleOpacity: 0.3,
        handleHoverOpacity: 1,
      }}
      style={{ width: '100%', height: 400 }}
    />
  );
};

🎨 Advanced Features

Theme Configuration

const themeConfig = {
  backgroundColor: '#1a1a1a',
  foregroundColor: '#ffffff', 
  gridColor: 'rgba(255, 255, 255, 0.1)',
  actionBackgroundColor: '#2f3134',
  actionBorderColor: 'rgba(255, 255, 255, 0.2)',
  dragLineColor: '#ff6b35',
};

<Timeline theme={themeConfig} />

Max Duration Control

<Timeline
  maxDuration={60} // Limit to 60 seconds
  validateActionChange={({ action, row, start, end }) => {
    // Custom validation logic
    return end <= 60 && start >= 0;
  }}
/>

Custom Cursor Styling

const cursorConfig = {
  cursorColor: '#00ff88',
  cursorWidth: 3,
  cursorStyle: 'dashed',
  cursorOpacity: 0.8,
  showCursorHead: true,
  cursorShadow: '0 0 10px rgba(0,255,136,0.5)',
};

<Timeline cursor={cursorConfig} />

Handle Customization

const handleConfig = {
  showHandles: true,
  handleBackground: 'linear-gradient(180deg, #ff6b35, #ff4500)',
  handleBorderColor: 'rgba(255, 255, 255, 0.4)',
  handleOpacity: 0.4,
  handleHoverOpacity: 1,
};

<Timeline handles={handleConfig} />

🎬 Media Support

The enhanced timeline editor supports video frame extraction and image previews:

// Custom render function for media actions
const renderAction = (action, row) => {
  if (action.effectId === 'video') {
    return <VideoStrip src="/video/sample.mp4" start={action.start} end={action.end} />;
  }
  if (action.effectId === 'image') {
    return <ImageStrip src="/images/sample.jpg" start={action.start} end={action.end} />;
  }
  return null;
};

<Timeline getActionRender={renderAction} />

📚 Enhanced from Original

This package is an enhanced version of the original @xzdarcy/react-timeline-editor with significant improvements:

• Enhanced Type System - Better TypeScript support with comprehensive interfaces
• Advanced Styling - Professional-grade visual design and theming
• Better Performance - Optimized rendering and interaction handling
• Extended API - More configuration options and customization capabilities
• Bug Fixes - Resolved cursor stuttering and validation issues
• Modern Features - Support for modern React patterns and hooks

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Based on the excellent work by @xzdarcy on the original react-timeline-editor.