GIF player, which allows you to control/draw every single frame separately.


Keywords
gif, player, gif-player, js
License
MIT
Install
npm install js-gifplayer@2.5.0

Documentation

GIF Player

GIF player, which allows you to control/draw every single frame separately.

Navigation

§0 Installation

npm i js-gifplayer

§1 Initialization

Import into JS module

import GIFPlayerV2 from "js-gifplayer" // or path to GIFPlayerV2.js

Usage

HTML

<div id="wrapper"></div>

JS

const sources = 'gif1.gif' || ['gif1.gif', 'gif2.gif'] 
const player = new GIFPlayer(sources, '#wrappper', {
    player: {
        //player config
    },
    plugins: [/* Plug-in names */],
    //plug-in name in lowercase: { plug-in config }
})

§2 Parameters

  • GIF links (multiple GIFS can be passed).
  • Wrapper selector.
  • Options:
    • player: {...} This is the workspace where we are going to assign our parameters.
    • fps: sets fps. Default is 60.
    • frame: sets starting frame (if passed index is invalid, player will run from default value). Default is 0.
    • autoplay: sets autoplay. Default is false.
    • direction: GIFPlayerV2.states.BACKWARD || GIFPlayerV2.states.FORWARD sets the play direction. Default is GIFPlayerV2.states.FORWARD.
    • plugins: binds built-in plug-ins [GIFPlayer.AllPlugins.PLG_NAME...].
    • PLG_NAME: { ... } set up plug in config.

§3 Functions

Setters

.direction set play direction.
.frame set current frame.
.fps set fps limiter.

Getters

.all all internal states of the player.
.canvas canvas HTML element.
.wrapper wrapper element.
.state player state.
.frames_length frames count.
.current_frame_index current frame index.
.current_frame current frame.
.direction playing direction.
.fps fps limiter.
.urls gifs urls and its frame indexes.
get_frame(index) also a getter, but it's function because you have to pass an index.

Controls

play() play the GIF.
play_forward() set direction to GIFPlayer.states.FORWARD and play.
play_backward() set direction to GIFPlayer.states.BACKWARD and play.
pause() pause the GIF.
stop() pause the GIF and jump back to the first frame.
reverse() reverse playing direction.
step(count) jumps count frames forward. (Depends on direction)
step_back(count) jumps back count frame. (Depends on direction)

GIF Mutators

shuffle_frames() randomly shuffles frames.
remove_frames(...indices) remove frames.
add_frames(...imgs) push new frames.
remove_gifs(...gifs) remove GIFs frames.
add_gifs(...gifs) push new GIFs frames.

§4 Global variables

static States = Object.freeze({
    LOADING: 0,  //loading states
    READY: 1,
    PAUSED: 2,
    PLAYING: 3,
    ERROR: 4,

    FORWARD: 5, //play direction states
    BACKWARD: 6,
})
static AllPlugins = Object.freeze({
    Scroller: 'scroller',
    GUI: 'gui'
})

§5 Plug-Ins

Note: some plug-ins overwrite functions.
Currently exist 2 plug-ins:

  • Scroller GIFPlayerV2.AllPlugins.Scroller
    • Name: Scroller.
    • Description: synchron play-on-scroll animation.
    • Options:
      • flow set the animation flow during scrolling. Default [0, 1].
      • target set the scrolling element.

  • GUI GIFPlayerV2.AllPlugins.GUI
    • Name: GUI.
    • Description: Interactive GUI Controller.
    • Options:
      • hidden hide GUI visuals. Default false.
      • animationDuration set GUIs animation duration.

§6 Note

Some GIFs may have artifacts when running backwards.
The most common reason is compression, which removes unchanged pixels from the next frame.