Created mediatype-handlers page

Opening-or-streaming-non-text-files.md

@@ -0,0 +1,102 @@
+The following page only applies to Amfora v1.8.0 and onward, which hasn't been released yet. If you'd like to try this out early, you can follow the [From Source instructions](https://github.com/makeworld-the-better-one/amfora#from-source) on the README and install an in-progress version of Amfora.
+
+---
+
+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:
+```toml
+# [[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](https://en.wikipedia.org/wiki/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 media type, 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](https://www.videolan.org/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.