ol.trixnity.media

Generic media upload and download helpers built on top of Trixnity’s media service.

Uploads happen in two steps:

  • prepare-upload stages local bytes in Trixnity’s media store and returns a prepared upload map containing an upload://…​ cache URI

  • upload uploads either a prepared upload map or a local path-like source and returns a handle exposing upload progress plus the final uploaded media

  • get-media, get-encrypted-media, and get-thumbnail download media as normalized handle maps carrying a JVM InputStream

Download selection follows the normalized event data:

  • use get-media for plain ::mx/url attachment references

  • use get-encrypted-media for ::mx/encrypted-file or ::mx/thumbnail-encrypted-file

  • use get-media or get-encrypted-media for event-provided thumbnail references already present on the event

  • use get-thumbnail only when asking the homeserver to generate a new thumbnail for an MXC URI at explicit dimensions

  • use temporary-file only when a filesystem path is required for an existing media handle

The public shapes here stay normalized as namespaced keyword maps so callers do not need to work with Kotlin media APIs directly.

Resolved download handles all share the same shape:

{::mx/input-stream <java.io.InputStream>
 ::mx/raw          <opaque upstream platform media>}

::mx/input-stream is the supported happy path. ::mx/raw exists only so temporary-file can compose on top of an already fetched handle.

→TemporaryMediaFile

(->TemporaryMediaFile path raw)

source

TemporaryMediaFile

source

map→TemporaryMediaFile

(map->TemporaryMediaFile m)

source

prepare-upload

(prepare-upload client source)
(prepare-upload client source opts)

Stages a local media source in Trixnity’s media store and returns a Missionary task of a prepared upload map.

source may be a string path, java.io.File, or java.nio.file.Path.

Supported opts:

key description

::mx/file-name

Optional logical file name stored in the returned metadata

::mx/mime-type

Optional MIME type forwarded to upstream media upload preparation

source

upload

(upload client source)
(upload client source opts)

Uploads a prepared upload map or local media source and returns a handle map.

When source is path-like, this first stages the file through prepare-upload and then uploads the resulting cache URI.

Return value:

  • ::mx/result is a Missionary task that resolves to the uploaded media map

  • ::mx/progress is a Missionary flow of normalized progress snapshots with ::mx/transferred and optional ::mx/total

This intentionally replaces the previous task-only return contract so one upload call can drive both progress observation and the final upload result from the same underlying operation.

Supported opts:

| key | description |-----|------------- | ::mx/file-name | Optional logical file name when source is path-like | | ::mx/mime-type | Optional MIME type when source is path-like | | ::mx/keep-in-cache | Keep the staged media in the local cache after upload, defaults to true |

source

get-media

(get-media client uri)

Downloads plain media identified by uri.

Returns a Missionary task of a normalized media handle:

  • ::mx/input-stream, the primary public readable stream

  • ::mx/raw, an opaque upstream media value used only for composition with temporary-file

uri should be an MXC URI such as mxc://example.org/abc.

Use this for event fields that already carry a plain media reference, such as ::mx/url or ::mx/thumbnail-url.

Example:

(m/sp
  (let [handle (m/? (get-media client (::mx/url ev)))]
    (slurp (::mx/input-stream handle))))

source

get-encrypted-media

(get-encrypted-media client encrypted-file)

Downloads encrypted media from normalized encrypted-file metadata.

encrypted-file must be the normalized encrypted-file map exposed on events under ::mx/encrypted-file or ::mx/thumbnail-encrypted-file.

Returns the same normalized media-handle shape as get-media, with ::mx/input-stream as the public happy path and ::mx/raw kept opaque for temporary-file composition.

Example:

(m/sp
  (let [handle (m/? (get-encrypted-media client
                                         (::mx/encrypted-file ev)))]
    (slurp (::mx/input-stream handle))))

source

get-thumbnail

(get-thumbnail client uri width height)
(get-thumbnail client uri width height opts)

Downloads a homeserver-generated thumbnail for uri.

This mirrors upstream Trixnity getThumbnail: it asks the homeserver to generate a thumbnail for an MXC URI using explicit dimensions. It does not read event-provided thumbnail references already present on an event. For those, use get-media or get-encrypted-media with ::mx/thumbnail-url or ::mx/thumbnail-encrypted-file.

Returns the same normalized media-handle shape as get-media.

Supported opts:

| key | description |-----|------------- | ::mx/method | Thumbnail resize method, either :crop or :scale | | ::mx/animated | Request animated thumbnails when upstream supports them |

Example:

(m/sp
  (let [handle (m/? (get-thumbnail client
                                    (::mx/url ev)
                                    320
                                    200
                                    {::mx/method :scale}))]
    (slurp (::mx/input-stream handle))))

source

temporary-file

(temporary-file media)

Creates a temporary file from media.

media may be either a resolved media handle or a media-handle task returned by get-media, get-encrypted-media, or get-thumbnail.

Returns a Missionary task of a closeable TemporaryMediaFile record. The record exposes :path directly as a slurpable string path and should usually be used with with-open.

Treat ::mx/raw on media handles as opaque; it exists only so this helper can compose with already-fetched media.

This is an opt-in JVM convenience for integrations that need a filesystem path. If the underlying media handle cannot produce a temporary file, the task fails with an exception from the bridge layer.

Example:

(m/sp
  (with-open [tmp (m/? (temporary-file
                        (get-media client (::mx/url ev))))]
    (slurp (:path tmp))))

source