Class: JpegCamera

Defined in:

src/jpeg_camera.coffee

Overview

Base class for JpegCamera implementations. Subclasses provide functionality defined by this API using different engines. On supported browsers HTML5 implementation will be used, otherwise Flash will be used if available.

if (!window.JpegCamera) {
  alert("Neither getUserMedia nor Flash are available!");
}
else {
  // either HTML5 or Flash are available
  var camera = JpegCamera("#camera").ready(function () {
    var snapshot = camera.capture().show()
  }).error(function () {
    alert("Camera access was declined.");
  });
}

Class Method Summary

. (Boolean) canvas_supported()
Tells whether the browser supports canvas element and you can use Snapshot#get_canvas method to display snapshots outside the camera container.

Instance Method Summary

# (JpegCamera) ready(callback) Bind callback for camera ready event.
# (JpegCamera) error(callback) Bind callback for camera error events.
# (void) get_stats(callback) Peak into video stream and calculate pixel statistics.
# (Snapshot) capture(options = {}) Capture camera snapshot.
# (JpegCamera) show_stream() Hide currently displayed snapshot and show the video stream.
# (JpegCamera) discard_all() Discard all snapshots and show video stream.

Class Method Details

. (Boolean) canvas_supported()

Tells whether the browser supports canvas element and you can use Snapshot#get_canvas method to display snapshots outside the camera container.

All browsers except Internet Explorer 8 and earlier support canvas element.

Returns:

( Boolean ) — True if canvas is supported.

Constructor Details

# (void) constructor(container, options)

Construct new camera.

JpegCamera will fill the entire container element. If the element's aspect ratio is different than that of the camera stream (usually 4:3, but sometimes 16:9) the stream will be clipped horizontally or vertically.

To display the image on the client side the image might additionally get resized to match container element, but the file sent to the server will always be in camera's native resolution.

By design the file sent to the server will only contain the area that was visible to the user during capture. There is no way of sending unclipped, full camera frame without showing the whole frame to the user.

Resizing container after the camera has been initialized is not supported.

Various options provided here can be overwritten when calling capture or Snapshot#upload.

Parameters:

container ( DOMElement, String ) — DOM element or element's ID.

Options Hash: (options):

swf_url ( String ) — URL to the SWF file that should be used for fallback if HTML5 cannot be used. "/jpeg_camera/jpeg_camera.swf" by default.
shutter_mp3_url ( String ) — URL to the shutter mp3 sound file. Used by flash. "/jpeg_camera/shutter.mp3" by default.
shutter_ogg_url ( String ) — URL to the shutter ogg sound file. Used by HTML5. "/jpeg_camera/shutter.ogg" by default.
on_ready ( Function ) — Function to call when camera is ready. Inside the callback camera object can be accessed as this. This function will receive object with video_width and video_height properties as the first argument. These indicate camera's native resolution. See also JpegCamera#ready.
on_error ( Function ) — Function to call when camera error occurs. Error message will be passed as the first argument. Inside the callback camera object can be accessed as this. See also JpegCamera#error.
on_debug ( Function ) — This callback can be used to log various events and information that can be useful when debugging JpegCamera. Debug message will be passed as the first argument. Inside the callback camera object can be accessed as this. There is a default implementation of this callback that logs messages to window.console if available.
quality ( Float ) — Quality of the JPEG file that will be uploaded to the server. Should be between 0 and 1. 0.9 by default. Can be overwritten when calling capture. Cannot be overwritten at the time of upload.
mirror ( Boolean ) — The video stream and images displayed on the client side mimic a mirror, because that's how people are used to seeing themselves. By default images are uploaded to the server in their natural orientation - how the front facing camera sees the user. This option can be set to true to upload images the way the user sees them. Can be overwritten when calling capture. Cannot be overwritten at the time of upload.
shutter ( Boolean ) — Whether to play shutter sound when capturing snapshots. Can be overwritten when calling capture.
api_url ( String ) — URL where the snapshots will be uploaded. Can be overwritten when calling capture or Snapshot#upload.
csrf_token ( String ) — CSRF token to be sent in the X-CSRF-Token header during upload. Can be overwritten when calling capture or Snapshot#upload.
timeout ( Integer ) — IGNORED (NOT IMPLEMENTED) The number of milliseconds a request can take before automatically being terminated. Default of 0 means there is no timeout. Can be overwritten when calling capture or Snapshot#upload.
on_upload_done ( Function ) — Function to call when upload completes. Snapshot object will be available as this, response body will be passed as the first argument. Can be overwritten when calling capture or Snapshot#upload.
on_upload_fail ( Function ) — Function to call when upload fails. Snapshot object will be available as this, response code will be passed as the first argument followed by error message and response body. Can be overwritten when calling capture or Snapshot#upload.
retry_if ( Function ) — Function to be called before any upload done/fail callbacks to decide if the upload should be retried. By default it's null and uploads are never retried. Inside the function snapshot object will be available as this and the arguments will be: status_code, error_message, response, retry. retry is a number incremented for each retry and starting with 1 when the upload finishes for the first time. If the function returns true or 0 then upload will be retried immediately. Number greater than 0 will delay the retry by that many milliseconds. Any other value will be treated as a decision not to retry the upload and one of the on_upload_done or on_upload_fail callbacks will be fired instead. Can be overwritten when calling capture or Snapshot#upload.
retry_success ( Boolean ) — By default retry_if is not called for uploads that finish with a status code from the 2XX range. Set this to true if you want to retry some of these responses. This can be useful if you're experiencing some network oddities. Can be overwritten when calling capture or Snapshot#upload.

Instance Method Details

# (JpegCamera) ready(callback)

Bind callback for camera ready event.

Replaces the callback set using on_ready option during initialization.

If the event has already happened the argument will be called immediately.

Parameters:

callback ( Function ) — function to call when camera is ready. Camera object will be available as this. This function will receive object with video_width and video_height properties as the first argument. These indicate camera's native resolution.

Returns:

( JpegCamera ) — Self for chaining.

# (JpegCamera) error(callback)

Bind callback for camera error events.

Replaces the callback set using on_error option during initialization.

Errors can occur if user declines camera access, flash fails to load, etc. Furthermore error event can occur even after camera was ready if for example user revokes access.

If the event has already happened the argument will be called immediately.

Parameters:

callback ( Function ) — function to call when errors occur. Camera object will be available as this, error message will be passed as the first argument.

Returns:

( JpegCamera ) — Self for chaining.

# (void) get_stats(callback)

Peak into video stream and calculate pixel statistics.

Can be useful to give the user hints about bad lighting. It uses full capture area, but at much lower resolution. It's more efficient than taking a regular capture and calling Snapshot#get_stats.

Because reading image data can take a while when Flash fallback is being used this method does not return the data immediately. Instead it accepts a callback that later will be called with a Stats instance as an argument. The camera object will be available as this.

Parameters:

callback ( Function ) — Function to call when data is available. Camera object will be available as this, the Stats instance will be passed as the first argument.

Returns:

void

# (Snapshot) capture(options = {})

Capture camera snapshot.

All of the options can have their defaults set when constructing camera object.

Options Hash: (options):

quality ( Float ) — Quality of the JPEG file that will be uploaded to the server. Should be between 0 and 1. Defaults to 0.9 or whatever was set during camera initialization. Cannot be overwritten at the time of upload.
mirror ( Boolean ) — The video stream and images displayed on the client side mimic a mirror, because that's how people are used to seeing themselves. By default images are uploaded to the server in their natural orientation - how the front facing camera sees the user. This option can be set to true to upload images the way the user sees them. Cannot be overwritten at the time of upload.
scale ( Float ) — By default snapshots are captured and uploaded using highest possible resolution. Set this to a number less than 1.0 to get smaller snapshots.
shutter ( Boolean ) — Whether to play the shutter sound.
api_url ( String ) — URL where the snapshots will be uploaded. Can be overwritten when calling Snapshot#upload.
csrf_token ( String ) — CSRF token to be sent in the X-CSRF-Token header during upload. Can be overwritten when calling Snapshot#upload.
timeout ( Integer ) — IGNORED (NOT IMPLEMENTED) The number of milliseconds a request can take before automatically being terminated. Default of 0 means there is no timeout. Can be overwritten when calling Snapshot#upload.
on_upload_done ( Function ) — Function to call when upload completes. Snapshot object will be available as this, response body will be passed as the first argument. Can be overwritten when calling Snapshot#upload.
on_upload_fail ( Function ) — Function to call when upload fails. Snapshot object will be available as this, response code will be passed as the first argument followed by error message and response body. Can be overwritten when calling Snapshot#upload.
retry_if ( Function ) — Function to be called before any upload done/fail callbacks to decide if the upload should be retried. By default it's null and uploads are never retried. Inside the function snapshot object will be available as this and the arguments will be: status_code, error_message, response, retry. retry is a number incremented for each retry and starting with 1 when the upload finishes for the first time. If the function returns true or 0 then upload will be retried immediately. Number greater than 0 will delay the retry by that many milliseconds. Any other value will be treated as a decision not to retry the upload and one of the on_upload_done or on_upload_fail callbacks will be fired instead. Can be overwritten when calling Snapshot#upload.
retry_success ( Boolean ) — By default retry_if is not called for uploads that finish with a status code from the 2XX range. Set this to true if you want to retry some of these responses. This can be useful if you're experiencing some network oddities. Can be overwritten when calling Snapshot#upload.

Returns:

( Snapshot ) — The snapshot that was taken.

# (JpegCamera) show_stream()

Hide currently displayed snapshot and show the video stream.

Returns:

( JpegCamera ) — Self for chaining.

# (JpegCamera) discard_all()

Discard all snapshots and show video stream.

Returns:

( JpegCamera ) — Self for chaining.