Relaks Media Capture
A reusable library for capturing video, audio, and images in a web browser. Designed to be used with Relaks.
Installation
npm --save-dev install relaks-media-capture
Usage
; { superprops; let options = video: true audio: true watchVolume: true ; thiscapture = options; } async { meanwhile; let props = onStart: thishandleStart onStop: thishandleStop onPause: thishandlePause onResume: thishandleResume onClear: thishandleClear onChoose: thishandleChoose onAccept: thishandleAccept onCancel: thishandleCancel ; thiscapture; do propsstatus = thiscapturestatus; propsdevices = thiscapturedevices; propschosenDeviceID = thiscapturechosenDeviceID; propsliveVideo = thiscaptureliveVideo; propsduration = thiscaptureduration; propsvolume = thiscapturevolume; propscapturedImage = thiscapturecapturedImage; propscapturedVideo = thiscapturecapturedVideo; meanwhile; await thiscapture; while thiscaptureactive; return <VideoDialogBoxSync ...props />; }
Options
- audio
- audioBitsPerSecond
- audioMIMEType
- captureImageOnly
- chooseNewDevice
- deactivationDelay
- imageMIMEType
- preferredDevice
- segmentDuration
- silent
- video
- videoBitsPerSecond
- videoMIMEType
- watchVolume
audio
A boolean indicating whether audio is desired.
Default value: true
.
audioBitsPerSecond
The desired audio bitrate.
Default value: 128000
audioMIMEType
The desired audio type. Due to licensing cost, it's unlikely that anything other than the open source WebM would be available.
Default value: "audio/webm"
captureImageOnly
Whether the desired result is an image rather than a video. When it's set, calling snap()
will change the status to "captured"
.
Default value: false
chooseNewDevice
Whether a new device should be automatically chosen as the input.
Default value: true
imageMIMEType
The desired audio type.
Default value: "image/jpeg"
preferredDevice
A text string indicating the preferred input device. If the device label contains the text, it'll be chosen.
Default value: "front"
segmentDuration
Duration of a video segment, in millisecond, that the MediaRecorder
should yield as soon as that amount of data becomes available. This allows a video to be uploaded in chunks as it's being recorded.
When it's set, the media capture object will emit the chunk
event periodically. It'll emit the end
event when capturing ends.
Default value: undefined
silent
Whether errors get sent to the development console.
Default value: false
.
video
A boolean indicating whether video is desired.
Default value: true
videoBitsPerSecond
The desired video bitrate.
Default value: 2500000
videoMIMEType
The desired video type. Due to licensing cost, it's unlikely that anything other than the open source WebM would be available.
Default value: "video/webm"
watchVolume
A boolean indicating whether audio volume should be monitored.
Default value: false
Properties
- active
- capturedImage
- capturedAudio
- capturedVideo
- chosenDeviceID
- devices
- duration
- lastError
- liveAudio
- liveVideo
- status
- volume
active
A boolean indicating whether the media capture object is active.
capturedImage
An object holding properties of the captured image, with the following properties:
blob
- blob containing the image dataurl
- URL to the blobwidth
- Width of the imageheight
- height of the image
The URL will be revoked when deactivate()
is called. It should only be used while the media capture object is active.
capturedAudio
An object holding properties of the captured audio, with the following properties:
blob
- blob containing the audio dataurl
- URL to the blob
The URL will be revoked when deactivate()
is called. It should only be used while the media capture object is active.
capturedVideo
blob
- blob containing the video dataurl
- URL to the blobwidth
- width of the imageheight
- height of the image
The URL will be revoked when deactivate()
is called. It should only be used while the media capture object is active.
chosenDeviceID
ID of the currently chosen camera.
devices
An array containing objects describing available input devices, each with the following properties:
id
- the device's ID (a string)label
- the device's name
duration
Duration of the captured video/audio, in millisecond. undefined
initially.
lastError
The last error encountered.
liveAudio
An object representing the input from the microphone, with the following properties:
stream
- an instance ofMediaStream
It's only available when audio
is true
and video
is false
.
liveVideo
An object representing the input from the camera, with the following properties:
stream
- an instance ofMediaStream
height
- the height of the videowidth
- the width of the video
It's available when video
is true
.
height
and width
will swap when the user rotates a phone or tablet.
status
One of the following:
- "acquiring" - in the process of acquiring a camera
- "denied" - permission to use camera was denied
- "initiating" - permission has been granted and the camera is about to become available
- "previewing" - camera input is available
- "capturing" - video/audio capturing is happening
- "paused" - Video/audio capturing has been paused
- "captured" - a video, audio, or image has been captured
volume
A number between 0 and 100 indicating the strength of audio coming from the microphone.
It's present only when watchVolume
is true
.
Methods
Event listeners:
Activation
Video/audio capture:
Image capture:
Others:
addEventListener()
Add an event listener to the route manager. handler
will be called whenever events of type
occur. When beginning
is true, the listener will be place before any existing listeners. Otherwise it's added at the end of the list.
Inherited from relaks-event-emitter.
removeEventListener()
Remove an event listener from the route manager. handler
and type
must match what was given to addEventListener()
.
Inherited from relaks-event-emitter.
waitForEvent()
Return a promise that is fulfilled when an event of the specified type occurs.
Inherited from relaks-event-emitter.
activate()
Activate the media capture object.
deactivate()
Deactivate the media capture object.
pause()
Pause capturing. status
will change to "pause"
.
resume()
Resume capturing. status
will become "capturing"
again.
start()
Start capturing video and/or audio. status
will change to "capturing"
.
stop()
Stop capturing. status
will change to "captured"
soon afterward.
snap()
Take a snapshot of the camera input. The result will be stored in capturedImage
.
status
will become "captured"
afterward if captureImageOnly
is true
.
change()
Wait for a change
event to occur.
choose()
Choose the camera or mic with the specified ID as the recording device.
clear()
Clear capturedVideo
, capturedAudio
, and capturedImage
. Return to previewing.
Events
change
The change
event is emitted after a property of media capture object has changed.
Properties:
propagationStopped
- whetherstopImmediatePropagation()
was calledtarget
- media capture objecttype
-"change"
Methods:
stopImmediatePropagation()
- stop other listeners from receiving the event
chunk
The chunk
event is emitted when a chunk of data become available. Only occurs when segmentDuration is set.
Properties:
blob
- aBlob
containing data of a video/audio segmentpropagationStopped
- whetherstopImmediatePropagation()
was calledtarget
- media capture objecttype
-"change"
Methods:
stopImmediatePropagation()
- stop other listeners from receiving the event
end
The end
event is emitted when video recording has come to an end, after the final chunk
event. Only occurs when segmentDuration is set.
Properties:
propagationStopped
- whetherstopImmediatePropagation()
was calledtarget
- media capture objecttype
-"change"
Methods:
stopImmediatePropagation()
- stop other listeners from receiving the event