Programmatic Webcam Control

On top of the Custom Button API you can programmatically control the webcam recorder, ie., without requiring user interactions. You should combine the programmatic webcam control with the onWebcamStatusChange callback, which will allow you to keep state in your code in sync with the actual state of the webcam recorder. The process.open() call of the Custom Button API returns a Javascript Promise, which resolves into a webcam API object when the Clipchamp widget is shown:

<script type="text/javascript">
    var process = clipchamp({
        inputs: ['camera'], // go directly to the webcam
        enable: [
            'no-thank-you', // close widget after upload and skip final 'Thank you' screen
            'no-user-retry', // directly upload video after finishing recording
            'mobile-webcam-format-fallback' // use inline recorder in Chrome on Android
        ],
        onWebcamStatusChange: function(status) {
            // handle current webcam and recording status (optional)
        }
    });
    process.open().then(function(remote) {
        // Webcam widget is now open.
        // First check if webcam/phone camera is ready:
        remote.areRecordingDevicesReady().then(function() {
            // Webcam/camera can be used on this browser/device.
            // Now call remote.startRecording() to start recording.
        }).catch(function() {
            // webcam/camera not accessible on this browser/device
        });
    });
</script>

We recommend to initially call the areRecordingDevicesReady() function, which resolves if the webcam can be successfully accessed and recording is generally possible. You can use this call as a “preflight” check to confirm that the subsequent calls can be performed. Please note that areRecordingDevicesReady may require a user interaction to approve a browser popup that prompts the browser to approve the domain api.clipchamp.com to access the webcam and microphone. Once approved, the corresponding permission is typically stored in the browser profile, but may be revoked at any time as a result of the user clearing out the browser cache, using the browser’s incognito mode, new hardware devices becoming available or other incidents. Hence, it is a good idea to precede every invocation of the programmatic webcam control API by an areRecordingDevicesReady() call. The other functions of the programmatic webcam control API are:

  • startRecording(): Starts the recording if the Clipchamp widget shows the webcam screen and the webcam capture is on.
  • pauseRecording(): Pauses the recording if a recording was previously started and is not currently paused.
  • resumeRecording(): Resumes the recording if a recording was previously started and is currently paused.
  • finishRecording(): Finishes the recording and triggers the subsequent processing of the video.
  • cancelRecording(): Aborts a recording and closes the Clipchamp widget.

All of these functions are asynchronous and may return before the corresponding action is complete. Please use the onWebcamStatusChange callback to synchronize any state on your side with the actual state of the webcam recorder. If a function of the webcam control API is called and the webcam recorder is in an incompatible state, the call may not be queued for later execution when the webcam recorder has reached the correct state. For instance, the behavior of the webcam control API is not defined when you call startRecording(), but the onWebcamStatusChange callback has not previously signaled that the webcam capture was successfully switched on (capture_started).