Preview plugins
A preview plugin is a small separately installed program that lets tessoa preview formats its built-in preview cannot handle, such as video, audio and multipage documents. This page covers finding and installing plugins, playback, page navigation and preview failures.
Plugin previews are a Supporter-tier paid feature: managing, installing and uninstalling work at any tier, but installed plugins only start producing images once you unlock.
How plugins run on your machine
Every plugin is a separate process. tessoa starts it only when a frame has to be decoded or a video played, and it exits on its own once idle. A plugin that crashes or hangs never affects tessoa itself: that one file falls back to an icon and everything else carries on.
The line on the plugin page says exactly this: Plugins run in separate processes; a crash or hang never affects tessoa itself. Enabling, disabling and uninstalling take effect immediately, no restart needed.
An installed package is unpacked into your user folder, and it does not roam with your settings:
| System | Location |
|---|---|
| Windows | %LOCALAPPDATA%\tessoa\plugins\<plugin id>\ |
| macOS | ~/Library/Application Support/tessoa/plugins/ |
| Linux | $XDG_DATA_HOME/tessoa/plugins/ |
Opening the plugin page
Two entry points lead to the same page:
- Click the menu button in the top-left corner of the window and choose Plugins.
- Open Settings and click Preview plugins in the Maintenance group.
The Maintenance group holds two more switches, and they govern two different things:
| Setting | What it does |
|---|---|
| Enable preview plugins | Whether plugins are loaded at all. With this off, installed plugins do nothing and everything behaves as if none were installed |
| Suggest installable preview plugins | Whether preview mentions a plugin when you open a format that needs one |
Installing from the plugin source
The lower half of the plugin page is the Available plugins section, listing what is available for this machine. The button at the end of a row has five states:
| Button | What it means |
|---|---|
| Install | Not installed yet; click to start downloading |
| Update | An older version is installed, and the sub-line reads version x.y.z available |
| Installed | Already on the newest version; not clickable |
| A percentage | Downloading and installing, counting up to 100% |
| Needs newer host | This plugin wants a newer tessoa, and the sub-line reads requires tessoa x.y.z or newer |
To install:
- Open the plugin page and wait for Fetching the plugin list… to turn into entries.
- Click Install on the row you want.
- The first time you install a plugin, the Preview Plugin Terms come up first; read them and click Agree & Continue. Choosing Not now returns you to the plugin page with nothing installed.
- The percentage on the button runs out, and the row appears in the Installed plugins section above.
An interrupted download resumes where it stopped the next time you click Install; it does not start over.
tessoa never checks for plugin updates in the background. The list is fetched the moment you open the plugin page or click Rescan, and at no other time. That single Rescan button does two things at once: it rescans the plugins installed on this machine and re-fetches the plugin source.
Installing from a file
When you have a .zip plugin package in hand:
- Click Install from file… in the top-right corner of the plugin page.
- Pick the
.zipfile in the Choose a Plugin Package dialog and click Install. - A toast reads Installed plugin …, and the row appears on the plugin page.
Installing a newer version of a plugin you already have does not require uninstalling the old one first.
When installing fails, the toast says why:
| Message | What it means |
|---|---|
| Not a plugin package (no plugin.toml at the archive root) | The wrong file was picked |
| The plugin manifest (plugin.toml) is invalid | The package's description file cannot be read |
| Extraction failed — the package may be corrupted | The download is incomplete, or the file is damaged |
| Couldn't replace the old version (files may be in use) — try again later | The old version's files are still held open; try again shortly |
| The package failed its checksum (corrupted in transit, or tampered with) — installation aborted | A package from the plugin source does not match the checksum in the listing |
Managing installed plugins
In the Installed plugins section each plugin takes two lines: the name and version on the first, and its id, the extensions it claims, its size on disk and its current status on the second.
The dropdown at the end of the row holds four entries:
| Entry | What it does |
|---|---|
| Enable / Disable | A disabled plugin produces nothing, exactly as if it were not installed; enabling it again takes effect immediately |
| Open file location | Opens the plugin's folder in your file manager |
| Uninstall | Stops the process and deletes the folder. It runs on the click, with no confirmation — reinstalling is one step |
The status normally reads Enabled or Disabled; when something is wrong it names the reason instead:
| Status | What it means |
|---|---|
| crashed repeatedly, disabled for this run | The plugin failed twice in a row, so tessoa stops asking it for the rest of this run. Restarting tessoa, or disabling and enabling it again, resets that |
| incompatible protocol version | The plugin was written for a different tessoa version |
| no binary for this platform | The package holds no program for your system |
| version x.y.z failed to install | The last update did not go through, and the old version is still in use |
What appears in preview once a plugin is installed
A format claimed by a plugin can have thumbnails in Icons view and previews in Gallery, the Columns preview pane, the side detail panel and preview tabs.
Video and audio files get a ▶ in the middle of their cover art. Click it to start playing, and a playback bar sits under the picture:
| Control | What it does |
|---|---|
| ⏯ | Pause / resume. Sound and picture stop together |
| Progress bar | Click anywhere to jump there |
| Timecode | The current position, mm:ss |
| ♪ | Mute / unmute. Muting is not pausing — the picture keeps running |
| Volume bar | Click to set the volume, unmuting as it does. Volume and mute are remembered across restarts |
A few boundaries worth knowing:
- Switching to another file, or closing the tab, ends playback.
- Switching to another tab pauses it; coming back leaves it where it stopped, and it does not resume on its own.
- Minimising the window keeps the sound going and stops the picture.
- With two windows each playing something, only the more recently started one has sound; the other one's picture carries on.
Multipage documents
Plugins that support page navigation can display a document page by page. A plugin that supplies only a cover image does not show page controls. For example, tessoa-office 0.2.0 and later supports multipage .docx and .pptx previews when used with tessoa 0.24.0 or later.
- Install or update a plugin that supports the format, and check that it is enabled.
- Select the document and view it in Gallery, the Columns preview pane, the side detail panel or a preview tab.
- Wait for the first page, then use the page number and layout controls to browse the rest.
| Action | How |
|---|---|
| Turn pages | Scroll the mouse wheel over the preview |
| Jump to a page | Click the page number, such as 1/6, and enter the target page |
| Change layout | Choose Single page, Continuous scroll or Two-page |
| Zoom in / out | Use the preview's zoom buttons; drag the page after zooming in |
These are the same controls as PDF preview. Layout buttons are hidden when the window is too narrow. Document previews are for viewing; text cannot be edited on the page.
Waiting and failure messages
If a plugin takes more than about 0.3 seconds to produce a preview, the large preview area shows a spinner. When you turn to a document page that has not loaded yet, the spinner appears in the middle of that page and disappears when loading completes. Thumbnails in Icons view do not show these spinners.
When a plugin cannot decode a file, preview shows the diagnosis it provides along with its name, such as Plugin … can't play this file. If repeated runtime failures temporarily disable the plugin, both the toast and preview explain Plugin … failed repeatedly and is disabled for this run. Playback and page-navigation controls are no longer available.
To try again, open Plugins from the top-left menu, then Disable and Enable the installed plugin using its menu. Restarting tessoa also resets it. If it still fails, keep the plugin name and diagnosis from the message when checking for plugin updates or reporting the problem.
The suggestion when no plugin is installed
Open a video, audio file or document whose format needs a plugin, and preview reads Install a preview plugin to preview this format, with a View plugins button below it that goes straight to the plugin page.
The line appears only when all four of these hold: Suggest installable preview plugins is on, Enable preview plugins is on, the extension is in tessoa's built-in list (mp4 mkv mov webm m4v avi mp3 flac ogg m4a wav docx pptx), and no installed plugin claims it — a plugin you installed and then disabled still counts as installed, so you are not talked into installing it twice.
To stop seeing the line, turn off Suggest installable preview plugins in the Maintenance group. The switch governs the line only; it does not change whether plugins work.
On Windows an ordinary mp4 usually shows no such line. The system produces a cover frame for those videos by itself, preview draws that picture, and there is no room left for the line. Videos the system cannot decode either (HEVC ones, for example), and macOS and Linux, show it as usual.
License and terms
Plugin previews belong to the Supporter tier. Below that tier:
- A note stays at the top of the plugin page saying installed plugins will not take effect and that thumbnails and playback fall back to the system defaults; the Unlock button at the end of that line opens the About › License page.
- Preview reads Upgrade to Supporter to use plugin previews, and only for files whose format a plugin you installed actually claims.
- Installing, uninstalling, enabling, disabling and browsing the plugin source are not restricted. Installing before buying is fine: plugins take effect the moment you unlock.
The Preview Plugin Terms are a document of their own, covering where responsibility sits between a third-party plugin and tessoa. They are presented once when you install a plugin and never block startup; after the terms change, the next install or update asks again. The full text is available at any time in the About group in Settings.
When the plugin source cannot be reached
The Available plugins section is always on the page, and when it cannot be reached the reason is what it shows:
| Message | What to do |
|---|---|
| Couldn't reach the plugin source. … | Check your connection, then click Rescan |
| The plugin source failed its signature check, so this list was rejected. … | Try again later; if it persists, download the package from the website and use Install from file… |
| The plugin list is in a format this build doesn't recognise. … | Update tessoa to the newest version first |
| The plugin source has nothing available for this machine yet. | Nothing is published yet for this system or architecture |