@cut.media/vue-gif-player

Vue 3 component for high-performance GIF playback, built on top of @cut.media/gif-player.

Part of the Cut.media online video editor project.

Features

• 🎬 High-performance GIF playback - Optimized frame rendering
• 🎮 Two UI modes - Simple controls or full-featured player interface
• 📊 Metadata extraction - Get frame count, dimensions, FPS
• 🖼️ Frame extraction - Extract individual frames as images
• 📱 Responsive sizing - Support for various sizing options
• 🎨 Customizable UI - Slots for loading, error, and control states
• 📡 Rich events - Load, play, pause, frame, error events
• ⏩ Speed control - Adjust playback speed (with full controls)
• 📺 Fullscreen support - Native fullscreen mode (with full controls)
• 🔄 Timeline scrubbing - Seek to any frame (with full controls)
• ⚡ Vue 3 optimized - Built with Vue 3 Composition API
• 📦 TypeScript support - Full type definitions included

Installation

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

Usage

Quick Start - Simple Player

<template>
  <gif-player
    src="/path/to/animation.gif"
    :autoplay="true"
    :loop="true"
    :width="400"
    :height="300"
  />
</template>

<script setup>
import { GifPlayer } from '@cut.media/vue-gif-player'
import '@cut.media/vue-gif-player/dist/style.css'
</script>

Professional Player with Full Controls

Enable the complete player interface with timeline scrubbing, speed control, and more:

<template>
  <gif-player
    src="/path/to/animation.gif"
    :with-controls="true"
    :autoplay="false"
    width="800"
    height="450"
  />
</template>

<script setup>
import { GifPlayer } from '@cut.media/vue-gif-player'
import '@cut.media/vue-gif-player/dist/style.css'
</script>

As a Plugin (Global Registration)

import { createApp } from 'vue'
import VueGifPlayer from '@cut.media/vue-gif-player'
import '@cut.media/vue-gif-player/dist/style.css'

const app = createApp(App)
app.use(VueGifPlayer) // Registers GifPlayer globally
app.mount('#app')

Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | - | Required. URL of the GIF to play | | autoplay | boolean | false | Start playing automatically when loaded | | loop | boolean | true | Loop the animation | | width | number \| string | - | Canvas width (number for pixels, string for CSS units) | | height | number \| string | - | Canvas height (number for pixels, string for CSS units) | | fit | string | 'contain' | Object fit mode: contain, cover, fill, none, scale-down | | withControls | boolean | false | Enable full player UI with timeline, speed control, etc. | | showControls | boolean | true | Show play/pause controls on hover (when withControls is false) | | showProgress | boolean | false | Show progress bar (when withControls is false) | | showCenterPlayButton | boolean | true | Show large play button in center (when withControls is true) | | hideControlsOnMouseLeave | boolean | true | Auto-hide controls when mouse leaves (when withControls is true) | | controlsTimeout | number | 3000 | Time in ms before controls auto-hide (when withControls is true) | | clickToToggle | boolean | true | Toggle play/pause on click | | playLabel | string | 'Play' | Aria label for play button | | pauseLabel | string | 'Pause' | Aria label for pause button | | preload | boolean | true | Load the GIF on mount | | fps | number | - | Override the GIF's native FPS | | speed | number | 1 | Playback speed (0.1 to 10) | | reverse | boolean | false | Play animation in reverse |

Events

| Event | Payload | Description | |-------|---------|-------------| | load | GifMetadata | Fired when GIF is loaded with metadata | | play | - | Fired when playback starts | | pause | - | Fired when playback is paused | | stop | - | Fired when playback is stopped | | frame | number | Fired on each frame with frame index | | error | string | Fired when an error occurs | | click | MouseEvent | Fired when canvas is clicked | | speedChange | number | Fired when playback speed changes (with full controls) | | loopChange | boolean | Fired when loop setting changes (with full controls) | | reverseChange | boolean | Fired when reverse playback is toggled (with full controls) |

Methods

Access component methods using template refs:

<template>
  <gif-player ref="player" src="animation.gif" />
  <button @click="player.play()">Play</button>
</template>

<script setup>
import { ref } from 'vue'

const player = ref(null)

// Available methods:
// player.value.play()       - Start playback
// player.value.pause()      - Pause playback
// player.value.stop()       - Stop and reset
// player.value.reset()      - Reset to first frame
// player.value.toggle()     - Toggle play/pause
// player.value.load()       - Load/reload the GIF
// player.value.extractFrame(index)  - Extract specific frame
// player.value.extractFrames()      - Extract all frames

// With full controls (withControls=true), additional methods:
// player.value.seekToFrame(index)   - Seek to specific frame
// player.value.setSpeed(speed)      - Set playback speed
// player.value.toggleReverse()      - Toggle reverse playback
// player.value.toggleFullscreen()   - Toggle fullscreen mode
</script>

Slots

Loading Slot

<gif-player src="animation.gif">
  <template #loading>
    <div class="custom-loader">Loading...</div>
  </template>
</gif-player>

Error Slot

<gif-player src="animation.gif">
  <template #error="{ error }">
    <div class="custom-error">Error: {{ error }}</div>
  </template>
</gif-player>

Control Icons (Simple Mode)

<gif-player src="animation.gif">
  <template #play-icon>
    <svg><!-- Custom play icon --></svg>
  </template>
  <template #pause-icon>
    <svg><!-- Custom pause icon --></svg>
  </template>
</gif-player>

Advanced Examples

Extract Frames

<script setup>
import { ref } from 'vue'
import { GifPlayer } from '@cut.media/vue-gif-player'

const player = ref(null)

const extractAllFrames = async () => {
  const frames = await player.value.extractFrames()
  console.log(`Extracted ${frames.length} frames`)

  // Each frame has canvas, imageData, and blob
  frames.forEach((frame, index) => {
    document.body.appendChild(frame.canvas)
  })
}

const extractSingleFrame = async () => {
  const frame = await player.value.extractFrame(10) // Extract frame 10
  console.log('Frame extracted:', frame)
}
</script>

Get Metadata

<script setup>
import { parseGif, calculateFPS } from '@cut.media/vue-gif-player'

const analyzeGif = async (url) => {
  const { metadata } = await parseGif(url)
  console.log('Dimensions:', metadata.width, 'x', metadata.height)
  console.log('Frames:', metadata.frameCount)
  console.log('FPS:', calculateFPS(metadata))
  console.log('Duration:', metadata.duration, 'ms')
}
</script>

Responsive Player

<template>
  <gif-player
    src="animation.gif"
    width="100%"
    height="auto"
    fit="cover"
    :autoplay="true"
    :loop="true"
  />
</template>

Full-Featured Player with All Controls

<template>
  <gif-player
    ref="player"
    src="animation.gif"
    :with-controls="true"
    width="100%"
    height="500"
    fit="contain"
    :autoplay="false"
    :loop="true"
    :show-center-play-button="true"
    :hide-controls-on-mouse-leave="true"
    :controls-timeout="3000"
    :speed="1"
    :reverse="false"
    @load="onLoad"
    @speedChange="onSpeedChange"
    @loopChange="onLoopChange"
    @reverseChange="onReverseChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { GifPlayer } from '@cut.media/vue-gif-player'

const player = ref(null)

const onLoad = (metadata) => {
  console.log('GIF loaded:', metadata)
  console.log('Duration:', metadata.duration, 'ms')
  console.log('Frames:', metadata.frameCount)
}

const onSpeedChange = (speed) => {
  console.log('Speed changed to:', speed)
}

const onLoopChange = (enabled) => {
  console.log('Loop:', enabled ? 'enabled' : 'disabled')
}

const onReverseChange = (enabled) => {
  console.log('Reverse:', enabled ? 'enabled' : 'disabled')
}

// You can also control the player programmatically
const playFromStart = () => {
  player.value.reset()
  player.value.play()
}

const jumpToMiddle = () => {
  if (player.value.metadata) {
    const middleFrame = Math.floor(player.value.metadata.frameCount / 2)
    player.value.seekToFrame(middleFrame)
  }
}

const doubleSpeed = () => {
  player.value.setSpeed(2)
}
</script>

Comparison: Simple vs Full Controls

<template>
  <!-- Simple player - minimal UI, perfect for backgrounds or decorations -->
  <gif-player
    src="animation.gif"
    :autoplay="true"
    :show-controls="false"
  />

  <!-- Full-featured player - complete controls for user interaction -->
  <gif-player
    src="animation.gif"
    :with-controls="true"
    :autoplay="false"
  />
</template>

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers with canvas support

Who's Using This

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