mirror of
https://github.com/transloadit/uppy.git
synced 2026-07-24 10:47:44 +00:00
252 lines
8.5 KiB
Text
252 lines
8.5 KiB
Text
---
|
||
sidebar_position: 1
|
||
slug: /webcam
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
import UppyCdnExample from '/src/components/UppyCdnExample';
|
||
|
||
# Webcam
|
||
|
||
The `@uppy/webcam` plugin lets you take photos and record videos with a built-in
|
||
camera on desktop and mobile devices.
|
||
|
||
:::tip
|
||
|
||
[Try out the live example](/examples) or take it for a spin in
|
||
[StackBlitz](https://stackblitz.com/edit/vitejs-vite-zaqyaf?file=main.js).
|
||
|
||
:::
|
||
|
||
## When should I use it?
|
||
|
||
When you want your users to able to use their camera. This plugin is published
|
||
separately but made specifically for the [Dashboard](/docs/dashboard). You can
|
||
technically use it without it, but it’s not officially supported.
|
||
|
||
## Install
|
||
|
||
<Tabs>
|
||
<TabItem value="npm" label="NPM" default>
|
||
|
||
```shell
|
||
npm install @uppy/webcam
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="yarn" label="Yarn">
|
||
|
||
```shell
|
||
yarn add @uppy/webcam
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="cdn" label="CDN">
|
||
<UppyCdnExample>
|
||
{`
|
||
import { Uppy, Dashboard, Webcam } from "{{UPPY_JS_URL}}"
|
||
const uppy = new Uppy()
|
||
uppy.use(Dashboard, { inline: true, target: 'body' })
|
||
uppy.use(Webcam)
|
||
`}
|
||
</UppyCdnExample>
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
## Use
|
||
|
||
:::note
|
||
|
||
To use the Webcam plugin in Chrome,
|
||
[your site must be served over https](https://developers.google.com/web/updates/2015/10/chrome-47-webrtc#public_service_announcements).
|
||
This restriction does not apply on `localhost`, so you don’t have to jump
|
||
through many hoops during development.
|
||
|
||
:::
|
||
|
||
```js {3,7,11} showLineNumbers
|
||
import Uppy from '@uppy/core';
|
||
import Dashboard from '@uppy/dashboard';
|
||
import Webcam from '@uppy/webcam';
|
||
|
||
import '@uppy/core/dist/style.min.css';
|
||
import '@uppy/dashboard/dist/style.min.css';
|
||
import '@uppy/webcam/dist/style.min.css';
|
||
|
||
new Uppy().use(Dashboard, { inline: true, target: 'body' }).use(Webcam);
|
||
```
|
||
|
||
## API
|
||
|
||
### Options
|
||
|
||
#### `id`
|
||
|
||
A unique identifier for this plugin (`string`, default: `'Webcam'`).
|
||
|
||
#### `target`
|
||
|
||
DOM element, CSS selector, or plugin to place the drag and drop area into
|
||
(`string`, `Element`, `Function`, or `UIPlugin`, default:
|
||
[`Dashboard`](/docs/dashboard)).
|
||
|
||
#### `countdown`
|
||
|
||
When taking a picture: the amount of seconds to wait before actually taking a
|
||
snapshot (`boolean`, default: `false`).
|
||
|
||
If set to `false` or 0, the snapshot is taken right away. This also shows a
|
||
`Smile!` message through the [Informer](/docs/informer) before the picture is
|
||
taken.
|
||
|
||
#### `onBeforeSnapshot`
|
||
|
||
A hook function to call before a snapshot is taken (`Function`, default:
|
||
`Promise.resolve`).
|
||
|
||
The Webcam plugin will wait for the returned Promise to resolve before taking
|
||
the snapshot. This can be used to carry out variations on the `countdown` option
|
||
for example.
|
||
|
||
#### `modes`
|
||
|
||
The types of recording modes to allow (`Array`, default: `[]`).
|
||
|
||
- `video-audio` - Record a video file, capturing both audio and video.
|
||
- `video-only` - Record a video file with the webcam, but don’t record audio.
|
||
- `audio-only` - Record an audio file with the user’s microphone.
|
||
- `picture` - Take a picture with the webcam.
|
||
|
||
By default, all modes are allowed, and the Webcam plugin will show controls for
|
||
recording video as well as taking pictures.
|
||
|
||
#### `mirror`
|
||
|
||
Configures whether to mirror preview image from the camera (`boolean`, default:
|
||
`true`).
|
||
|
||
This option is useful when taking a selfie with a front camera: when you wave
|
||
your right hand, you will see your hand on the right on the preview screen, like
|
||
in the mirror. But when you actually take a picture, it will not be mirrored.
|
||
This is how smartphone selfie cameras behave.
|
||
|
||
#### `videoConstraints`
|
||
|
||
Configure the [`MediaTrackConstraints`][] (`Object`, default: `{}`).
|
||
|
||
You can specify acceptable ranges for the resolution of the video stream using
|
||
the [`aspectRatio`][], [`width`][], and [`height`][] properties. Each property
|
||
takes an object with `{ min, ideal, max }` properties. For example, use
|
||
`width: { min: 720, max: 1920, ideal: 1920 }` to allow any width between 720 and
|
||
1920 pixels wide, while preferring the highest resolution.
|
||
|
||
Devices sometimes have several cameras, front and back, for example.
|
||
[`facingMode`][] lets you specify which should be used:
|
||
|
||
- `user`: The video source is facing toward the user; this includes, for
|
||
example, the front-facing camera on a smartphone.
|
||
- `environment`: The video source is facing away from the user, thereby viewing
|
||
their environment. This is the back camera on a smartphone.
|
||
- `left`: The video source is facing toward the user but to their left, such as
|
||
a camera aimed toward the user but over their left shoulder.
|
||
- `right`: The video source is facing toward the user but to their right, such
|
||
as a camera aimed toward the user but over their right shoulder.
|
||
|
||
For a full list of available properties, check out MDN documentation for
|
||
[`MediaTrackConstraints`][].
|
||
|
||
[`mediatrackconstraints`]:
|
||
https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#Properties_of_video_tracks
|
||
[`aspectratio`]:
|
||
https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/aspectRatio
|
||
[`width`]:
|
||
https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width
|
||
[`height`]:
|
||
https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height
|
||
[`facingmode`]:
|
||
https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode
|
||
|
||
#### `showVideoSourceDropdown`
|
||
|
||
Configures whether to show a dropdown which enables to choose the video device
|
||
to use (`boolean`, default: `false`).
|
||
|
||
This option will have priority over `facingMode` if enabled.
|
||
|
||
#### `showRecordingLength`
|
||
|
||
Configures whether to show the length of the recording while the recording is in
|
||
progress (`boolean`, default: `false`).
|
||
|
||
#### `preferredVideoMimeType`
|
||
|
||
Set the preferred mime type for video recordings, for example `'video/webm'`
|
||
(`string`, default: `null`).
|
||
|
||
If the browser supports the given mime type, the video will be recorded in this
|
||
format. If the browser does not support it, it will use the browser default. If
|
||
no preferred video mime type is given, the Webcam plugin will prefer types
|
||
listed in the [`allowedFileTypes` restriction](/docs/uppy/#restrictions), if
|
||
any.
|
||
|
||
#### `preferredImageMimeType`
|
||
|
||
Set the preferred mime type for images, for example `'image/png'` (`string`,
|
||
default: `image/jpeg`).
|
||
|
||
If the browser supports rendering the given mime type, the image will be stored
|
||
in this format. Else `image/jpeg` is used by default. If no preferred image mime
|
||
type is given, the Webcam plugin will prefer types listed in the
|
||
[`allowedFileTypes` restriction](/docs/uppy/#restrictions), if any.
|
||
|
||
#### `mobileNativeCamera`
|
||
|
||
Replaces Uppy’s custom camera UI on mobile and tablet with the native device
|
||
camera (`Function: boolean` or `boolean`, default: `isMobile()`).
|
||
|
||
This will show the “Take Picture” and / or “Record Video” buttons, which ones
|
||
show depends on the [`modes`](#modes) option.
|
||
|
||
You can set a boolean to forcefully enable / disable this feature, or a function
|
||
which returns a boolean. By default we use the
|
||
[`is-mobile`](https://github.com/juliangruber/is-mobile) package.
|
||
|
||
#### `locale`
|
||
|
||
```js
|
||
export default {
|
||
strings: {
|
||
pluginNameCamera: 'Camera',
|
||
noCameraTitle: 'Camera Not Available',
|
||
noCameraDescription:
|
||
'In order to take pictures or record video, please connect a camera device',
|
||
recordingStoppedMaxSize:
|
||
'Recording stopped because the file size is about to exceed the limit',
|
||
submitRecordedFile: 'Submit recorded file',
|
||
discardRecordedFile: 'Discard recorded file',
|
||
// Shown before a picture is taken when the `countdown` option is set.
|
||
smile: 'Smile!',
|
||
// Used as the label for the button that takes a picture.
|
||
// This is not visibly rendered but is picked up by screen readers.
|
||
takePicture: 'Take a picture',
|
||
// Used as the label for the button that starts a video recording.
|
||
// This is not visibly rendered but is picked up by screen readers.
|
||
startRecording: 'Begin video recording',
|
||
// Used as the label for the button that stops a video recording.
|
||
// This is not visibly rendered but is picked up by screen readers.
|
||
stopRecording: 'Stop video recording',
|
||
// Used as the label for the recording length counter. See the showRecordingLength option.
|
||
// This is not visibly rendered but is picked up by screen readers.
|
||
recordingLength: 'Recording length %{recording_length}',
|
||
// Title on the “allow access” screen
|
||
allowAccessTitle: 'Please allow access to your camera',
|
||
// Description on the “allow access” screen
|
||
allowAccessDescription:
|
||
'In order to take pictures or record video with your camera, please allow camera access for this site.',
|
||
},
|
||
};
|
||
```
|