MediaAsset

View Source Code

namespace VideoKit {
    /// <summary>
    /// Video, audio, or other media file.
    /// </summary>
    class MediaAsset { ... }
}

The MediaAsset refers to a media file on the file system.

Creating a Media Asset

Media assets can be created in a variety of ways:

From a File

/// <summary>
/// Create a media aseet from a file.
/// </summary>
/// <param name="path">Path to media file.</param>
/// <returns>Media asset.</returns>
static Task<MediaAsset> FromFile (string path);

Media assets can be created from a file on the local file system using the file path.

From a Texture

/// <summary>
/// Create a media aseet from a texture.
/// </summary>
/// <param name="texture">Texture.</param>
/// <returns>Image asset.</returns>
static Task<MediaAsset> FromTexture (Texture2D texture);

Media assets can be created from Texture2D instances.

You must ensure that the texture.isReadable.

To ensure that the created MediaAsset has a valid path, the texture is encoded to PNG and written to a temporary file.

From an Audio Clip

/// <summary>
/// Create a media aseet from an audio clip.    
/// NOTE: This requires an active VideoKit plan.
/// </summary>
/// <param name="clip">Audio clip.</param>
/// <param name="format">Media format used to encode the audio.</param>
/// <returns>Audio asset.</returns>
static Task<MediaAsset> FromAudioClip (
    AudioClip clip,
    MediaRecorder.Format format = MediaRecorder.Format.WAV
);

Media assets can be created from AudioClip instances. To ensure that the created MediaAsset has a valid path, the clip is encoded to an audio file using the MediaRecorder class.

Because input audio clips are recorded to files, this function requires an active VideoKit Core plan.

From Plain Text

/// <summary>
/// Create a media aseet from plain text.
/// </summary>
/// <param name="text">Text.</param>
/// <returns>Text asset.</returns>
static Task<MediaAsset> FromText (string text);

Media assets can be created from plain text. To ensure that the created MediaAsset has a valid path, the text is written to a temporary file.

From the Camera Roll

/// <summary>
/// Create a media asset by prompting the user to select an image or video from the camera roll.
/// NOTE: This requires iOS 14+.
/// </summary>
/// <param name="type">Desired asset type.</param>
/// <returns>Media asset.</returns>
static Task<MediaAsset?> FromCameraRoll (MediaType type);

Media assets can be created by prompting the user to pick an image or video from the camera roll.

From Streaming Assets

/// <summary>
/// Create a media asset from a file in `StreamingAssets`.
/// </summary>
/// <param name="path">Relative file path in `StreamingAssets`.</param>
/// <returns>Media asset.</returns>
static Task<MediaAsset?> FromStreamingAssets (string path);

Media assets can be created by loading from Streaming Assets.

Inspecting the Asset

When media assets are created, their corresponded metadata is populated. Below are properties that are available for use:

Inspecting the Type

/// <summary>
/// Get the asset media type.
/// </summary>
MediaType type { get; }

Media assets have a media type.

/// <summary>
/// Media type.
/// </summary>
enum MediaType : int {
    /// <summary>
    /// Unknown or unsupported media type.
    /// </summary>
    Unknown   = 0,
    /// <summary>
    /// Image.
    /// </summary>
    Image     = 1,
    /// <summary>
    /// Audio.
    /// </summary>
    Audio     = 2,
    /// <summary>
    /// Video.
    /// </summary>
    Video     = 3,
    /// <summary>
    /// Text.
    /// </summary>
    Text      = 4,
    /// <summary>
    /// Sequence.
    /// </summary>
    Sequence  = 5,
}

Inspecting the Path

/// <summary>
/// Path to media asset.
/// </summary>
string? path { get; }

Media assets expose the path to the underlying media file that they represent.

The path is null for MediaType.Sequence assets.

On WebGL, the path is usually exposed as a data: URL referring to blob memory in the browser tab.

Inspecting the Image Width

/// <summary>
/// Image or video width.
/// </summary>
int width { get; }

For image and video assets, the width property provides the asset width in pixels.

The width is only populated for MediaType.Image and MediaType.Video assets.

Inspecting the Image Height

/// <summary>
/// Image or video height.
/// </summary>
int height { get; }

For image and video assets, the height property provides the asset height in pixels.

The height is only populated for MediaType.Image and MediaType.Video assets.

Inspecting the Video Frame Rate

/// <summary>
/// Video frame rate.
/// </summary>
float frameRate { get; }

For video assets, the frameRate property provides the asset frame rate.

The frameRate is only populated for MediaType.Video assets.

Inspecting the Audio Sample Rate

/// <summary>
/// Audio sample rate.
/// </summary>
int sampleRate { get; }

For video and audio assets, the sampleRate property provides the asset's audio sample rate.

The sampleRate is only populated for MediaType.Video and MediaType.Audio assets.

Inspecting the Audio Channel Count

/// <summary>
/// Audio channel count.
/// </summary>
int channelCount { get; }

For video and audio assets, the channelCount property provides the asset's audio channel count.

The channelCount is only populated for MediaType.Video and MediaType.Audio assets.

Inspecting the Media Duration

/// <summary>
/// Video or audio duration in seconds.
/// </summary>
float duration { get; }

For video and audio assets, the duration property provides the asset's duration in seconds.

The duration is only populated for MediaType.Video and MediaType.Audio assets.

Inspecting Sub-Assets

/// <summary>
/// Media assets contained within this asset.
/// </summary>
IReadOnlyList<MediaAsset> assets { get; }

For sequence assets, the assets property provides the assets contained in the sequence.

The assets are only populated for MediaType.Sequence assets.

Reading the Asset

Media assets support reading contained data, allowing for decoding and other functionality.

Reading Sample Buffers

/// <summary>
/// Read sample buffers in the media asset.
/// </summary>
/// <returns>Sample buffers in the media asset.</returns>
IEnumerable<T> Read<T> () where T : AudioBuffer | PixelBuffer;

Video and audio assets can be decoded in a loop to extract pixel and audio buffers:

// Create asset
MediaAsset asset = ...
// Read video frames
foreach (PixelBuffer pixelBuffer in asset.Read<PixelBuffer>()) {
    // Do stuff
    ...
}

Media assets can be shared, providing a critical foundation for building virality in your application.

Sharing the Asset

/// <summary>
/// Share the media asset using the native sharing UI.
/// </summary>
/// <param name="message">Optional message to share with the media asset.</param>
/// <returns>Receiving app bundle ID or `null` if the user did not complete the share action.</returns>
Task<string?> Share (string? message = null);

Media assets can be shared with the native share sheet UI.

This method will return null if the user cancels the sharing interaction.

The message shared with the asset is not guaranteed to be used by the receiving application.

Saving to the Camera Roll

/// <summary>
/// Save the media asset to the camera roll.
/// </summary>
/// <param name="album">Optional album to save media asset to.</param>
/// <returns>Whether the asset was successfully saved to the camera roll.</returns>
Task<bool> SaveToCameraRoll (string? album = null);

Media assets can be saved to the user's camera roll.

Converting the Asset

Media assets can be converted to underlying texture and audio types for use within Unity Engine:

Converting to Texture

/// <summary>
/// Create a texture from the media asset.
/// This can only be used on image and video assets.
/// </summary>
/// <param name="time">Time to extract the texture from. This is only supported for video assets.</param>
/// <returns>Texture.</returns>
Task<Texture2D> ToTexture (float time = 0f);

Image assets can be converted to Texture2D instances.

Converting to an Audio Clip

/// <summary>
/// Create an audio clip from the media asset.
/// </summary>
/// <returns>Audio clip.</returns>
Task<AudioClip> ToAudioClip ();

Image assets can be converted to AudioClip instances.

This method only works if the underlying media file is a *.wav waveform audio file.