Skip to main content
The Osmium Chat Protocol distinguishes between two separate concepts for handling media:

​
File vs Media

​
File

A File is raw data uploaded to the server, devoid of context, usage, or metadata about how it’s being used. Files are identified by a snowflake ID and stored in specific regions.

​
Media

A Media object is the backing type for attachments in messages. It contains:
  • A reference to a File
  • Additional metadata (dimensions, duration, etc.)
  • Context about how the file is being used

​
Core Types

​
File Structure

message File {
  fixed64 file_id = 1;        // @snowflake<File>
  uint32 region = 2;
  uint64 size = 3;
  string mimetype = 4;
  optional string filename = 5;
  FileMetadata metadata = 6;
}
​
file_id
fixed64
Snowflake identifier for the file
​
region
uint32
Storage region where the file is located
​
size
uint64
File size in bytes
​
mimetype
string
MIME type of the file (e.g., image/png, video/mp4)
​
filename
string
Original filename
​
metadata
FileMetadata
Type-specific metadata (see below)

​
FileMetadata Variants

The FileMetadata message contains different metadata based on file type:

​
Image Metadata

message MetadataImage {
  uint32 width = 1;
  uint32 height = 2;
  optional bytes preview = 3;
}
​
width
uint32
Image width in pixels
​
height
uint32
Image height in pixels
​
preview
bytes
Low-resolution preview data for fast loading

​
Video Metadata

message MetadataVideo {
  uint32 width = 1;
  uint32 height = 2;
  uint32 duration = 3;  // in seconds
}
​
width
uint32
Video width in pixels
​
height
uint32
Video height in pixels
​
duration
uint32
Video duration in seconds

​
Audio Metadata

message MetadataAudio {
  uint32 duration = 1;  // in seconds
}
​
duration
uint32
Audio duration in seconds

​
Custom Emoji Metadata

message MetadataCustomEmoji {
  uint32 width = 1;
  uint32 height = 2;
  string emoji = 3;
  refs.StickerPackRef pack = 4;
}
​
width
uint32
Emoji image width in pixels
​
height
uint32
Emoji image height in pixels
​
emoji
string
The emoji character this represents
​
pack
StickerPackRef
Reference to the sticker pack containing this emoji

​
Message Media Types

When attaching media to messages, use the MessageMedia type: 
message MessageMedia {
  oneof media {
    MediaFile file = 1;
    MediaEmbed embed = 2;
  }
}
  • MediaFile: A file attachment with metadata
  • MediaEmbed: A URL embed with preview data
See the Embeds section for more information on URL embeds.

Build docs developers (and LLMs) love

Get started for freeTalk to us