0
# File Sources
1

2
File source plugins enable users to capture or select files from various local sources including cameras, microphones, screen recording, and file processing capabilities.
3

4
## Capabilities
5

6
### Media Capture
7

8
Plugins for capturing media directly from user devices.
9

10
```typescript { .api }
11
/**
12
 * Webcam capture for photos and videos
13
 */
14
class Webcam<M extends Meta = {}, B extends Body = {}> extends UIPlugin<WebcamOptions> {
15
  constructor(uppy: Uppy<M, B>, options?: WebcamOptions);
16
}
17

18
interface WebcamOptions {
19
  target?: string | Element;
20
  countdown?: boolean | number;
21
  modes?: Array<'video-audio' | 'video-only' | 'audio-only' | 'picture'>;
22
  mirror?: boolean;
23
  facingMode?: 'user' | 'environment';
24
  videoConstraints?: MediaTrackConstraints;
25
  showVideoSourceDropdown?: boolean;
26
  preferredVideoMimeType?: string;
27
  title?: string;
28
  locale?: Locale;
29
}
30

31
/**
32
 * Audio recording from microphone
33
 */
34
class Audio<M extends Meta = {}, B extends Body = {}> extends UIPlugin<AudioOptions> {
35
  constructor(uppy: Uppy<M, B>, options?: AudioOptions);
36
}
37

38
interface AudioOptions {
39
  target?: string | Element;
40
  showAudioSourceDropdown?: boolean;
41
  audioConstraints?: MediaTrackConstraints;
42
  audioContext?: AudioContext;
43
  preferredAudioMimeType?: string;
44
  title?: string;
45
  locale?: Locale;
46
}
47

48
/**
49
 * Screen capture and recording
50
 */
51
class ScreenCapture<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ScreenCaptureOptions> {
52
  constructor(uppy: Uppy<M, B>, options?: ScreenCaptureOptions);
53
}
54

55
interface ScreenCaptureOptions {
56
  target?: string | Element;
57
  displayMediaConstraints?: DisplayMediaStreamConstraints;
58
  userMediaConstraints?: MediaStreamConstraints;
59
  preferredVideoMimeType?: string;
60
  title?: string;
61
  locale?: Locale;
62
}
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { Uppy, Webcam, Audio, ScreenCapture } from "uppy";
69

70
const uppy = new Uppy()
71
  // Webcam with video and photo modes
72
  .use(Webcam, {
73
    countdown: 3,
74
    modes: ['video-audio', 'picture'],
75
    mirror: true,
76
    facingMode: 'user',
77
    preferredVideoMimeType: 'video/webm'
78
  })
79
  
80
  // Audio recording with device selection
81
  .use(Audio, {
82
    showAudioSourceDropdown: true,
83
    preferredAudioMimeType: 'audio/webm'
84
  })
85
  
86
  // Screen recording
87
  .use(ScreenCapture, {
88
    preferredVideoMimeType: 'video/webm',
89
    displayMediaConstraints: {
90
      video: { mediaSource: 'screen' }
91
    }
92
  });
93
```
94

95
### File Processing
96

97
Plugins for editing and processing files before upload.
98

99
```typescript { .api }
100
/**
101
 * Image editor with cropping and filtering
102
 */
103
class ImageEditor<M extends Meta = {}, B extends Body = {}> extends UIPlugin<ImageEditorOptions> {
104
  constructor(uppy: Uppy<M, B>, options?: ImageEditorOptions);
105
}
106

107
interface ImageEditorOptions {
108
  target?: string | Element;
109
  quality?: number;
110
  cropperOptions?: {
111
    viewMode?: number;
112
    background?: boolean;
113
    autoCropArea?: number;
114
    responsive?: boolean;
115
  };
116
  actions?: {
117
    revert?: boolean;
118
    rotate?: boolean;
119
    granularRotate?: boolean;
120
    flip?: boolean;
121
    zoomIn?: boolean;
122
    zoomOut?: boolean;
123
    cropSquare?: boolean;
124
    cropWidescreen?: boolean;
125
    cropWidescreenVertical?: boolean;
126
  };
127
  locale?: Locale;
128
}
129

130
/**
131
 * Image compression and optimization
132
 */
133
class Compressor<M extends Meta = {}, B extends Body = {}> extends BasePlugin<CompressorOptions> {
134
  constructor(uppy: Uppy<M, B>, options?: CompressorOptions);
135
}
136

137
interface CompressorOptions {
138
  quality?: number;
139
  limit?: number;
140
  mimeType?: string;
141
  convertTypes?: string | string[];
142
  convertSize?: number;
143
  locale?: Locale;
144
}
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
// Image editor with cropping tools
151
uppy.use(ImageEditor, {
152
  quality: 0.8,
153
  cropperOptions: {
154
    viewMode: 1,
155
    background: false,
156
    autoCropArea: 1,
157
    responsive: true
158
  },
159
  actions: {
160
    revert: true,
161
    rotate: true,
162
    granularRotate: true,
163
    flip: true,
164
    zoomIn: true,
165
    zoomOut: true,
166
    cropSquare: true,
167
    cropWidescreen: true
168
  }
169
});
170

171
// Image compression for file size optimization
172
uppy.use(Compressor, {
173
  quality: 0.6,
174
  limit: 1000, // 1MB limit
175
  convertTypes: ['image/webp', 'image/avif'],
176
  convertSize: 1000000 // Convert files larger than 1MB
177
});
178
```
179

180
## File Source Events
181

182
```typescript { .api }
183
// Media capture events
184
interface MediaCaptureEvents {
185
  'webcam:start': () => void;
186
  'webcam:stop': () => void;
187
  'webcam:error': (error: Error) => void;
188
  'audio:start': () => void;
189
  'audio:stop': () => void;
190
  'screen-capture:start': () => void;
191
  'screen-capture:stop': () => void;
192
}
193

194
// File processing events
195
interface FileProcessingEvents<M extends Meta = {}, B extends Body = {}> {
196
  'image-editor:open': (file: UppyFile<M, B>) => void;
197
  'image-editor:complete': (file: UppyFile<M, B>) => void;
198
  'image-editor:cancel': (file: UppyFile<M, B>) => void;
199
  'compressor:start': (file: UppyFile<M, B>) => void;
200
  'compressor:complete': (file: UppyFile<M, B>) => void;
201
}
202
```
203

204
## Media Constraints
205

206
```typescript { .api }
207
/**
208
 * Media stream constraints for device capture
209
 */
210
interface MediaConstraints {
211
  video?: boolean | MediaTrackConstraints;
212
  audio?: boolean | MediaTrackConstraints;
213
}
214

215
interface MediaTrackConstraints {
216
  aspectRatio?: number | ConstrainDouble;
217
  autoGainControl?: boolean | ConstrainBoolean;
218
  channelCount?: number | ConstrainULong;
219
  deviceId?: string | string[] | ConstrainDOMString;
220
  echoCancellation?: boolean | ConstrainBoolean;
221
  facingMode?: string | string[] | ConstrainDOMString;
222
  frameRate?: number | ConstrainDouble;
223
  groupId?: string | string[] | ConstrainDOMString;
224
  height?: number | ConstrainULong;
225
  noiseSuppression?: boolean | ConstrainBoolean;
226
  sampleRate?: number | ConstrainULong;
227
  sampleSize?: number | ConstrainULong;
228
  width?: number | ConstrainULong;
229
}
230

231
interface DisplayMediaStreamConstraints {
232
  video?: boolean | MediaTrackConstraints & {
233
    cursor?: 'always' | 'motion' | 'never';
234
    displaySurface?: 'application' | 'browser' | 'monitor' | 'window';
235
    logicalSurface?: boolean;
236
    mediaSource?: 'screen' | 'window' | 'application';
237
  };
238
  audio?: boolean | MediaTrackConstraints;
239
}
240
```