Concepts

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

• add, remove and rearrange video segments
• preview the segments individually
• preview the video as a whole
• trim video segments
• build a responsive UI to show controls to the user.

The editor will also forward all relevant events to subscribers that were registered with the addListener* functions. We recommend listening at least to the result and error event:

val editor: Editor = ...
editor.addListener(lifecycle, object : EditorListener {
    override fun onResult(edit: Edit) {
        // handle result!
    }
    override fun onError(error: VideoError) {
        // 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.

Editor interface

Note: if you use the default controls, the user will be able to control the editor through the user interface, so there's no need to interact directly with these functions.

Adding segments

To add video segments, you will need an Uri pointing to the video content. If you are using the recorder module, this might be coming from Record.uri or Clip.uri, for example. Once you have the uri,

// Insert at the given index:
editor.insertSegment(index = 0, uri = uri)
// Or, just append at the end:
editor.appendSegment(uri = uri)

The imported segments will soon be visible in the editor.segments list, and you will also receive live updates about them in the onSegmentsChanged() listener callback.

When a new segment is added, it is processed asynchronously to ensure that the data is valid, compute video properties (like duration) and extract thumbnails, which are useful for UI controls (e.g. a video trimmer). All this information is available through the Segment object that is exposed as described above.

Importing segments

Importing segments from gallery is even easier:

editor.importSegments()

The user will be presented with the system picker through which he will be able to choose one or more videos. After the videos are picked, they are automatically added to the editor and will be available in editor.segments just as if they were added using insert / append.

Moving and removing segments

After a segment has been added, it can be:

• removed using editor.removeSegment(index)
• moved to a different position using editor.moveSegment(fromIndex = 0, toIndex = 1)

As always, the editor.segments list will be updated as soon as possible and callbacks will be dispatched.

Trimming segments

At any point, a given segments can be trimmed using editor.trimSegment(index, trim). The trim information is stored in the Trim object, which contains the start and end trim values in the 0 .. 1 range, where, for example, start=0.2, end=0.3 means trimming the first 20% and the last 30% of the video.

val trim = Trim(
    start = 0.2F, // trim first 20%
    end = 0.3F // trim last 30%
)
editor.trimSegment(index, trim)

Of course, both values should be positive and smaller than 1, and their sum should also be smaller than 1. Each Segment object carries information about the trim in the Segment.trim field.

Segment selection

The editor (if UI is attached) is capable of previewing each segment individually, or previewing the whole video (made of all segments played serially, with effects like trimming applied). To ask the editor to preview a specific segment, it must be selected:

editor.selectSegment(index)

When this is done, the editor enters the EditorState.EDITING state and the playback will only include the selected segment. This is the right moment for you to show segment-specific editing controls, for example a trimmer bar (note that VideoKit provides one).

Once the single segment has been reviewed and potentially edited, you can go back to the full preview like so:

// go back, save changes:
editor.unselectSegment()

// or go back, but discard any change that was made when this
// segment was selected:
editor.unselectSegment(keepChanges = false)

The currently selected segment can be accessed using editor.selectedSegment.

Controlling playback

As described above, the editor with attached UI is able to preview either a single segment (if any of them is selected) or the whole set of segments. Regardless of which mode you are using, playback can be controlled with simple APIs that are very similar to VideoKit's Player SDK:

editor.play() // start playing
editor.pause() // pause playing
editor.toggle() // toggle between play and pause
val playing: Boolean = editor.playing // playing or not?

val position: Long = editor.position // playback position in ms
val duration: Long = editor.duration // playback duration in ms

editor.seek(targetPosition) // seek playback
editor.loop = true // enable/disable loop
editor.mute = true // enable/disable playback sound

These APIs and their respective callbacks can be used to implement playback UI controls.

Resetting the edit

To discard any segment data, cancel any ongoing operation and go back to the initial state, simply call editor.reset():

editor.reset()

Confirming the edit

To confirm the edited video, simply call editor.confirm(). This moves the editor to the EditorState.FINALIZING state and we'll transcode all video segments under the hood to create a single video file.

editor.confirm()

Depending on the amount of data to be processed, the finalization can take time. On top of the special editor state, we offer the editor.progress variable and callback, ranging from 0.0 to 1.0, so that you can display e.g. a progress bar to the user.

Once the operation is complete, the listener callback onResult(Edit) will be called, exposing the Uri of the edited media file.

If editor.saveToGallery was set to true, calling confirm will also save the resulting video to the user gallery.