Media API

syntax = "proto3";

/**
 * How media works
 *
 * There are two distinct and separate types:
 * a) a File, which is a file that is uploaded to the server, devoid of context,
 * usage, or metadata.
 * b) Media, the backing type for attachments in messages,
 * which may contain a reference to a File, along with additional metadata.
 *
 */
package tangle.client.media;

import "refs.proto";

// media.uploadFilePart -> ()
message UploadFilePart {
  // The identifier of the uploaded file. Generated by the client.
  uint64 upload_id = 1;
  uint32 part = 2;
  bytes data = 3;
}

// media.downloadFilePart -> media.FilePart
message DownloadFilePart {
  FileRef file_ref = 1;
  uint64 offset = 2;
  uint32 length = 3;
}

message FilePart { bytes data = 3; }

message FileRef {
  message MediaFileRef {
    // @snowflake<File>
    fixed64 file_id = 1;
  }
  message ChatPhotoFileRef {
    // @snowflake<File>
    fixed64 file_id = 1;
  }

  oneof ref {
    MediaFileRef media_file = 1;
    ChatPhotoFileRef chat_photo = 2;
  }
}

message UploadedFileRef {
  fixed64 id = 1;
  string name = 2;
  uint32 part_count = 3;
}

message MediaRef {
  oneof ref {
    MediaRefUploadedFile uploaded = 1;
    MediaRefEmbed embed = 2;
  }
}

message MediaRefUploadedFile {
  UploadedFileRef file = 1;
  optional string filename = 2;
  string mimetype = 3;
  FileMetadata metadata = 4;
}

message MediaRefEmbed {
  string url = 1;
}

// File metadata, used to store information about the file, included with media.
message FileMetadata {
  message MetadataImage {
    uint32 width = 1;
    uint32 height = 2;
    optional bytes preview = 3;
  }
  message MetadataVideo {
    uint32 width = 1;
    uint32 height = 2;
    uint32 duration = 3; // in seconds
  }
  message MetadataAudio {
    uint32 duration = 1; // in seconds
  }
  message MetadataFile {}
  message MetadataCustomEmoji {
    uint32 width = 1;
    uint32 height = 2;
    string emoji = 3;
    refs.StickerPackRef pack = 4;
  }

  oneof metadata {
    MetadataImage image = 1;
    MetadataVideo video = 2;
    MetadataAudio audio = 3;
    MetadataFile file = 4;
    MetadataCustomEmoji custom_emoji = 5;
  }
}

message File {
  // @snowflake<File>
  fixed64 file_id = 1;
  uint32 region = 2;
  uint64 size = 3;
  string mimetype = 4;
  optional string filename = 5;
  FileMetadata metadata = 6;
}

message Files {
  repeated File files = 1;
}

message MediaFile {
  File file = 1;
  // TODO: spoiler, etc
}

message MediaEmbed {
  string url = 1;
  optional string title = 2;
  optional string description = 3;
  // TODO: spoiler, etc
}

// Media in messages
message MessageMedia {
  oneof media {
    MediaFile file = 1;
    MediaEmbed embed = 2;
  }
}