Merge branch 'master' into gh-pages

.eslintrc

@@ -1,15 +1,24 @@
 {
-  "parser": "babel-eslint",
-  "extends": "airbnb",
-  "env": {
-    "browser": true,
-    "mocha": true,
-    "node": true
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "plugin:react/recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2018,
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
   },
   "rules": {
-    "jsx-a11y/media-has-caption": 0,
-    "react/forbid-prop-types": 0,
-    "react/jsx-filename-extension": 0,
-    "react/require-default-props": 0
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-unused-vars": ["error", { "ignoreRestSiblings": true }],
+    "@typescript-eslint/ban-ts-ignore": "off"
+  },
+  "settings": {
+    "react": {
+      "version": "detect"
+    }
   }
 }

.travis.yml

@@ -1,3 +1,3 @@
 language: node_js
 node_js:
-  - "iojs"
+  - "v12.13.0"

ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Please follow the general troubleshooting steps first:
+
+- [ ] Is your app running over HTTPS? (please provide the URL if possible)
+- [ ] Have you tried running the demo (https://codepen.io/mozmorris/pen/JLZdoP) on your device?
+- [ ] Checked the latest "Can I use" compatbility table? (https://caniuse.com/stream)
+
+### Bug reports:
+
+If you can provide a minimal reproducible demo (CodePen, CodeSandbox, etc) or a GitHub repository, that will greatly help us to solve your problem. Many of the issues posted are questions about react-webcam usage. We don't discourage you posting a question, it's just a lot easier to help you if we can see your code.
+
+### Features:
+
+**Please note by far the quickest way to get a new feature is to file a Pull Request.**
+
+We will consider your request but it may be closed if it's something we're not actively planning to work on.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Moz Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,27 @@
 # react-webcam
 
-Webcam component for React. See [this](http://caniuse.com/#feat=stream)
+[![Build Status][build-badge]][build]
+![downloads][downloads-badge]
+
+<img src="Logotype primary.png" width="70%" height="70%" />
+
+**DEMO:** https://codepen.io/mozmorris/pen/JLZdoP
+
+https://www.npmjs.com/package/react-webcam
+
+Webcam component for React. See [http://caniuse.com/#feat=stream](http://caniuse.com/#feat=stream)
 for browser compatibility.
 
+**Note: Browsers will throw an error if the page is loaded from insecure origin. I.e. Use https.**
+
 ## Installation
 
-```
+```shell
+# with npm
 npm install react-webcam
+
+# with yarn
+yarn add react-webcam
 ```
 
 ## Demo
@@ -15,76 +30,216 @@ https://codepen.io/mozmorris/pen/JLZdoP
 
 ## Usage
 
-```javascript
-import React from 'react';
-import Webcam from 'react-webcam';
+```jsx
+import React from "react";
+import Webcam from "react-webcam";
 
-class Component extends React.Component {
-  render() {
-    return <Webcam/>;
-  }
-}
+const WebcamComponent = () => <Webcam />;
 ```
 
 ### Props
 
-prop             | type     | default      | notes
------------------|----------|--------------|----------
-className        | string   | ''           | CSS class of video element
-audio            | boolean  | true         | enable/disable audio
-height           | number   | 480          | height of video element
-width            | number   | 640          | width of video element
-screenshotWidth  | number   |              | width of screenshot
-style            | object   |              | style prop passed to video element
-screenshotFormat | string   | 'image/webp' | format of screenshot
-onUserMedia      | function | noop         | callback when component receives a media stream
-onUserMediaError | function | noop         | callback when component cannot receives any media stream width error param
-screenshotQuality      | number   |        0.92      | quality of screenshot(0 to 1)
-audioConstraints | object   |              | MediaStreamConstraint(s) for the audio
-videoConstraints | object   |              | MediaStreamConstraints(s) for the video
+The props here are specific to this component but one can pass any prop to the underlying video tag eg `className`, `style`, `muted`, etc
+
+| prop                      | type     | default      | notes                                                                                   |
+|---------------------------|----------|--------------|-----------------------------------------------------------------------------------------|
+| audio                     | boolean  | false        | enable/disable audio                                                                    |
+| audioConstraints          | object   |              | MediaStreamConstraint(s) for the audio                                                  |
+| disablePictureInPicture   | boolean  | false        | disable Picture-in-Picture                                                              |
+| forceScreenshotSourceSize | boolean  | false        | uses size of underlying source video stream (and thus ignores other size related props) |
+| imageSmoothing            | boolean  | true         | pixel smoothing of the screenshot taken                                                 |
+| mirrored                  | boolean  | false        | show camera preview and get the screenshot mirrored                                     |
+| minScreenshotHeight       | number   |              | min height of screenshot                                                                |
+| minScreenshotWidth        | number   |              | min width of screenshot                                                                 |
+| onUserMedia               | function | noop         | callback for when component receives a media stream                                     |
+| onUserMediaError          | function | noop         | callback for when component can't receive a media stream with MediaStreamError param    |
+| screenshotFormat          | string   | 'image/webp' | format of screenshot                                                                    |
+| screenshotQuality         | number   | 0.92         | quality of screenshot(0 to 1)                                                           |
+| videoConstraints          | object   |              | MediaStreamConstraints(s) for the video                                                 |
 
 ### Methods
 
 `getScreenshot` - Returns a base64 encoded string of the current webcam image. Example:
 
-```javascript
+[https://codepen.io/mozmorris/pen/gOOoqpw](https://codepen.io/mozmorris/pen/gOOoqpw)
+
+You may also pass in an optional `dimensions` object:
+
+```
+getScreenshot({width: 1920, height: 1080});
+```
+
+### The Constraints
+
+We can build a constraints object by passing it to the videoConstraints prop. This gets passed into getUserMedia method. Please take a look at the MDN docs to get an understanding how this works.
+
+https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia
+https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints
+
+As an example take a look at this [CodePen demo https://codepen.io/mozmorris/pen/GRpEQwK?editors=0010](https://codepen.io/mozmorris/pen/GRpEQwK?editors=0010) which shows how to build a custom aspect ratio for the video.
+
+## Screenshot (via render props)
+
+```jsx
+const videoConstraints = {
+  width: 1280,
+  height: 720,
+  facingMode: "user"
+};
+
+const WebcamCapture = () => (
+  <Webcam
+    audio={false}
+    height={720}
+    screenshotFormat="image/jpeg"
+    width={1280}
+    videoConstraints={videoConstraints}
+  >
+    {({ getScreenshot }) => (
+      <button
+        onClick={() => {
+          const imageSrc = getScreenshot()
+        }}
+      >
+        Capture photo
+      </button>
+    )}
+  </Webcam>
+);
+```
+
+## Screenshot (via ref)
+
+```jsx
+const videoConstraints = {
+  width: 1280,
+  height: 720,
+  facingMode: "user"
+};
+
+const WebcamCapture = () => {
+  const webcamRef = React.useRef(null);
+  const capture = React.useCallback(
+    () => {
+      const imageSrc = webcamRef.current.getScreenshot();
+    },
+    [webcamRef]
+  );
+  return (
+    <>
+      <Webcam
+        audio={false}
+        height={720}
+        ref={webcamRef}
+        screenshotFormat="image/jpeg"
+        width={1280}
+        videoConstraints={videoConstraints}
+      />
+      <button onClick={capture}>Capture photo</button>
+    </>
+  );
+};
+```
+
+## Capturing video
+
+It is posible to capture video with `<Webcam />` using the [MediaStream Recording API](https://developer.mozilla.org/en-US/docs/Web/API/MediaStream_Recording_API).
+
+You can find an example [https://codepen.io/mozmorris/pen/yLYKzyp?editors=0010](https://codepen.io/mozmorris/pen/yLYKzyp?editors=0010).
+
+## Choosing a camera
+
+### User/Selfie/forward facing camera
+
+```jsx
 class WebcamCapture extends React.Component {
-  setRef = (webcam) => {
-    this.webcam = webcam;
+  render() {
+    const videoConstraints = {
+      facingMode: "user"
+    };
+
+    return <Webcam videoConstraints={videoConstraints} />;
   }
+}
+```
 
-  capture = () => {
-    const imageSrc = this.webcam.getScreenshot();
-  };
+### Environment/Facing-Out camera
 
+```jsx
+class WebcamCapture extends React.Component {
   render() {
     const videoConstraints = {
-      width: 1280,
-      height: 720,
-      facingMode: 'user',
+      facingMode: { exact: "environment" }
     };
 
-    return (
-      <div>
-        <Webcam
-          audio={false}
-          height={350}
-          ref={this.setRef}
-          screenshotFormat="image/jpeg"
-          width={350}
-          videoConstraints={videoConstraints}
-        />
-        <button onClick={this.capture}>Capture photo</button>
-      </div>
-    );
+    return <Webcam videoConstraints={videoConstraints} />;
   }
 }
 ```
 
+For more information on `facingMode`, please see the MDN web docs [https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode)
+
+## Show all cameras by deviceId
+
+```jsx
+const WebcamCapture = () => {
+  const [deviceId, setDeviceId] = React.useState({});
+  const [devices, setDevices] = React.useState([]);
+
+  const handleDevices = React.useCallback(
+    mediaDevices =>
+      setDevices(mediaDevices.filter(({ kind }) => kind === "videoinput")),
+    [setDevices]
+  );
+
+  React.useEffect(
+    () => {
+      navigator.mediaDevices.enumerateDevices().then(handleDevices);
+    },
+    [handleDevices]
+  );
+
+  return (
+    <>
+      {devices.map((device, key) => (
+          <div>
+            <Webcam audio={false} videoConstraints={{ deviceId: device.deviceId }} />
+            {device.label || `Device ${key + 1}`}
+          </div>
+
+        ))}
+    </>
+  );
+};
+```
+
+## Recording a stream
+
+https://codepen.io/mozmorris/pen/yLYKzyp?editors=0011
+
+## Using within an iframe
+
+The Webcam component will fail to load when used inside a cross-origin iframe in newer version of Chrome (> 64). In order to overcome this security restriction a special `allow` attribute needs to be added to the iframe tag specifying `microphone` and `camera` as the required permissions like in the below example:
+
+```html
+<iframe src="https://my-website.com/page-with-webcam" allow="camera; microphone;"/>
+```
+
+## Mirrored video but non-mirrored screenshot
+
+Add `mirrored` prop to the component will make the video and the screenshot be mirrored, but sometimes you need to show a mirrored video but take a non-mirrored screenshot, to accomplish that, you just need to add this CSS to your project:
+
+```css
+video {
+  transform: scaleX(-1);
+}
+```
+You can find an example at [https://codepen.io/mozmorris/pen/oNygXwz?editors=0110](https://codepen.io/mozmorris/pen/oNygXwz?editors=0110).
+
 ## License
 
 MIT
 
-## Credits
-
-Many thanks to @cezary for his work on this component.
+[build-badge]: https://img.shields.io/travis/com/mozmorris/react-webcam.svg?style=flat-square
+[build]: https://travis-ci.com/mozmorris/react-webcam
+[downloads-badge]: https://img.shields.io/npm/dw/react-webcam.svg?style=flat-square