Optional tools: installing ffmpeg¶

Helia reads SER and uncompressed AVI by itself. To open MP4, MOV, M4V, MKV and WebM files, and AVI files that use a compressed codec, it uses the free ffmpeg program. Helia does not contain ffmpeg and its installers never will: ffmpeg belongs to its own authors and has its own licence. What Helia can do is fetch it for you from the people who build it, after you have read and accepted their licence, and keep it in a folder of your own. This page shows how, and how to check, update and remove it.

Where it comes from¶

Helia downloads from the provider's own server, checks the file against a fingerprint (SHA-256) that is signed with the same key that signs Helia's updates, and refuses anything that does not match. The list of what is on offer is itself signed, so a change to a provider's address or file needs no new Helia.

Video formats such as H.264 and H.265 are covered by patents in some countries. Whether that matters to you is between you and the provider; Helia only uses ffmpeg to read the videos you give it.

Tutorial: install ffmpeg from the terminal¶

This walks through helia tools on Linux with no ffmpeg installed. The window version is the same steps in a dialog (see the app section below).

1. See what you have. This uses no network.

$ helia tools status
Optional tools
  Nothing installed with Helia. `helia tools install ffmpeg` installs ffmpeg.
Helia cannot find ffmpeg. Video files need it; `helia tools install ffmpeg` fetches it.
Tools folder: ~/.local/share/helia/tools

2. Start the install. Helia fetches the signed list of tools, then shows what it would do and the licence, and waits.

$ helia tools install ffmpeg --method download
FFmpeg 9.0.2
  FFmpeg and FFprobe read compressed video (MP4, MOV, MKV, WebM). Helia uses them only to decode your own video files on this computer; nothing is encoded or sent anywhere.
  Provided by: BtbN FFmpeg-Builds
  Helia would download 131.5 MB from github.com into ~/.local/share/helia/tools.
  Licence: GNU Lesser General Public License, version 3 or later
  Licence and source: https://github.com/BtbN/FFmpeg-Builds
  Helia is not affiliated with the provider and does not distribute this tool.

The licence follows. Read it, then answer the question at the end.

                   GNU LESSER GENERAL PUBLIC LICENSE
                       Version 3, 29 June 2007

 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
[... the licence text continues, 170 lines in all ...]

Type yes to accept the licence above and install FFmpeg. Anything else cancels:

On a terminal the licence opens in your pager ($PAGER, else less, else more): read it, press q, and the question follows. Anything other than yes cancels:

Type yes to accept the licence above and install FFmpeg. Anything else cancels: no
Cancelled. Nothing was downloaded. Helia keeps working without FFmpeg.

That ends with exit code 3 and no network request for the file was made.

3. Accept. Type yes. Helia records your acceptance, then downloads, checks and unpacks. The download resumes if it is interrupted: run the same command again.

Type yes to accept the licence above and install FFmpeg. Anything else cancels: yes
Downloading part 1/1: 0.0 MB of 131.5 MB (0%)
Downloading part 1/1: 13.2 MB of 131.5 MB (10%)
...
Downloading part 1/1: 131.5 MB of 131.5 MB (100%)
Checking the download...
Unpacking...
Installed FFmpeg 9.0.2 in ~/.local/share/helia/tools/ffmpeg.
FFmpeg is a trademark of Fabrice Bellard, originator of the FFmpeg project. This build of FFmpeg is made by the BtbN FFmpeg-Builds project and is used under the GNU Lesser General Public License, version 3 or later. Source code and build scripts: https://github.com/BtbN/FFmpeg-Builds and https://ffmpeg.org/download.html. Helia is not affiliated with FFmpeg or BtbN.
Helia uses it automatically; HELIA_FFMPEG and HELIA_FFPROBE still win if you set them.

On a 131.5 MB download over a fast home connection this took 44 seconds (your time depends on your line). The archive is unpacked while it is read, so no second large copy is written to disk.

4. Use it. Nothing else to set up. Open a video the way you always do:

$ helia info test.mp4
file:        test.mp4
format:      MP4 (read with ffmpeg)
codec:       mpeg4 (Simple Profile)
size:        320 x 240
pixel format: yuv420p, 8 bit
frames:      50
frame rate:  25.000 per second
duration:    2.0 s
note:        lossy 8-bit 4:2:0 video (mpeg4): fine for quick results, SER/AVI raw captures keep more detail

Helia looks for ffmpeg in this order: the HELIA_FFMPEG and HELIA_FFPROBE variables, a copy installed with helia tools install, then your PATH.

5. Check it later.

$ helia tools status
Optional tools
  FFmpeg 9.0.2 (download), installed 2026-10-26T15:43:06Z from BtbN FFmpeg-Builds
    Licence: GNU Lesser General Public License, version 3 or later (https://github.com/BtbN/FFmpeg-Builds)
    FFmpeg is a trademark of Fabrice Bellard, originator of the FFmpeg project. ...
Helia finds ffmpeg at ~/.local/share/helia/tools/ffmpeg/ffmpeg (installed with Helia).
Tools folder: ~/.local/share/helia/tools

status re-checks that each file is still there and the right size, and says NEEDS ATTENTION with what is wrong if not; run the install again to repair it. helia tools status --json prints the same as JSON.

6. Install again or update. Run helia tools install ffmpeg again. If you accepted the same licence text before, Helia says so and does not ask again:

You accepted this licence on 2026-10-26T15:42:22Z; it has not changed.

If the provider has changed the text, you see it and are asked again. A new ffmpeg version replaces the old folder as a whole.

7. Remove it.

$ helia tools remove ffmpeg --yes
Removed FFmpeg.

Without --yes Helia asks. Add --forget-licence to also forget that you accepted the licence, so installing again asks again.

Choosing how to install: --method¶

In scripts¶

There is no terminal to ask on, so install refuses with exit code 3 and tells you how to accept on purpose. Read the licence first:

helia tools licence ffmpeg          # provider, licence name, hash and the full text
helia tools install ffmpeg --method download --accept-licence 4b8f1c2d9a7e

--accept-licence takes the first 12 or more characters of the hash licence prints. If the licence text changed since you read it, the hash differs and nothing is installed.

In the app¶

When you open a video and ffmpeg is missing, Helia does not just refuse. It opens a page that says what happened, why, and what to do, with the provider, the size, the source link and the whole licence in a box you can scroll. Nothing is downloaded yet: the page has fetched only the signed list of tools, to be able to show the licence.

• Accept and install records your acceptance of the text on screen (and checks that the text is still the same when the download starts), then downloads, checks and unpacks.
• Decline, Close or Esc leave everything as it was. Helia keeps working; you can open SER and uncompressed AVI files without ffmpeg.
• If your system has a package manager, the page shows its command with Copy command, to run yourself in a terminal. The window never runs it, because it may ask for your password.
• If you accepted exactly this licence text before, the page says so; the text is still shown, and Accept and install installs without recording anything new.

While it downloads, the page shows progress and Cancel. Cancel keeps the part that arrived, so the next try carries on from there.

When it is done the page says so and shows the attribution the licence asks for.

If something goes wrong (no network, a file that does not match its checksum, a list that is not signed by Helia's key) the page says what happened and that nothing was installed, with Try again.

The About page has an Optional tools block. It lists what Helia installed, its provider and licence, the attribution, where Helia finds ffmpeg, and buttons to Install again (repair or update) and Remove.

Where things are kept¶

HELIA_EXTERNAL_DIR puts everything under one folder of your choice (a portable copy, or a test).

When something goes wrong¶

The tool list and the file are fetched only when you run licence or install. status and remove use no network, and Helia never checks for tool updates on its own.