The label on the embedded button – this is the text that gets displayed on the button, which is placed into the wrapper element.
The size of the Clipchamp button, choose between 4 sizes.
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
The URL of the logo image for the UI – this is an image that is shown in the top-left corner of the
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
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.
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.
Configure a number of output encoding parameters.
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 (
camera). If both
camera are given in the
inputs array, then the
camera options will be ignored and the
direct.files parameter is expected to be an array of
The destinations where we will make the output video available or upload to. If “blob” is chosen we provide the output video as a
Settings that configure the upload process across all supported upload targets.
Configuration elements for customizing camera recordings.
Extra parameters that apply to the
direct option within the inputs parameter.
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 the
mobile-webcam-format-fallbackflag set). BETA
mobile-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. Setting
no-popoutsuppresses 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.
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 an
iframeinside the embedding website’s DOM. Must not be used in conjunction with the
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 the
camera.limitparameter. Clients need to make sure to only set the
overlong-recordingflag 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 the
mp4(default) format. Depending on the underlying hardware, a multiple times speedup can be attained when setting the
h264-hardware-accelerationflag. Clients will experience different compression ratio for the same (subjective) perceived output quality and are thus encouraged to adjust the
compressionparameter to yield an acceptable quality/compression tradeoff.
Configuration elements for the use of the Amazon S3 upload target. (configuration instructions for S3)
Configuration elements when using the Microsoft Azure blob storage upload target. (configuration instructions for Azure)
Configuration elements when using the Google Drive upload target. (configuration instructions for Google Drive)
Configuration elements to use the Dropbox upload target.
Configuration elements when making use of the YouTube upload target.
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 stream
capture_ended– the webcam or phone camera was switched off and is no longer capturing a video stream
capture_failed– accessing the webcam or phone camera failed
recording_running– the webcam recording has started or was resumed after it was previously paused
recording_paused– the webcam recording was paused and can later be resumed or finished
recording_finished– the webcam recording has finished but may still be processing before it is being uploaded or made available in the
recording_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).
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 information
streams– 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 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
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 filename
duration– the video duration. This field may be absent in certain situations
There are as a well a number of
- If using output “youtube”
id– the video ID
url– the view URL
embedHtml– the HTML snippet provided by YouTube for embedding the video (if provided).
- If using output “azure”
blob– the actual Azure blob name ultimately used when storing the upload.
- If using output “s3”
key– the actual Amazon S3 object key ultimately used when storing the upload.
- If using output “gdrive”
id– the Google file ID
name– the name of the file as stored in Google Drive.
url– a URL to the file
folder– the Google folder ID the file is in, or “root” if at the top level.
- If using output “dropbox”
id– the Dropbox file ID
name– the name of the file as stored on Dropbox
path– the file path on Dropbox
link– the shared link of the file on Dropbox (requires the corresponding option to be toggled in the Clipchamp API settings)
- If using output “blob”
data– array of whatever
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 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.
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.