MediaAsset

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

/// <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);

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

/// <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 async Task<MediaAsset> FromAudioClip (
  AudioClip clip,
  MediaRecorder.Format format = MediaRecorder.Format.WAV
);

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

/// <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);

/// <summary>
/// Create a media asset by performing text-to-speech on the provided text prompt.
/// </summary>
/// <param name="prompt">Text to synthesize speech from.</param>
/// <param name="voice">Voice to use for generation. See https://videokit.ai/reference/mediaasset for more information.</param>
/// <returns>Generated audio asset.</returns>
static Task<MediaAsset> FromSpeechPrompt (
    string prompt,
    NarrationVoice voice = 0
);

/// <summary>
/// Audio narration voice.
/// </summary>
enum NarrationVoice : int {
  /// <summary>
  /// Default narration voice.
  /// </summary>
  Default = 0,
  /// <summary>
  /// Male 1 narration voice.
  /// </summary>
  Kevin = 1,
  /// <summary>
  /// Male 2 narration voice.
  /// </summary>
  Arjun = 2,
  /// <summary>
  /// Male 3 narration voice.
  /// </summary>
  Dami = 3,
  /// <summary>
  /// Male 4 narration voice.
  /// </summary>
  Juan = 4,
  /// <summary>
  /// Female 1 narration voice.
  /// </summary>
  Rhea = 5,
  /// <summary>
  /// Female 2 narration voice.
  /// </summary>
  Aliyah = 6,
  /// <summary>
  /// Female 3 narration voice.
  /// </summary>
  Kristen = 7,
  /// <summary>
  /// Female 4 narration voice.
  /// </summary>
  Salma = 8,
}

/// <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 async Task<MediaAsset?> FromStreamingAssets (string path);

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

/// <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,
}

/// <summary>
/// Path to media asset.
/// This is `null` for sequence assets.
/// </summary>
string? path { get; }

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

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

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

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

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

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

/// <summary>
/// Media assets contained within this asset.
/// This is only populated for `Sequence` assets.
/// </summary>
IReadOnlyList<MediaAsset> assets { get; }

/// <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;

/// <summary>
/// Caption the audio asset by performing speech-to-text.
/// </summary>
Task<string> Caption ();

/// <summary>
/// Caption the media asset into a structure.
/// </summary>
/// <typeparam name="T">Structure to parse into.</typeparam>
/// <returns>Parsed structure.</returns>
Task<T> Caption<T> ();

/// <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);

/// <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);

/// <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);

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