7. Files and images#

In this chapter you move files between your devices and a session, and show pictures right in the terminal.

Drop files onto a pane (desktop)#

Drag files from your file manager onto a pane. mpmux types their paths into the pane, quoted for the shell. Nothing is copied; the program in the pane gets the paths, for example as an argument or as a file for an agent to read.

Upload and download (tablet and phone)#

On Android, a hosted session can receive files from the device and send files back.

Upload is handy for agents: take a screenshot on the tablet, upload it, and the agent gets the path.

Hand a file to another device by short code#

To pass a file to another device, use a short code. The transfer is end-to-end encrypted; the relay only forwards the encrypted bytes.

1. On the sending device, choose Send File by Short Code in the command palette and pick a file. mpmux shows a short code.
2. On the receiving device, choose Receive File by Short Code, enter the code, and choose where to save the file.

Both entries are on Android today. A desktop command line for the same transfer exists but is still experimental; see short-code exchange.

Images in the terminal#

mpmux supports the Kitty graphics protocol. Programs that speak it draw real pictures in the terminal: plots, screenshots, previews. For example:

chafa --format kitty picture.png

Images also work in hosted sessions and on the tablet.

kitten icat picture.png works as well.

▶ watch the clip

The Viewer: images, tables and documents beside the terminal#

A picture in the terminal scrolls away with the output. For a chart you want to keep looking at, a table, or a document, use the Viewer, a panel beside the terminal:

mpmux-cli media demo                 # sample chart, table, document and page
mpmux-cli media show chart.png
mpmux-cli media show results.csv --title "Test results"
mpmux-cli media show ./scene/        # scene/index.html with scene's other files
mpmux-cli media show https://example.org

show prints a link such as mpmux-media://chart.png, and in an mpmux terminal it draws a PNG as a small thumbnail above the link. Click or tap the link or the thumbnail to bring the object back (--thumbnail never leaves the thumbnail out, --thumbnail-rows sizes it). Showing a file again replaces it in the Viewer, so a script that redraws its chart updates it in place.

The dock menu's Viewer entry and the command palette's Show Viewer open the panel. Its buttons step through the objects and close them; with the panel focused, ← and → step too, and Ctrl + / Ctrl − (or a pinch on a phone or tablet) scale its text and zoom its pages, like the terminal's. Open shows a page in the browser of the device you are looking at; on the desktop it hands other objects to the system's program for them.

Double-click (or double-tap) a picture, document or table to give it the whole window: the terminal and a split dock's second panel fold away until you double-click again. When something brought the Viewer up for you (a todo's Show in the Viewer, a chart from an agent), closing that object (✕) returns the dock to what it showed before.

▶ c29-viewer, c33-viewer-return

Pages#

On a tablet or phone the Viewer shows an HTML page itself, interactive, in the system's web view. On the Linux desktop it does so once the web engine is installed: Install web engine (over a page's source, or Install Web Engine in the command palette) downloads Chromium (CEF, about 320 MB, about 570 MB on disk) to ~/.local/share/mpmux/web-engine, once, with a progress bar in the Viewer, and pages show without a restart. Elsewhere the Viewer shows the page's source.

Right-click a page on the desktop for its menu: Copy, Paste, Select All, a link's Open in Browser and Copy Link Address, Back, Forward, Reload, zoom, Copy Page Address (Copy mpmux Link for a page mpmux serves, whose own address only works while the app runs), View Source, Open in Browser, and Show Console, which lists what the page logged (its errors, say) under it. mpmux-cli media console prints the same for an agent that made the page.

Browsing#

To browse, use the palette's Open Web Page (or mpmux-cli media show https://example.org) and type an address above the page; Enter loads it, and the field follows the links you follow.

Documents with links#

A link in a Markdown document opens where it points:

• a file next to the document shows in the document's place: an image, another document, a page, or a Wasm guest, which runs. Back (or Backspace) returns.
• a web address opens as a web link in the Viewer, and a media link (mpmux-media://chart.png) its object.

mpmux-cli media show sends the files a Markdown or HTML document links to along with it: those in its folder or below, and what linked documents link to, at most 64 files and 24 MB together. It names the links it cannot carry. A page in the Viewer that links to a Wasm guest or a Markdown file it carries opens it the same way.

Agents and hosted sessions#

Agents can use the Viewer too: an agent in a hosted session on a server that runs mpmux-cli media show shows its chart on your tablet. In a hosted session the session host keeps the objects: they are still there after the app restarts, and the tablet shows what was shown while only the laptop was attached, or nothing was. Closing an object removes it from the session.

Each object can be at most 8 MB (640 KB from standard input, or when mpmux-cli talks to mpmux over TCP). mpmux-cli media list, close and clear manage them.

Next#

Chapter 8 shows how to reach a session host on another machine.