Table of Contents
Make sure that you've read the configuration wiki page first.
By default, when clicking a non-text file, Amfora will present you with options to either Open or Download the file. If you choose Open, Amfora will download the file to a temporary folder, and then open it using your OS's default application for that file type.
You can configure what applications Amfora uses if you want to override this behaviour. You can also configure whether streaming is used, which is explained more below.
From the default config file:
# [[mediatype-handlers]] section
# ---------------------------------
#
# Specify what applications will open certain media types.
# By default your default application will be used to open the file when you select "Open".
# You only need to configure this section if you want to override your default application,
# or do special things like streaming.
#
# Note the use of single quotes for commands, so that backslashes will not be escaped.
#
#
# To open jpeg files with the feh command:
#
# [[mediatype-handlers]]
# cmd = ['feh']
# types = ["image/jpeg"]
#
# Each command that you specify must come under its own [[mediatype-handlers]]. You may
# specify as many [[mediatype-handlers]] as you want to setup multiple commands.
#
# If the subtype is omitted then the specified command will be used for the
# entire type:
#
# [[mediatype-handlers]]
# command = ['vlc', '--flag']
# types = ["audio", "video"]
#
# A catch-all handler can by specified with "*".
# Note that there are already catch-all handlers in place for all OSes,
# that open the file using your default application. This is only if you
# want to override that.
#
# [[mediatype-handlers]]
# cmd = ['some-command']
# types = [
# "application/pdf",
# "*",
# ]
#
# You can also choose to stream the data instead of downloading it all before
# opening it. This is especially useful for large video or audio files, as
# well as radio streams, which will never complete. You can do this like so:
#
# [[mediatype-handlers]]
# cmd = ['vlc', '-']
# types = ["audio", "video"]
# stream = true
#
# This uses vlc to stream all video and audio content.
# By default stream is set to off for all handlers
#
#
# If you want to always open a type in its viewer without the download or open
# prompt appearing, you can add no_prompt = true
#
# [[mediatype-handlers]]
# cmd = ['feh']
# types = ["image"]
# no_prompt = true
#
# Note: Multiple handlers cannot be defined for the same full media type, but
# still there needs to be an order for which handlers are used. The following
# order applies regardless of the order written in the config:
#
# 1. Full media type: "image/jpeg"
# 2. Just type: "image"
# 3. Catch-all: "*"
What even are media types?
You'll notice this config mentions "media type" or "mediatypes" a lot. A media type is a type of identifier for file formats that are sent over the Internet. It's way for computers to know what kind of files are being sent. For example on your hard drive a file might end with .jpg, which tells you and the computer that it's a JPEG file. Over the Web and Gemini, that file would be sent along with a media type of image/jpeg, which tells the computer the same thing, that it's a JPEG file.
You'll notice that media types have two parts, separated by a slash. These are called the type and subtype. In Amfora's config, you can configure applications to only open a specific subtype, like image/jpeg, or a whole type, like image.
Streaming
The config also explains that you can stream data by setting stream = true. This means that instead of downloading the whole file into a temporary folder then opening it, it will just feed the application the data as it's being downloaded, and never save it anywhere. As the config mentions, the is especially useful for large audio and video files, and audio/video streams.
Note that most applications will not work with streaming, for example you might not be able to open a PDF that way. You might also need a slightly different command to stream files. Like in the config example, you can't just use ['vlc'], it has to be ['vlc', '-'] to tell VLC to use the streamed data.
Technical details
Default application
On Linux or *BSD systems the default opening application used is xdg-open. Most OSes/distros should have a package called xdg-utils to install this if necessary, although most should already have it installed. On macOS open is used, and on Windows rundll32 url.dll,FileProtocolHandler is.
Opening command
For non-stream opening of files, the provided command is run, with the downloaded file path appended as the final argument.
For streams, no path is appended, and instead the downloaded data is "piped" to stdin. You must configure your command so it reads from stdin. Some software does this by default if no path is specified, although must GUI apps don't. Often the convention of using - as a path will work. If you're on a non-Windows system you could also try using /dev/stdin as the path.
If you'd like to support Amfora development, you can sponsor me through Ko-Fi or Github Sponsors. Feel free to submit a PR as well! Thanks.