blob-util is a Blob library for busy people.
It offers a tiny (~3.5KB min+gz) set of cross-browser utilities for translating Blobs to and from different formats:
<img/>tags- base 64 strings
- binary strings
- ArrayBuffers
- data URLs
- canvas
It's also a good pairing with the attachment API in PouchDB.
Note: this is a browser library. For Node.js, see Buffers.
Topics:
Download it from the dist/ folder above, or use NPM:
$ npm install blob-utilor Bower:
$ bower install blob-utilThen stick it in your HTML:
<script src="blob-util.js"></script>Now you have a window.blobUtil object. Or if you don't like globals, you can use Browserify.
- Firefox
- Chrome
- IE 10+
- Safari 6+
- iOS 6+
- Android 4.4+
- Any browser with either
Blobor the olderBlobBuilder; see caniuse for details.
Blobs (binary large objects) are the modern way of working with binary data in the browser. The browser support is very good.
Once you have a Blob, you can make it available offline by storing it in IndexedDB, PouchDB, LocalForage, or other in-browser databases. So it's the perfect format for working with offline images, sound, and video.
A File is also a Blob. So if you have an <input type="file"> in your page, you can let your users upload any file and then work with it as a Blob.
Here's Kirby. He's a famous little Blob.
So let's fulfill his destiny, and convert him to a real Blob object.
var img = document.getElementById('kirby');
blobUtil.imgSrcToBlob(img.src).then(function (blob) {
// ladies and gents, we have a blob
}).catch(function (err) {
// image failed to load
});(Don't worry, this won't download the image twice, because browsers are smart.)
Now that we have a Blob, we can convert it to a URL and use that as the source for another <img/> tag:
var blobURL = blobUtil.createObjectURL(blob);
var newImg = document.createElement('img');
newImg.src = blobURL;
document.body.appendChild(newImg);So now we have two Kirbys - one with a normal URL, and the other with a blob URL. You can try this out yourself in the blob-util playground. Super fun!
Warning: this API uses Promises, because it's not 2009 anymore.
###Overview
- createBlob(parts, options)
- createObjectURL(blob)
- revokeObjectURL(url)
- blobToBinaryString(blob)
- base64StringToBlob(base64, type)
- binaryStringToBlob(binary, type)
- blobToBase64String(blob)
- dataURLToBlob(dataURL)
- imgSrcToDataURL(src, type, crossOrigin, quality)
- canvasToBlob(canvas, type, quality)
- imgSrcToBlob(src, type, crossOrigin, quality)
- arrayBufferToBlob(buffer, type)
- blobToArrayBuffer(blob)
###createBlob(parts, options)
Shim for
new Blob()
to support
older browsers that use the deprecated BlobBuilder API.
Params
- parts
Array- content of theBlob - options
Object- usually just{type: myContentType}
Returns: Blob
Example:
var myBlob = blobUtil.createBlob(['hello world'], {type: 'text/plain'});
###createObjectURL(blob)
Shim for
URL.createObjectURL()
to support browsers that only have the prefixed
webkitURL (e.g. Android <4.4).
Params
- blob
Blob
Returns: string - url
Example:
var myUrl = blobUtil.createObjectURL(blob);
###revokeObjectURL(url)
Shim for
URL.revokeObjectURL()
to support browsers that only have the prefixed
webkitURL (e.g. Android <4.4).
Params
- url
string
Example:
blobUtil.revokeObjectURL(myUrl);
###blobToBinaryString(blob)
Convert a Blob to a binary string. Returns a Promise.
Params
- blob
Blob
Returns: Promise - Promise that resolves with the binary string
Example:
blobUtil.blobToBinaryString(blob).then(function (binaryString) {
// success
}).catch(function (err) {
// error
});
###base64StringToBlob(base64, type)
Convert a base64-encoded string to a Blob. Returns a Promise.
Params
- base64
string - type
string|undefined- the content type (optional)
Returns: Promise - Promise that resolves with the Blob
Example:
blobUtil.base64StringToBlob(base64String).then(function (blob) {
// success
}).catch(function (err) {
// error
});
###binaryStringToBlob(binary, type)
Convert a binary string to a Blob. Returns a Promise.
Params
- binary
string - type
string|undefined- the content type (optional)
Returns: Promise - Promise that resolves with the Blob
Example:
blobUtil.binaryStringToBlob(binaryString).then(function (blob) {
// success
}).catch(function (err) {
// error
});
###blobToBase64String(blob)
Convert a Blob to a binary string. Returns a Promise.
Params
- blob
Blob
Returns: Promise - Promise that resolves with the binary string
Example:
blobUtil.blobToBase64String(blob).then(function (base64String) {
// success
}).catch(function (err) {
// error
});
###dataURLToBlob(dataURL)
Convert a data URL string
(e.g. 'data:image/png;base64,iVBORw0KG...')
to a Blob. Returns a Promise.
Params
- dataURL
string
Returns: Promise - Promise that resolves with the Blob
Example:
blobUtil.dataURLToBlob(dataURL).then(function (blob) {
// success
}).catch(function (err) {
// error
});
###imgSrcToDataURL(src, type, crossOrigin, quality)
Convert an image's src URL to a data URL by loading the image and painting
it to a canvas. Returns a Promise.
Note: this will coerce the image to the desired content type, and it will only paint the first frame of an animated GIF.
Params
- src
string - type
string|undefined- the content type (optional, defaults to 'image/png') - crossOrigin
string|undefined- for CORS-enabled images, set this to 'Anonymous' to avoid "tainted canvas" errors - quality
number|undefined- a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'
Returns: Promise - Promise that resolves with the data URL string
Examples:
blobUtil.imgSrcToDataURL('http://mysite.com/img.png').then(function (dataURL) {
// success
}).catch(function (err) {
// error
});blobUtil.imgSrcToDataURL('http://some-other-site.com/img.jpg', 'image/jpeg',
{crossOrigin: 'Anonymous'}).then(function (dataURL) {
// success
}).catch(function (err) {
// error
});
###canvasToBlob(canvas, type, quality)
Convert a canvas to a Blob. Returns a Promise.
Params
- canvas
string - type
string|undefined- the content type (optional, defaults to 'image/png') - quality
number|undefined- a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'
Returns: Promise - Promise that resolves with the Blob
Examples:
blobUtil.canvasToBlob(canvas).then(function (blob) {
// success
}).catch(function (err) {
// error
});Most browsers support converting a canvas to both 'image/png' and 'image/jpeg'. You may
also want to try 'image/webp', which will work in some browsers like Chrome (and in other browsers, will just fall back to 'image/png'):
blobUtil.canvasToBlob(canvas, 'image/webp').then(function (blob) {
// success
}).catch(function (err) {
// error
});
###imgSrcToBlob(src, type, crossOrigin, quality)
Convert an image's src URL to a Blob by loading the image and painting
it to a canvas. Returns a Promise.
Note: this will coerce the image to the desired content type, and it will only paint the first frame of an animated GIF.
Params
- src
string - type
string|undefined- the content type (optional, defaults to 'image/png') - crossOrigin
string|undefined- for CORS-enabled images, set this to 'Anonymous' to avoid "tainted canvas" errors - quality
number|undefined- a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'
Returns: Promise - Promise that resolves with the Blob
Examples:
blobUtil.imgSrcToBlob('http://mysite.com/img.png').then(function (blob) {
// success
}).catch(function (err) {
// error
});blobUtil.imgSrcToBlob('http://some-other-site.com/img.jpg', 'image/jpeg',
{crossOrigin: 'Anonymous'}).then(function (blob) {
// success
}).catch(function (err) {
// error
});
###arrayBufferToBlob(buffer, type)
Convert an ArrayBuffer to a Blob. Returns a Promise.
Params
- buffer
ArrayBuffer - type
string|undefined- the content type (optional)
Returns: Promise - Promise that resolves with the Blob
Example:
blobUtil.arrayBufferToBlob(arrayBuff, 'audio/mpeg').then(function (blob) {
// success
}).catch(function (err) {
// error
});
###blobToArrayBuffer(blob)
Convert a Blob to an ArrayBuffer. Returns a Promise.
Params
- blob
Blob
Returns: Promise - Promise that resolves with the ArrayBuffer
Example:
blobUtil.blobToArrayBuffer(blob).then(function (arrayBuff) {
// success
}).catch(function (err) {
// error
});Thanks to webmodules/blob for the Blob constructor shim, and to the rest of the PouchDB team for figuring most of this crazy stuff out.
npm install
npm run build
To generate documentation in doc/:
npm run jsdoc
or in markdown format as api.md
npm run jsdoc2md
The playground is just jsdoc with some extra text containing Kirby and the code samples and such.
So unfortunately you will need to do a manual diff to get the docs up to date. You'll need to diff:
api.mdtoREADME.mdindex.htmltodoc/global.html
Update: I also manually added a bunch of code samples to README.md because jsdoc didn't seem to support that. So... yeah, jsdoc might not be so helpful anymore.
npm install
Then to test in the browser using Saucelabs:
npm test
Or to test locally in your browser of choice:
npm run test-local
Or to test in PhantomJS:
npm run test-phantom