# Media

Matrix media (images, files, thumbnails) moves as raw bytes, not JSON. `Client` routes those transfers through a dedicated `MediaClient` so binary bodies never pass through JSON encoding. You reach it two ways — directly via `client.media`, or implicitly through the [API chain](/async-matrix/client/#the-api-chain), which detects binary routes and dispatches them to the media client automatically.

## Uploading

```ruby
bytes = File.binread("cat.png")
mxc   = client.media.upload(:post, upload_path, bytes, "image/png")
```

`upload(method, path, body, content_type = "application/octet-stream")` sends the bytes with an explicit content type and returns the homeserver's response (the `mxc://` URI you then reference in a message event). Pass the correct content type — it's what clients use to render the file.

## Downloading

```ruby
data = client.media.download(download_path)
```

`download(path)` streams the body back with the same **size-limit enforcement** the JSON client applies, so a hostile or misconfigured homeserver can't make you buffer an unbounded response — an oversized body is cut off mid-stream rather than read whole.

## Version rewriting

The Matrix media endpoints moved across spec versions. When you build a media path through the API chain at `/v3`, async-matrix rewrites it to `/v1` where the spec requires, so you can chain naturally without tracking which media route lives at which version.

## Config

Two config sections govern media behavior at the bridge level (see [Configuration](/async-matrix/configuration/)):

- **`direct_media`** — serve media straight from the remote network rather than reuploading to your homeserver.
- **`public_media`** — expose media over a public, unauthenticated URL.

## Lifecycle

`MediaClient` uses the same fiber-safe, pooled `Async::HTTP::Internet` as the JSON client. Share it (via `client.media`) rather than constructing per transfer.

Media

Matrix media (images, files, thumbnails) moves as raw bytes, not JSON. Client routes those transfers through a dedicated MediaClient so binary bodies never pass through JSON encoding. You reach it two ways — directly via client.media, or implicitly through the API chain, which detects binary routes and dispatches them to the media client automatically.

Uploading

bytes = File.binread("cat.png")
mxc   = client.media.upload(:post, upload_path, bytes, "image/png")

upload(method, path, body, content_type = "application/octet-stream") sends the bytes with an explicit content type and returns the homeserver’s response (the mxc:// URI you then reference in a message event). Pass the correct content type — it’s what clients use to render the file.

Downloading

data = client.media.download(download_path)

download(path) streams the body back with the same size-limit enforcement the JSON client applies, so a hostile or misconfigured homeserver can’t make you buffer an unbounded response — an oversized body is cut off mid-stream rather than read whole.

Version rewriting

The Matrix media endpoints moved across spec versions. When you build a media path through the API chain at /v3, async-matrix rewrites it to /v1 where the spec requires, so you can chain naturally without tracking which media route lives at which version.

Config

Two config sections govern media behavior at the bridge level (see Configuration):

direct_media — serve media straight from the remote network rather than reuploading to your homeserver.
public_media — expose media over a public, unauthenticated URL.

Lifecycle

MediaClient uses the same fiber-safe, pooled Async::HTTP::Internet as the JSON client. Share it (via client.media) rather than constructing per transfer.