@cut.media/gif-player

A high-performance GIF player library for animated GIFs and WebP with full control over animation timing.

Part of the Cut.media online video editor project.

Features

• 🎬 GIF and animated WebP support
• 🎮 Full playback control (play, pause, seek)
• 🖼️ Canvas-based rendering for performance
• 📦 Small bundle size with tree-shaking support
• 🔧 TypeScript support
• 🖼️ Frame extraction and metadata parsing
• ⏩ Playback speed control
• ⏪ Reverse playback

Installation

npm install @cut.media/gif-player
# or
pnpm add @cut.media/gif-player

Usage

Basic Animation

import gifPlayer from '@cut.media/gif-player'

// Load and play GIF in a canvas
const gif = gifPlayer('path/to/animation.gif')
const animator = await gif.get()
animator.animateInCanvas(canvas)
animator.start()

// Control playback
animator.stop()
animator.reset()
animator.setSpeed(2) // 2x speed
animator.setReverse(true) // Play backwards

Parse GIF Metadata

import { parseGif, calculateFPS } from '@cut.media/gif-player'

// Get GIF metadata
const result = await parseGif('path/to/animation.gif')
console.log(result.metadata)
// {
//   width: 500,
//   height: 300,
//   frameCount: 30,
//   duration: 2000,
//   frames: [...]
// }

// Calculate actual FPS
const fps = calculateFPS(result.metadata.frames)
console.log(`FPS: ${fps}`)

// Extract specific frame
const frame = await result.extractFrame(10)
// Returns ImageData for frame 10

// Extract all frames
const frames = await result.extractAllFrames()
// Returns array of ImageData

API Reference

Main Player Function

import gifPlayer from '@cut.media/gif-player'

// Returns a Gif instance for controlling animation
const gif = gifPlayer(url: string): Gif

Gif Methods

// Get animator instance
gif.get(): Promise<Animator>

// Animate in a canvas element
gif.animate(selector: string | HTMLCanvasElement): Promise<Animator>

// Custom frame rendering
gif.frames(
  selector: string | HTMLCanvasElement,
  onDrawFrame: (ctx, frame) => void,
  setDimensions?: boolean,
  autoStart?: boolean
): Promise<Animator>

Animator Methods

// Playback control
animator.start(): void
animator.stop(): void
animator.reset(): void
animator.running(): boolean

// Speed and direction
animator.setSpeed(speed: number): void  // 0.1 to 10
animator.setReverse(reverse: boolean): void

// Canvas rendering
animator.animateInCanvas(
  canvas: HTMLCanvasElement,
  setDimensions?: boolean,
  autoStart?: boolean
): void

// Event handling
animator.onFrame = (frame: Frame, index: number) => void

Parser Functions

import { parseGif, calculateFPS, getFrameAtTime } from '@cut.media/gif-player'

// Parse GIF and get metadata
parseGif(url: string): Promise<{
  metadata: GifMetadata
  extractFrame: (index: number) => Promise<ImageData>
  extractAllFrames: () => Promise<ImageData[]>
}>

// Calculate FPS from frames
calculateFPS(frames: FrameMetadata[]): number

// Get frame at specific time
getFrameAtTime(frames: FrameMetadata[], time: number): number

Types

interface GifMetadata {
  width: number
  height: number
  frameCount: number
  duration: number
  frames: FrameMetadata[]
}

interface FrameMetadata {
  delay: number
  disposal: number
  transparency: boolean
  transparent_index?: number
  data_offset: number
  data_length: number
}

Who's Using This

• GifPlayer.app - Online GIF player and editor
• Cut.media - Online video editor

Building

# Install dependencies
pnpm install

# Build library
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage