label: string
The label on the embedded button – this is the text that gets displayed on the button, which is placed into the wrapper element.
size: string
The size of the Clipchamp button, choose between 4 sizes.
title: string
The title of the UI that appears after a user clicks on the embedded button. The title is shown at the top of the popup iframe
.
logo: string
The URL of the logo image for the UI – this is an image that is shown in the top-left corner of the iframe
.
color: string
Determines the color of the Clipchamp button, the background of the popup’s title bar and other graphical elements. Can be a color name (such as blue
, a hex-encoded color code (such as #3300cc
), or an RGB-encoded color (such as rgba(78,24,212,0.5)
).
style: object
Allows for the detailed customization of the API’s visual appearance using CSS. A custom CSS stylesheet can be provided as a URL (style.url
property) or as CSS declarations string (style.text
). In both cases, the custom CSS declarations augment but do not replace the default user interface styling, based on the Bootstrap 3 default styling. That is, the custom CSS styling is layered on top of the existing CSS styling where existing CSS classes can be augmented, CSS properties be added or replaced. Enterprise plan.
inline: object
Allows for an inline placement of the API’s widget where the <iframe>
that contains the Clipchamp widget is placed inside a nominated wrapper element on the embedding page. Available in the Enterprise plan.
encoding: object
Configure a number of output encoding parameters.
inputs: Array<string>
Sources the user can pick an input video from – camera
for her webcam and file
for her computer’s file system. The direct
option instructs the Clipchamp API to receive the input video file(s) without any end user action directly through the direct.files
parameter. Consequently, the direct
input option should not be used in combination with any of the other two options (file
, camera
). If both direct
and file
or camera
are given in the inputs
array, then the file
and camera
options will be ignored and the direct.files
parameter is expected to be an array of Blob
instance(s).
output: string
The destinations where we will make the output video available or upload to. If “blob” is chosen we provide the output video as a Blob
to your client-side JavaScript code. If you select “youtube”, “azure” or “s3”, you need to authorize us to upload the video into the appropriate account from the configuration page. The “dummy” output doesn’t output anything at all but it simulates an upload using a simple timer and can be used for initial integration and testing without having a backend configured.
upload: object
Settings that configure the upload process across all supported upload targets.
camera: object
Configuration elements for customizing camera recordings.
direct: object
Extra parameters that apply to the direct
option within the inputs parameter.
enable: Array<string>
Enable special behaviour of the Clipchamp API:
batch
– allow multiple files to be processed and uploaded in sequence without further user interaction.fixup-webcam-webm
– “fixes” WebM webcam recordings which can have incorrect or missing timely duration metadata. Use this flag if you want to make sure that subsequent steps in your video processing pipeline receive WebM files where the embedded video metadata is correct and complete. This flag does not currently apply to mobile devices (ie., Android phones with themobile-webcam-format-fallback
flag set). BETAmobile-webcam-format-fallback
– enables the compression of webcam recordings on mobile devices even when the target format is not available (experimental). This feature is currently restricted to Chrome on Android where with this flag, the Clipchamp API produces WebM files using the VP8 or VP9 video codec.no-branding
– remove Clipchamp branding from the user-facing UI, if available in your plan. This does not apply to the embedded button. Use the Custom Button API option to style the embedded button (if available in your plan).no-error-bypass
– if transcoding fails for whatever reason, normally Clipchamp would resort to simply uploading the input file as is. This flag suppresses that behavior. The most common cause for transcoding failures are unsupported input codecs.no-hidden-run
– disable the option to continue processing and uploading in the background if the user closes the window after clicking “submit”.no-popout
– some browsers block the use of certain features for third party code. When this is detected, Clipchamp will open a new window in order to gain access to these features. Settingno-popout
suppresses this behavior, and forces Clipchamp to try to make do with what’s available. This might lead to increased memory requirements, among other things.no-probe-reject
– in case we are unable to determine that an input file is a video it would normally be rejected. This option accepts all input files and skips straight to upload for non-video files.no-thank-you
– disable the thank you screen and close window immediately. If there were any errors encountered during the process the last screen will still be displayed.no-user-retry
– disable user confirmation and retry option after a webcam recording was completed and before the file is uploaded. Adding this flag will immediately start the upload after the webcam recording has ended. Users will not have a chance to repeat their webcam recording.
experimental: Array<string>
Enable experimental behaviour of the Clipchamp API
force-popout
– always launch the user interface of the Clipchamp API in a separate “popout” browser window, even if it could run inside aniframe
inside the embedding website’s DOM. Must not be used in conjunction with theno-popout
flag (enable
) parameter.overlong-recording
– allow webcam/mobile camera recordings without any timely limitation of the recording duration (as otherwise enforced by the Clipchamp API). The recording duration can still be deliberately limited by setting a numeric value (number of seconds) in thecamera.limit
parameter. Clients need to make sure to only set theoverlong-recording
flag in supported browsers (currently: Chrome, Opera, and Firefox).h264-hardware-acceleration
– enable hardware-accelerated H.264 video encoding on supported platforms (currently: x86-based ChromeOS/Chromebook devices). The flag only applies to theweb
(default)preset
and themp4
(default) format. Depending on the underlying hardware, a multiple times speedup can be attained when setting theh264-hardware-acceleration
flag. Clients will experience different compression ratio for the same (subjective) perceived output quality and are thus encouraged to adjust thecompression
parameter to yield an acceptable quality/compression tradeoff.
s3: object
Configuration elements for the use of the Amazon S3 upload target. (configuration instructions for S3)
azure: object
Configuration elements when using the Microsoft Azure blob storage upload target. (configuration instructions for Azure)
gdrive: object
Configuration elements when using the Google Drive upload target. (configuration instructions for Google Drive)
dropbox: object
Configuration elements to use the Dropbox upload target.
youtube: object
Configuration elements when making use of the YouTube upload target.
onWebcamStatusChange(status): function
This callback function is invoked for a number of events affecting the recording of videos and the webcam or phone camera where status
is a String
reflecting the new status of the webcam or the recording:
capture_started
– the webcam or phone camera was successfully switched on and is capturing (but not yet recording) a video streamcapture_ended
– the webcam or phone camera was switched off and is no longer capturing a video streamcapture_failed
– accessing the webcam or phone camera failedrecording_running
– the webcam recording has started or was resumed after it was previously pausedrecording_paused
– the webcam recording was paused and can later be resumed or finishedrecording_finished
– the webcam recording has finished but may still be processing before it is being uploaded or made available in theonVideoCreated
callbackrecording_cancelled
– the webcam recording was cancelled
Tracking the status of the webcam or phone camera is supported in desktop browsers (and in Chrome on Android when the mobile-webcam-format-fallback
flag is set in the enable
parameter array).
onMetadataAvailable(metadata): function
This callback function is invoked for every webcam recording and input video file when the webcam recording or input video file was successfully analysed. The metadata
parameter is an object with the following properties:
raw
– the raw video metadata being an object with the following properties:format
– video container format informationstreams
– array of video, audio, subtitle, data, etc. streams contained in the video
Notice that when the user chooses to discard and repeat a webcam recording, this callback will be invoked multiple times with the metadata of the different recordings. onMetadataAvailable
will also be invoked multiple times when using the batch
flag, where the user can select multiple input videos. BETA
onPreviewAvailable(imageBlob): function
onPreviewAvailable
is called with the preview image when one is available. Note that the parameter is a Blob
instance and not a URL – the image is not uploaded to the nominated upload destination alongside the output video. Also note that not all scenarios will produce a preview image, particularly so if the input video is corrupt or contains invalid/incomplete metadata. BETA
onUploadComplete(data): function
This callback function is invoked once when the output video has completed uploading where a single data
object contains meta information about the uploaded file. There are 2 common properties:
filename
– the original video filenameduration
– the video duration. This field may be absent in certain situations
There are as a well a number of output
-specific properties:
- If using output “youtube”
kind
– “youtube”id
– the video IDurl
– the view URLembedHtml
– the HTML snippet provided by YouTube for embedding the video (if provided).
- If using output “azure”
kind
– “azure”blob
– the actual Azure blob name ultimately used when storing the upload.
- If using output “s3”
kind
– “s3”key
– the actual Amazon S3 object key ultimately used when storing the upload.
- If using output “gdrive”
kind
– “gdrive”id
– the Google file IDname
– the name of the file as stored in Google Drive.url
– a URL to the filefolder
– the Google folder ID the file is in, or “root” if at the top level.
- If using output “dropbox”
kind
– “dropbox”id
– the Dropbox file IDname
– the name of the file as stored on Dropboxpath
– the file path on Dropboxlink
– the shared link of the file on Dropbox (requires the corresponding option to be toggled in the Clipchamp API settings)
- If using output “blob”
kind
– “blob”data
– array of whateveronVideoCreated
resulted in
onVideoCreated: function
onVideoCreated(blob [,done [,fail [,notify]]])
onVideoCreated
is called if the output is set to blob
and the output video blob will be passed as the first parameter. The blob is valid until this function finishes processing which is determined using either 1 of 3 cases:
- If the function signature contains at least a done parameter and either done or fail callback is called.
- If a promise (or thenable) is returned, wait for it to be resolved or rejected.
- If the function returns something other than a promise, and doesn’t specify at least a done-callback parameter, the processing will be considered completed immediately on return.
Until the function completes processing the output file is considered as “being uploaded”. If a promise capable of progress reports is returned (i.e. where the then-function accepts a third callback), or if the notify callback is used, a numeric progress will be interpreted as an upload completion percentage and will be displayed as such on screen. After the processing is completed (as determined above) the blob can no longer be used reliably as the backing store may have been removed.
onErrorOccurred: function
onErrorOccurred
is called when an error was detected while recording, processing, or uploading a video or camera recording. The error
parameter is an object with a mandatory type
property, which can be one of the following:
webcam_processing
, when the error happened during a webcam (or phone camera) recording;video_processing
, when the error happened while an input video or webcam/camera recording was processed (transcoded/compressed) prior to uploading the video;video_uploading
, when the error happened while the processed output video file was being uploaded to its selected storage location;other_unknown
, when the cause of the error is something else or is even unknown;
A second (optional) property message
represents a human-readable error explanation. You can use the string value of the message
property to show an error message to your users. An optional details
property is an array that contains further technical information about the error, such as exceptions, error events and the like. Use the value of the details
property to communicate any issues to the Clipchamp support. The onErrorOccurred
callback may occasionally be called multiple times for the same root cause. Please note that the Clipchamp API has the provisions to compensate for some of the incidents that are reported to the onErrorOccurred
callback. For instance, the no-probe-reject
flag (see enable parameter) will make sure a video file is passed down to the video transcoding engine even if we could not extract technical metadata from that file.
localization: object
A table of strings that are available for localization. Use it to adjust all user-facing elements of the API to appear in the language of your website if it is not English. Note that you can also use these strings to blank out text snippets you don’t want to show to your users at all.