Concepts

The entry point for the recorder SDK is the io.video.videokit.recorder.Recorder interface. This interface provides functions to:

• start and stop the recording
• control the camera through Recorder.camera
• configure the upload
• preview the recorded video
• build a responsive UI to show controls to the user.

The recorder will forward all relevant events to subscribers that were registered with the addObserver or similar functions, or, for coroutine users, collectors of one of the exposed flows. We recommend listening at least to the result and error event:

val recorder: Recorder = ...
recorder.addObserver(object : Recorder.Observer {
    override fun onResult(recording: Recording) {
        // handle result!
    }
    override fun onError(error: VideoKitException) {
        // handle error!
    }
})

We provide different implementations that can be used within your app depending on your needs, but all of them share the same API surface described below. All of them will also automatically request the appropriate permissions: camera, microphone and, in some cases, storage.

Recorder interface

Recording

The recorder is able to record multiple clips together in a single file. This means that recording can be paused and resumed as many times as you want. To start recording:

recorder.start()

This will soon move the recorder.state from RecorderState.Idle to RecorderState.Recording. To pause recording:

recorder.pause()

This will bring back recorder.state to RecorderState.Idle. At this point, the video is not finalized, and you have different options:

• resume recording, with recorder.start()
• confirm the video, with recorder.stop()
• discard the video, with recorder.reset()
• enter or exit preview mode

The recorder can go through multiple start() / pause() calls and the new video will just be appended to the existing content. You can also change camera sensor and settings in between.

Recording and segments

As you record clips with start() and pause(), the recorder will expose information about the recorded data with Recording and Segment objects:

// After the first start / pause cycle, you will find a non-null Recording
val recording: Recording? = recorder.recording

// List of clips, each one representing a start / pause cycle
val segments: List<Segment> = recording.segments

// Recorded duration in milliseconds, keeps growing
val duration: Long = recorder.duration

Canceling the recording

To discard the recorded data (assuming it was not confirmed yet), simply call reset(). This will move the recorder to its original state, with no pending recording and zero segments:

recorder.reset()

Confirm the recording

To confirm the recorded data, simply call stop(). This tells the recorder that you are not planning to write anything else to this file.

recorder.stop()

After this call, you should soon receive a complete Recording in the onResult() listener callback. The record will contain several properties, most importantly an uri pointing to the resulting file.

Duration limits

The recorder has an option to stop recording automatically after a certain duration has been reached. This duration can be set through recorder.maxDuration in milliseconds:

// Stop automatically after 15 seconds:
recorder.maxDuration = 15 * 1000L

Importing videos

You have the option to import videos from the gallery using the import* functions.

// Opens the gallery picker to choose a video
recorder.import()

// Imports a specific video by Uri
recorder.import(uri)

In both cases, the recorder will enter preview mode to preview the video.

Configuring video parameters

You can configure both audio and video encoding parameters using the AudioOptions and VideoOptions class and passing them to the recorder. Since the encoders available on-device might not support all configuration, the recorder class accepts a list of options instead of a single value. The recorder will try each option and, if not supported, try with the next one.

recorder.audioOptions = listOf(AudioOptions(
   samplingFrequency = 44100,
   channels = 1,
   bitRate = 96000,
))

val mainVideoOptions = VideoOptions(
    size = VideoSize(1280, 720),
    frameRate = 30
)
val fallbackVideoOptions = VideoOptions(
   size = VideoSize(720, 480),
   frameRate = 24
)
recorder.videoOptions = listOf(mainVideoOptions, fallbackVideoOptions)