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 iframe.

The URL of the logo image for the UI – this is an image that is shown in the top-left corner of the iframe.

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)).

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 (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).

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.

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-fallback flag 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-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.

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 iframe inside the embedding website’s DOM. Must not be used in conjunction with the no-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 the camera.limit parameter. Clients need to make sure to only set the overlong-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 the web (default) preset and the mp4 (default) format. Depending on the underlying hardware, a multiple times speedup can be attained when setting the h264-hardware-acceleration flag. Clients will experience different compression ratio for the same (subjective) perceived output quality and are thus encouraged to adjust the compression parameter 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 onVideoCreated callback
• 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 output-specific properties:

• If using output “youtube”
  • kind – “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”
  • 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 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”
  • kind – “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”
  • kind – “blob”
  • data – array of whatever onVideoCreated resulted in

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:

1. If the function signature contains at least a done parameter and either done or fail callback is called.
2. If a promise (or thenable) is returned, wait for it to be resolved or rejected.
3. 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.