@blinkmobile/camera

Javascript plugin that uses WebRTC if available or cordova-camera if available

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
11Aug 21, 2017Jan 17, 2017Minified + gzip package size for @blinkmobile/camera in KB

Readme

Camera

npm

A Facade over WebRTC or Cordova's Camera plugin for a consistant API

If the cordova camera plug in is detected this plugin assumes that it is inside a Cordova application, otherwise it will assume it is being run in a browser and use the WebRTC protocol, if available.

There are 3 builds, depending on your target:

Dependencies

  • getusermedia shim - It is excluded in the default WebRTC builds. You can use a custom build to include this file in the bundle, otherwise you must include it in your web project. See the Build section for more information.

Supported Browsers

Any browser that is supported by the getusermedia shim is supported. At the time of writing,Safari is unsupported.

WebRTC example

See the WebRTC examples folder for examples of how to use this library. Note that WebRTC requires the page to load over https for access to the webcam. We recommend using the http-server node module for this.

Cordova Example

See the Cordova Examples folder for instructions on how to make the Cordova example.

API

@blinkmobile/camera is a facade around cordova-plugin-camera and WebRTC that provides an (alomst) unified API. It is meant to be used in conjuntion with a component framework such as Angular, React, Vue etc.

@blinkmobile/camera is distributed as a UMD module. If no module system is found it is bound to the global window.bmCameraFactory

window.bmCameraFactory or the imported module is a factory function that returns an instance of either CordovaCamera or WebRTCCamera, depending on the environment.

Factory

window.bmCameraFactory or if used in a module system like commonjs require('@blinkmobile/camera') is the factory function.

It returns a CordovaCamera or WebRTCCamera instance.

If you are using the WebRTC camera you must pass in a reference to a HTML5 video element which will be used to display the image from the camera. If none is supplied, a TypeError will be thrown

Instance Members

availableDevices

A list of video enabled devices supported by the device. Note that in the WebRTC version this list will be an empty array until the user has granted access to the camera. It is therefore recommended that displaying a selection list is done only once the user has granted access to the Camera (this is done via a call to open)

defaultConstraints

The constraints to use when accessing the camera. Generally you will not need to change these, but if you do, you can set the member directly or pass in an object to the open function

Instance Methods

getDevices()

Returns: An array of supported video devices, or an empty array if the user has not yet granted access to the camera.

Cordova camera will always return 2 devices, the front and back camera.

useDevice(device)

Returns: undefined

Sets the default constraints of the instance to use the passed in device obtained from a call to getDevices(). This is best used for WebRTC implementations only, as the cordova plugin has many device specific quirks, essentially rendering this function useless

open(constraints = defaultConstraints)

Returns: Promise

WebRTC projects will request access to the users camera. Once this is granted, .availableDevices will be populated and the video element passed to the factory function will display the stream from the video. The returned Promise will be resolved with no arguments

Cordova projects will open the device camera and will resolve with the result, either the image uri or a Base64 Encoded String

getPicture()

Returns: Promise

WebRTC projects will take a still image from the video feed.

Cordova projects will use the image taken when open was called. If there is no previous image, open() will be called to get one.

stop()

Stops the WebRTC video feed and closes the webcam

undefined for Cordova Projects

Build

See gulpfile for the available tasks.

All tasks will accept the following command line args

  • --buildmode prod - Builds both minified and unminified libraries
  • --shim true - Includes the getUserMedia shim in the plugin file.

By default the dist/ folder contains the lib without the getUserMedia shim.

Tests

Currently only Chrome is tested, Firefox tests will be available soon.

Tests are run via gulp - gulp test-webrtc or npm - npm test

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.