VideoKitRecorder

class VideoKit.VideoKitRecorder : MonoBehaviour

This component manages recording videos. The component can be added to any game object in the scene.

One recorder component can only record one video at a time. To record multiple videos simultaneously, use multiple recorder components.

Format Settings

The recorder's format settings dictate what types of media can be recorded, and how the resulting recording is handled:

Specifying the Recording Format

/// <summary>
/// Recording format.
/// </summary>
Format format { get; set; }

The format dictates what type of file gets recorded in a given recording session. Currently, the following formats are supported:

/// <summary>
/// Recording format.
/// </summary>
enum Format {
    /// <summary>
    /// MP4 video with H.264 AVC video codec.
    /// This format supports recording both video and audio.
    /// </summary>
    MP4 = 0,
    /// <summary>
    /// MP4 video with H.265 HEVC video codec.
    /// This format has better compression than `MP4`.
    /// This format supports recording both video and audio.
    /// </summary>
    HEVC = 1,
    /// <summary>
    /// WEBM video.
    /// This format support recording both video and audio.
    /// This is only supported on Android and WebGL.
    /// </summary>
    WEBM = 2,
    /// <summary>
    /// Animated GIF image.
    /// This format only supports recording video.
    /// </summary>
    GIF = 3,
    /// <summary>
    /// JPEG image sequence.
    /// This format only supports recording video.
    /// </summary>
    JPEG = 4,
    /// <summary>
    /// Waveform audio.
    /// This format only supports recording audio.
    /// </summary>
    WAV = 5,
}

The MP4 and HEVC formats are not supported on WebGL.

The WEBM format is currently only supported on Android and WebGL.

Specifying the Recording Destination

/// <summary>
/// Recording destination.
/// </summary>
Destination destination { get; set; }

The recorder destination determines if and how recorded videos are saved after a recording is finished. The following destinations are supported:

/// <summary>
/// Recorded media destination.
/// </summary>
[Flags]
enum Destination {
    /// <summary>
    /// Recorded media is discarded immediately.
    /// </summary>
    None        = 0b0000,
    /// <summary>
    /// Record media to the app's private documents directory.
    /// </summary>
    Documents   = 0b0001,
    /// <summary>
    /// Record images and videos to the camera roll.
    /// </summary>
    CameraRoll  = 0b0010,
    /// <summary>
    /// Prompt the user to share the recorded media with the native sharing UI.
    /// </summary>
    PromptUser  = 0b0100,
    /// <summary>
    /// Playback the video with the platform default media player.
    /// </summary>
    Playback    = Documents | 0b1000,
}

Specifying the Recording Directory

/// <summary>
/// Recording destination path prefix when saving recordings to the app's documents.
/// </summary>
string destinationPathPrefix { get; set; } = @"VideoKit";

When the recorder destination includes Destination.Documents, the destinationPathPrefix property is used to control the subdirectory where recordings are saved.

When the destinationPathPrefix is null or empty, recordings are saved to the application's documents directory.

Specifying the Video Mode

/// <summary>
/// Video recording mode.
/// </summary>
VideoMode videoMode { get; set; }

The videoMode defines how video frames will be recorded. The following video modes are supported:

/// <summary>
/// Video recording mode.
/// </summary>
enum VideoMode {
    /// <summary>
    /// Don't record video.
    /// </summary>
    None        = 0,
    /// <summary>
    /// Record video frames from one or more game cameras.
    /// </summary>
    Camera      = 1,
    /// <summary>
    /// Record video frames from the screen.
    /// </summary>
    Screen      = 2,
    /// <summary>
    /// Record video frames from a texture.
    /// </summary>
    Texture     = 3,
    /// <summary>
    /// Record video frames from a camera device.
    /// </summary>
    CameraDevice    = 4,
}

The videoMode is ignored when the recorder format does not support recording video frames.

Specifying the Audio Mode

/// <summary>
/// Audio recording mode.
/// </summary>
AudioMode audioMode { get; set; }

The audioMode defines how audio frames will be recorded. The following audio modes are supported:

/// <summary>
/// Audio recording mode.
/// </summary>
[Flags]
enum AudioMode {
    /// <summary>
    /// Don't record audio.
    /// </summary>
    None            = 0,
    /// <summary>
    /// Record audio frames from the scene's audio listener.
    /// </summary>
    AudioListener   = 1,
    /// <summary>
    /// Record audio frames from an audio device.
    /// </summary>
    AudioDevice     = 2,
}

Recording (AudioListener | Microphone) is not yet supported, but will be soon.

Video Settings

The video settings are used to configure the video stream of recordings.

These settings only have an effect when the format supports recording video frames, and when the videoMode is not VideoMode.None.

Specifying the Video Resolution

/// <summary>
/// Video recording resolution.
/// </summary>
Resolution resolution { get; set; }

The resolution determines the video resolution of recorded videos or images. The following resolution presets are supported:

/// <summary>
/// Video recording resolution presets.
/// </summary>
enum Resolution {
    /// <summary>
    /// SD resolution.
    /// </summary>
    _640x480    = 0,
    /// <summary>
    /// HD resolution.
    /// </summary>
    _1280x720   = 1,
    /// <summary>
    /// Full HD resolution.
    /// </summary>
    _1920x1080  = 2,
    /// <summary>
    /// 2K WQHD resolution.
    /// </summary>
    _2K = 3,
    /// <summary>
    /// 4K UHD resolution.
    /// </summary>
    _4K = 4,
    /// <summary>
    /// Screen resolution.
    /// </summary>
    Screen = 9,
    /// <summary>
    /// Half of the screen resolution.
    /// </summary>
    HalfScreen = 10,
}

Resolutions are always specified in landscape format, meaning that the width is always larger than the height.

We recommend against recording at Screen resolution because some devices have very high screen pixel density. Use 1920x1080 instead.

Specifying the Video Orientation

/// <summary>
/// Video orientation mode.
/// </summary>
OrientationMode orientation { get; set; }

The orientation determines whether the video is recorded in portrait or landscape. The following orientation modes are supported:

/// <summary>
/// Video orientation mode.
/// </summary>
enum OrientationMode {
    /// <summary>
    /// Match the screen orientation.
    /// </summary>
    MatchScreen = 0,
    /// <summary>
    /// Record in landscape.
    /// </summary>
    Landscape = 1,
    /// <summary>
    /// Record in portrait.
    /// </summary>
    Portrait = 2,
}

The orientation property does not rotate the video. It simply determines whether the video is tall or wide.

Specifying the Video Aspect

/// <summary>
/// Video aspect mode.
/// </summary>
AspectMode aspect { get; set; }

The aspect is used to modify the video resolution to have a desired aspect ratio. The following aspect modes are supported:

/// <summary>
/// Video aspect mode.
/// </summary>
enum AspectMode {
    /// <summary>
    /// Use the recording resolution aspect ratio.
    /// </summary>
    Resolution = 0,
    /// <summary>
    /// Match the screen aspect ratio by adjusting the video width.
    /// </summary>
    MatchScreenAdjustWidth = 1,
    /// <summary>
    /// Match the screen aspect ratio by adjusting the video height.
    /// </summary>
    MatchScreenAdjustHeight = 2,
}

The aspect can be used to ensure that the recording aspect ratio matches the screen aspect ratio. This is useful when recording in augmented reality apps.

The aspect property only has an effect when the orientation is set to OrientationMode.MatchScreen.

Specifying the Recording Cameras

/// <summary>
/// Game cameras to record.
/// </summary>
Camera[] cameras { get; set; }

The cameras property holds an array of game cameras to record in a given recording session.

The cameras are only used when the video mode is set to VideoMode.Camera.

Specifying the Recording Texture

/// <summary>
/// Texture to record.
/// </summary>
Texture texture { get; set; }

The texture property is used to record video frames from a Texture.

The texture is only used when the videoMode is set to VideoMode.Texture.

Specifying the Recording Camera Manager

/// <summary>
/// Camera manager for recording video frames from a camera device.
/// </summary>
VideoKitCameraManager cameraManager { get; set; }

The cameraManager property is used to record video frames from a CameraDevice.

The cameraManager is only used when the videoMode is set to VideoMode.CameraDevice.

Audio Settings

The audio settings are used to configure the audio stream of recordings.

These settings only have an effect when the format supports recording audio frames, and when the audioMode is not VideoMode.None.

Specifying the Recording Microphone

/// <summary>
/// Audio device to record from when using `AudioMode.Microphone`.
/// </summary>
AudioDevice audioDevice { get; set; }

The audioDevice is used to stream microphone audio that will then be recorded.

The audioDevice is only used when the audio mode has the AudioMode.Microphone flag set.

See the NatDevice documentation for more information on working with audio devices.

Checking the Recording State

/// <summary>
/// Whether a recording is currently in progress.
/// </summary>
bool recording { get; }

The recording property reports whether a recording is currently in progress.

Starting a Recording Session

/// <summary>
/// Start recording.
/// </summary>
void StartRecording ();

A recording session is started by calling the StartRecording method. This method can be invoked directly from UI elements:

Recorders can only record one video at a time. So calling this method when running is true will result in an error.

Stopping a Recording Session

/// <summary>
/// Stop recording.
/// </summary>
void StopRecording ();

A recording session is stopped by calling the StopRecording method.

Similar to the StartRecording method, this method can be invoked directly from UI elements.

When the recorder destination is set to Documents, the videos are saved to the VideoKit folder in the app's private documents directory.

Calling StopRecording when recording is false will log a warning and silently return.

Handling a Recording Session

/// <summary>
/// Event raised when a recording session is completed.
/// </summary>
UnityEvent<MediaAsset> OnRecordingCompleted { get; set; }

The OnRecordingCompleted event is raised when a recording session is completed. A completed session could either result in a successful recording or a failure. Refer to the MediaAsset class for more information.

Last updated