JavaScript library that can create animated GIFs from media streams, videos, or images
How
gifshot uses the following technologies:
-
The webRTC getUserMedia()
API to get permission to use a user's webcam and manipulate the CameraStream
Media object
-
The HTML5 Filesystem
APIs to handle the temporary blob URL creation
-
The HTML5 video
element to stream the blob URL
-
The canvas
API to create a dynamic image from an HTML5 video, or images
-
Web workers
to process the GIF frames
-
Typed Arrays
to handle binary image data
-
Base 64 encoding
to create a base 64 encoded image string
Browser Support
- Animated GIF from Webcam :
- Firefox 17+, Chrome 21+, Opera 18+, Blackberry Browser 10+, Opera Mobile 12+, Chrome For Android 35+, Firefox for Android 29+
- Animated GIF from Existing Video :
- All modern browsers (IE10+)
- Animated GIF from Existing Images :
- All modern browsers (IE10+)
Quick Start
- Include
gifshot
on your HTML page (gifshot.js
can be found in the build
directory)
<script src='gifshot.js'></script>
- Start using the JavaScript API to create your animated GIFs
gifshot.createGIF({}, function(obj) {
if(!obj.error) {
var image = obj.image,
animatedImage = document.createElement('img');
animatedImage.src = image;
document.body.appendChild(animatedImage);
}
});
Demo Set Up
- git clone this repo:
git clone git@github.com:yahoo/gifshot.git
- Install Node.js
- Install all local dependencies:
npm install
- Start up the included node.js preview server:
npm run preview
- Go to
localhost:8001
to try out gifshot
API Methods
createGIF(options, callback)
Creates an animated GIF from either a webcam stream, an existing video (e.g. mp4), or existing images
Note: If you wish to use the default options, you can just pass a callback function as the only argument
Another Note: An object is passed back to the callback function with helpful data
gifshot.createGIF({}, function(obj) {
});
takeSnapShot(options, callback)
Takes a snap shot (not animated) image from a webcam stream or existing video
Note: If you wish to use the default options, you can just pass a callback function as the only argument
Another Note: An object is passed back to the callback function with helpful data
gifshot.takeSnapShot({}, function(obj) {
});
stopVideoStreaming()
Turns off the user's webcam (by default, the user's webcam is turned off)
Note: This is helpful when you use the keepCameraOn
option
gifshot.stopVideoStreaming();
isSupported()
If the current browser supports all of the gifshot animated GIF options
gifshot.isSupported();
isWebCamGIFSupported()
If the current browser supports creating animated GIFs from a webcam video stream
gifshot.isWebCamGIFSupported();
isExistingVideoGIFSupported()
If the current browser supports creating animated GIFs from an existing HTML video (e.g. mp4, ogg, ogv, webm)
Note: You can pass in an array of codec extensions to specifically check if the current browser supports at least one of them
gifshot.isExistingVideoGIFSupported(['mp4', 'ogg']);
isExistingImagesGIFSupported()
If the current browser supports creating animated GIFs from existing images (e.g. jpeg, png, gif)
gifshot.isExistingImagesGIFSupported();
Examples
Web Cam
gifshot.createGIF(function(obj) {
if(!obj.error) {
var image = obj.image,
animatedImage = document.createElement('img');
animatedImage.src = image;
document.body.appendChild(animatedImage);
}
});
HTML5 Video
gifshot.createGIF({
'video': ['example.mp4', 'example.ogv']
},function(obj) {
if(!obj.error) {
var image = obj.image,
animatedImage = document.createElement('img');
animatedImage.src = image;
document.body.appendChild(animatedImage);
}
});
Images
gifshot.createGIF({
'images': ['http://i.imgur.com/2OO33vX.jpg', 'http://i.imgur.com/qOwVaSN.png', 'http://i.imgur.com/Vo5mFZJ.gif']
},function(obj) {
if(!obj.error) {
var image = obj.image,
animatedImage = document.createElement('img');
animatedImage.src = image;
document.body.appendChild(animatedImage);
}
});
Snap Shot
gifshot.takeSnapShot(function(obj) {
if(!obj.error) {
var image = obj.image,
animatedImage = document.createElement('img');
animatedImage.src = image;
document.body.appendChild(animatedImage);
}
});
Options
'gifWidth': 200,
'gifHeight': 200,
'images': [],
'video': null,
'webcamVideoElement': null,
'keepCameraOn': false,
'cameraStream': null,
'interval': 0.1,
'numFrames': 10,
'text': '',
'fontWeight': 'normal',
'fontSize': '16px',
'minFontSize': '10px',
'resizeFont': false,
'fontFamily': 'sans-serif',
'fontColor': '#ffffff',
'textAlign': 'center',
'textBaseline': 'bottom',
'textXCoordinate': null,
'textYCoordinate': null,
'progressCallback': function(captureProgress) {},
'completeCallback': function() {},
'sampleInterval': 10,
'numWorkers': 2,
'saveRenderingContexts': false,
'savedRenderingContexts': []
'crossOrigin': 'Anonymous'
Custom Builds
We provide a gulp custom-build
task, that allows you to remove certain dependencies that you may not need. Pass in the custom build name that you would like (it default to webcam
):
gulp custom-build --webcam
Note: For custom builds, you need to clone this repo locally. Also, the unminified and minified custom build files will be in the build/custom
directory of the local gifshot repo.
###Possible build options:
webcam
- The webcam-to-GIF functionality of gifshot (the existing image/video logic is removed)
image
- The image-to-GIF functionality of gifshot (the existing webcam/video logic is removed)
video
- The HTML5 video-to-GIF functionality of gifshot (the existing webcam/image logic is removed)
Contributing
Please send all PR's to the dev
branch.
If your PR is a code change:
- Install all node.js dev dependencies:
npm install
- Update the appropriate module inside of the
src/modules
directory. - Install gulp.js globally:
sudo npm install gulp -g
- Concatenate, Lint, Test, and Minify gifshot with Gulp:
gulp
- Verify that the minified output file has been updated in
build/gifshot.js
and build/gifshot.min.js
and that no unit tests are failing. - Send the PR!
Note: There is a gulp watch
task set up that will automatically build, test, and minify gifshot whenever a module inside of the src/modules
directory is changed. We recommend using it.
Credits
gifshot would not have been possible without the help/inspiration of the following libraries/awesome people:
###Used
- An image quantization algorithm to reduce the number of colors required to represent the image (thus decreasing the file size). This script was ported from C into Java by Kevin Weiner and then to ActionScript 3 by Thibault Imbert, and to JavaScript by antimatter15, and fixed, patched and revised by sole.
- Copyright (c) Anthony Dekker 1994 - MIT License
- Encodes a GIF into the GIF89 spec
- Copyright (c) Dean McNamee, 2013 - MIT License
###Inspiration
- A module wrapping WebRTC's getUserMedia
- Uses web workers and encoding/decoding algorithms to produce a Base 64 data URI image
Contributors