Overview

Forked from the excelent jsgif project (https://github.com/shachaf/jsgif), which was implemented as a bookmarklet to manipulate animated gifs (http://slbkbs.org/jsgif).

This is an attempt to pull out the gif parsing and playing logic, seperate it from the bookmarklet, and publish it as a library that you can use in your project.

As an added bonus, you can make gifs "rubbable" so that scrubbing with your mouse (or rubbing with your finger on a touch device) cause the gif to move back and forth.

Example

Please see example.html for, you know, an example. This will demonstrate how to use basic play controls for a gif, and also a rubbable one.

Please note: this example must be loaded via a webserver, not directly from disk. I.e. http://localhost/libgif-js/example.html NOT file:///libgif-js/example.html. See the same-domain origin caveat at the bottom of this document for more information.

For a hosted example, check out this post on BuzzFeed.com (http://www.buzzfeed.com/yacomink/rubbable-gifs)

Technical Details

Of note to the developer, libjs.gif contains a class SuperGif, which can be used to manipulate animated gifs.

Class: SuperGif

Example usage:

		<img src="./example1_preview.gif" rel:animated_src="./example1.gif"
		width="360" height="360" rel:auto_play="1" rel:rubbable="1" />

		<script type="text/javascript">
			$$('img').each(function (img_tag) {
				if (/.*\.gif/.test(img_tag.src)) {
					var rub = new SuperGif({ gif: img_tag } );
					rub.load(function(){
						console.log('oh hey, now the gif is loaded');
					});
				}
			});
		</script>

Image tag attributes:

• rel:animated_src - If this url is specified, it's loaded into the player instead of src. This allows a preview frame to be shown until animated gif data is streamed into the canvas

• rel:auto_play - Defaults to 1 if not specified. If set to zero, a call to the play() method is needed

• rel:rubbable - Defaults to 0 if not specified. If set to 1, the gif will be a canvas with handlers to handle rubbing.

Constructor options

• gif - Required. The DOM element of an img tag.
• loop_mode - Optional. Setting this to false will force disable looping of the gif.
• auto_play - Optional. Same as the rel:auto_play attribute above, this arg overrides the img tag info.
• max_width - Optional. Scale images over max_width down to max_width. Helpful with mobile.
• rubbable - Optional. Make it rubbable.
• on_end - Optional. Add a callback for when the gif reaches the end of a single loop (one iteration). The first argument passed will be the gif HTMLElement.
• loop_delay - Optional. The amount of time to pause (in ms) after each single loop (iteration).
• progressbar_height - Optional. The height of the progress bar.
• progressbar_background_color - Optional. The background color of the progress bar.
• progressbar_foreground_color - Optional. The foreground color of the progress bar.

Instance methods

loading

• load( callback ) - Loads the gif specified by the src or rel:animated_src sttributie of the img tag into a canvas element and then calls callback if one is passed
• load_url( src, callback ) - Loads the gif file specified in the src argument into a canvas element and then calls callback if one is passed

play controls

• play - Start playing the gif
• pause - Stop playing the gif
• move_to(i) - Move to frame i of the gif
• move_relative(i) - Move i frames ahead (or behind if i < 0)

getters

• get_canvas - The canvas element that the gif is playing in. Handy for assigning event handlers to.
• get_playing - Whether or not the gif is currently playing
• get_loading - Whether or not the gif has finished loading/parsing
• get_auto_play - Whether or not the gif is set to play automatically
• get_length - The number of frames in the gif
• get_current_frame - The index of the currently displayed frame of the gif

Caveat: same-domain origin

The gif has to be on the same domain (and port and protocol) as the page you're loading.

The library works by parsing gif image data in js, extracting individual frames, and rendering them on a canvas element. There is no way to get the raw image data from a normal image load, so this library does an XHR request for the image and forces the MIME-type to "text/plain". Consequently, using this library is subject to all the same cross-domain restrictions as any other XHR request.