EN | KO

React Video Timestone

A React component library that provides seamless multi-video timeline experiences through instant navigation without buffering interruptions.

Why This Library?

Every time you implement interactive video storytelling, you need to repeatedly develop complex logic for specific point events, reverse playback, multi-video connections, and more. It's difficult to create smooth storytelling experiences with HTML5 video alone, and implementing similar features from scratch each time makes it hard to focus on core storytelling. This library was created to address these pain points.

Our Solution

React Video Timestone provides video control features essential for storytelling in a single component:

1. Ready-to-use Timeline: Smooth storytelling connecting multiple videos
2. Interactive Marker System: Automatic callback execution and control at specific points
3. Buffer-free Instant Navigation: Seamless navigation experience using preloading and Blob caching
4. Play/Reverse/Seek: Control forward and reverse playback with simple API
5. Consistent Development Experience: Implement all interactive videos the same way

When to Use

✅ Ideal for:

• Storytelling with short videos where flow is important
• Storytelling connecting multiple videos
• Interfaces where play/reverse playback is crucial
• Experiences requiring interaction at specific points

❌ Not suitable for:

• Simple single video playback (regular video tag is sufficient)
• Very long video content (increased memory usage)
• Real-time streaming content

Technical Considerations

Advantages

• Buffer-free playback
• Smooth play/reverse experience
• Interaction through marker system

Limitations

• Memory Usage: All videos cached as blobs in memory
• Initial Loading: Initial delay due to preloading all videos
• File Size: Increased file size with GOP-1 optimization

Installation

npm install react-video-timestone

Quick Start

import {
  VideoTimestone,
  MARKER_DIRECTION,
  MARKER_ACTION,
} from 'react-video-timestone';

function App() {
  return (
    <VideoTimestone
      videoUrls={['/video1.mp4', '/video2.mp4', '/video3.mp4']}
      speed={1}
      controls
      onStateChange={({ currentTime, playerState }) => {
        console.log('Current time:', currentTime, 'State:', playerState);
      }}
    />
  );
}

Usage Examples

Basic Multi-video Timeline

function VideoExample() {
  const [isLoading, setIsLoading] = useState(true);
  const [canPlay, setCanPlay] = useState(false);

  return (
    <VideoTimestone
      videoUrls={['/intro.mp4', '/main.mp4', '/outro.mp4']}
      controls
      onLoading={progress => console.log(`Downloading: ${progress}%`)}
      onLoaded={() => {
        console.log('Download complete');
        setIsLoading(false);
      }}
      onReady={() => {
        console.log('Ready to play');
        setCanPlay(true);
      }}
    />
  );
}

Interactive Timeline with Markers

<VideoTimestone
  videoUrls={['/story.mp4']}
  markers={[
    {
      time: 5,
      label: 'Choice Point',
      action: MARKER_ACTION.PAUSE,
      callback: () => showChoiceDialog(),
    },
    {
      time: 10,
      label: 'Reverse Point',
      direction: MARKER_DIRECTION.BACKWARD,
    },
  ]}
  onStateChange={({ playerState, currentTime }) => {
    console.log(`State: ${playerState}, Time: ${currentTime}`);
  }}
/>

External Control with Ref

function ControlledTimeline() {
  const timelineRef = useRef(null);

  return (
    <>
      <VideoTimestone
        ref={timelineRef}
        videoUrls={['/demo.mp4']}
        controls={false}
      />
      <button onClick={() => timelineRef.current?.play()}>Play</button>
      <button onClick={() => timelineRef.current?.pause()}>Pause</button>
      <button
        onClick={() =>
          timelineRef.current?.seekTo({ time: 10, autoPlay: true })
        }
      >
        Jump to 10s
      </button>
    </>
  );
}

Video Preparation

For optimal performance, videos should be encoded with:

• GOP Size: 1 (each frame is a keyframe)
• Format: MP4 with H.264
• Duration: Set appropriately for your use case
• Resolution: Match your display requirements
• Mobile: Recommend preparing separate mobile-optimized videos for performance

FFmpeg command examples:

# Basic GOP-1 conversion
ffmpeg -i input.mp4 -g 1 output-gop1.mp4

# With quality adjustment if needed
ffmpeg -i input.mp4 -g 1 -c:v libx264 -crf 23 output-gop1.mp4

API Reference

VideoTimestone Props

• videoUrls (string[]): Array of video URLs to play (required)
• markers? (Marker[]): Array of timeline markers
• speed? (number): Playback speed (default: 1)
• controls? (boolean): Show default controls
• fullScreen? (boolean): Fullscreen mode
• className? (string): Custom CSS class
• posters? (string[]): Array of poster images for each video
• onLoading? ((progress: number) => void): Video download progress callback (0-100)
• onLoaded? (() => void): Called when all video downloads and blob conversion complete
• onReady? (() => void): Called when video elements finish loading and are ready for actual playback
• onStateChange? ((state) => void): State change callback

Marker Type

// Convenient constants
export const MARKER_DIRECTION = {
  FORWARD: 'FORWARD',
  BACKWARD: 'BACKWARD',
  BOTH: 'BOTH',
} as const;

export const MARKER_ACTION = {
  CONTINUE: 'CONTINUE',
  PAUSE: 'PAUSE',
} as const;

// Marker types
type MarkerDirection = (typeof MARKER_DIRECTION)[keyof typeof MARKER_DIRECTION];
type MarkerAction = (typeof MARKER_ACTION)[keyof typeof MARKER_ACTION];

type Marker = {
  videoIndex?: number; // Video index (default: 0)
  label: string; // Marker label
  time: number; // Marker time (seconds)
  action?: MarkerAction; // Marker action (default: 'CONTINUE')
  direction?: MarkerDirection; // Direction
  callback?: () => void; // Callback function
};

Ref Methods

type TimelineRef = {
  videoElement: HTMLVideoElement | undefined; // Video element
  play: () => void; // Play
  pause: () => void; // Pause
  rewind: () => void; // Reverse play
  seekTo: ({ time, autoPlay }) => void; // Seek to specific time
};

Contributing

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

License

MIT © eatdesignlove