Installation

There are two ways to get Helia: install a release (Windows, Debian and Ubuntu, Fedora, any Linux through an AppImage; macOS is coming) or build it from source (every platform, a few minutes). Releases are built by the project and shared with early-access users (contact 12hobbies.studio; releases are not public yet).

You get two programs:

• helia, the command line tool (which also runs the API server);
• helia-gui, the desktop app.

Download a release

Each release has an installer or package for your system, the plain archives, a SHA256SUMS file and the release notes. Releases before 1.0 are marked as pre-releases. Pick one of the rows that matches your system.

The Windows files are attached by a second build, so they can appear a little after the Linux ones. Download and verify shows how to check a download against its checksum before you run it.

Windows

Run helia-<version>-x86_64-pc-windows-msvc-setup.exe.

The first run shows a SmartScreen warning. The installer is not code-signed yet (#70), so Windows says "Windows protected your PC" and "Unknown publisher". After you have checked the file's checksum, choose More info, then Run anyway. The warning goes away once the project has a signing certificate.

The installer:

1. shows the GPL and the additional terms that go with it (you must read, not sign: Helia is free software and the pages are there so you know what you are getting);

2. asks Who is this for? The default, Just for me, installs to %LOCALAPPDATA%\Programs\Helia and needs no administrator rights. All users installs to C:\Program Files\Helia; if you are not an administrator the installer asks Windows for permission and starts again with the choice made, so the licence pages show a second time;

3. offers these parts, ticked as shown:

   Part	Default	What it does
   Helia	always	helia-gui.exe (the app), helia.exe (the command line tool), the licences
   Start menu shortcut	on	Helia in the Start menu
   Desktop shortcut	off	an icon on the desktop
   Add the helia command to PATH	off	lets you type helia in any new terminal
   Open with Helia	on	lists Helia under Open with for .ser, .avi and .fits files. It never becomes the default program for them

Helia then appears in Settings > Apps > Installed apps with its version and publisher, and uninstalls from there. Double-clicking helia-gui.exe opens the window with no console behind it; helia.exe is the command line tool and stays a console program.

To install for a whole lab without the pages, from a terminal:

.\helia-0.5.0-x86_64-pc-windows-msvc-setup.exe /S /ADDPATH /DESKTOP

The switches are /S (silent), /AllUsers (needs an administrator), /ADDPATH, /DESKTOP, /NOSTART, /NOASSOC and /D=C:\Where\To\Install (last, with no quotes). Without /AllUsers the install is for the current user and needs no administrator rights, even when silent. With /AllUsers from a prompt that is not elevated the installer stops with exit code 740 and installs nothing; run it from an administrator prompt. The start menu shortcut and Open with are on unless you pass /NOSTART or /NOASSOC; the desktop shortcut and the PATH entry are off unless you pass /DESKTOP or /ADDPATH.

Uninstall: Settings > Apps > Installed apps > Helia > Uninstall, or run uninstall.exe in the install folder with /S. For an all-users install add /AllUsers and run it from an administrator prompt (uninstall.exe /AllUsers /S); the entry in Settings does that for you. It removes the programs, the shortcuts, the Open with entries and the PATH entry. It leaves your settings (%APPDATA%\helia) and your images alone; delete the folder if you want them gone.

If you prefer no installer, unzip the .zip anywhere and run helia-gui.exe.

If something goes wrong on Windows

Debian, Ubuntu and Raspberry Pi OS

sudo apt install ./helia_0.5.0_amd64.deb      # arm64 on a Raspberry Pi

(apt install ./file.deb also pulls in the packages Helia recommends, such as the Vulkan loader and Mesa drivers; plain dpkg -i does not.) You get helia and helia-gui in /usr/bin, a Helia entry in your applications menu with its icon, and Helia in the Open with list for SER, AVI and FITS files. Install ffmpeg too if you want to open MP4 files.

Uninstall: sudo apt remove helia. (sudo apt purge helia is the same; the package keeps no configuration. Your settings are in ~/.config/helia.)

If something goes wrong on Debian and relatives

• dpkg: dependency problems or libc6 (>= 2.35) but ... is installed: the system is too old (Ubuntu 20.04 and Debian 11 are). Build from source, or use a newer system.
• Unable to locate package ./helia_..., or Unsupported file ... given on commandline: apt install needs the path to start with ./ (or be absolute), and the file must be the one for your CPU (amd64 on a PC, arm64 on a Raspberry Pi with a 64-bit system; dpkg --print-architecture tells you).
• helia: command not found right after installing: open a new terminal. The programs are in /usr/bin, so a fresh shell finds them.
• No Helia entry in the applications menu, or it is not under Open with: log out and in, or run sudo update-desktop-database and sudo update-mime-database /usr/share/mime. The package installs the desktop file and a MIME type for SER files (video/x-astro-ser); AVI and FITS are known to the system already.
• The window opens but the top bar says CPU: no Vulkan driver was found. Install libvulkan1 and mesa-vulkan-drivers, or NVIDIA's driver. See GPU acceleration.

Fedora and other RPM systems

sudo dnf install ./helia-0.5.0-1.x86_64.rpm   # aarch64 on ARM

It installs the same files in the same places, and the troubleshooting notes for the .deb apply, with sudo dnf install ./file.rpm for apt install ./file.deb and the architectures x86_64 and aarch64 (uname -m tells you which). Uninstall: sudo dnf remove helia. The RPM is built for glibc 2.35 or newer, which every supported Fedora has. It has not been installed on a Fedora machine by the project's own tests (there is none), only unpacked and checked on Debian; report what you find.

AppImage

One file, no installation, runs on most Linux desktops:

chmod +x Helia-0.5.0-x86_64.AppImage
./Helia-0.5.0-x86_64.AppImage                  # the app
./Helia-0.5.0-x86_64.AppImage --cli --version  # the command line tool

Pass a capture to open it: ./Helia-0.5.0-x86_64.AppImage capture.ser. If it says it cannot mount itself, your system lacks FUSE; run it with APPIMAGE_EXTRACT_AND_RUN=1 or install libfuse2. An AppImage does not add a menu entry by itself; tools such as AppImageLauncher do that, or copy the .desktop file from the tarball. Uninstall: delete the file.

If something goes wrong with the AppImage

• Permission denied: the file is not executable. chmod +x it; some browsers and file managers drop the permission.
• It starts and stops at once with a message about fusermount or libfuse.so.2: see the FUSE note above (APPIMAGE_EXTRACT_AND_RUN=1 or libfuse2).
• It will not run from a folder: a few systems mount /tmp or the home folder with noexec, which stops AppImages and extracted copies. Put the file in a folder that is not mounted that way.
• The command line tool is the same file with --cli first: ./Helia-0.5.0-x86_64.AppImage --cli stack capture.ser -o out.tif.
• Open with is not set up: an AppImage does not register file types. Pass the capture on the command line, or integrate the AppImage with a tool such as AppImageLauncher.

macOS

macOS builds are coming. The project has no Mac to build on yet (#75), so there is no download today; build from source as described below. The packaging is written and waits for a Mac build machine: a Helia.app in a disk image, universal for Apple silicon and Intel, with .ser, .avi and .fits listed under Open With.

When it arrives it will not be signed or notarised until the project has an Apple Developer ID, so macOS Gatekeeper will say Helia "cannot be opened because the developer cannot be verified". To open it the first time: drag Helia to Applications, right-click (or Control-click) Helia and choose Open, then Open again in the dialog. Or open System Settings > Privacy & Security, scroll to the message about Helia, and choose Open Anyway. You only do this once. Uninstall: drag Helia to the Bin; settings are in ~/.config/helia.

The plain archives

The .tar.gz and .zip archives hold the same programs without an installer, for people who want to put them somewhere themselves:

# in the folder you downloaded the archive and SHA256SUMS to
sha256sum -c SHA256SUMS --ignore-missing
tar -xzf helia-<version>-x86_64-unknown-linux-gnu.tar.gz
cd helia-<version>-x86_64-unknown-linux-gnu
./helia --version
./helia-gui

Each archive holds helia, helia-gui, the licences, this project's README and changelog, and THIRD-PARTY-LICENSES.txt for the libraries inside. The Linux one also has share/applications/helia.desktop and the icons under share/icons; copy share/ into ~/.local to get a menu entry.

Things to know about the Linux downloads

• They need glibc 2.35 or newer: Ubuntu 22.04, Debian 12, Raspberry Pi OS (Bookworm), Fedora 36 or anything newer. On an older system, build from source.
• They do not bundle a graphics driver. Install the Vulkan loader and a driver (libvulkan1 and mesa-vulkan-drivers, or NVIDIA's driver); without one Helia uses the CPU. The .deb and .rpm recommend them. The desktop app also needs the usual X11 or Wayland and libxkbcommon libraries, which a desktop installation already has.
• The aarch64 packages are cross-compiled and checked by running the binaries under an emulator, not on real Raspberry Pi hardware. Report what you find.
• Each release also carries two CycloneDX SBOM files (*.cdx.json) listing the libraries each program was built from. Every package carries the licences: /usr/share/doc/helia in the .deb and .rpm, inside the AppImage, in the install folder on Windows.

Open a capture from your file manager

With the installer or a package you can right-click a .ser, .avi or .fits file and choose Open with > Helia. The same works from a terminal: helia-gui capture.ser. Helia remembers the size of its window and, under Recent in the top bar, the last eight captures you opened.

Optional: ffmpeg for MP4 and other video

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 (MJPEG, H.264), it uses the free ffmpeg program if it is installed. Nothing else changes if it is not: Helia never bundles or links ffmpeg, and without it those files are refused with a message that says how to install it.

You need ffmpeg and ffprobe (they come together) at version 4.4 or newer.

Check it with ffmpeg -version. Helia finds the programs on your PATH. To use others, set HELIA_FFMPEG and HELIA_FFPROBE to their full paths. The helia info command on a video file is a quick test that it all works, and Troubleshooting lists what the errors mean.

Decoded frames are written to a cache directory (the operating system's cache folder by default, --cache-dir or HELIA_CACHE_DIR to choose another), and removed when Helia is done with them. See Capturing for why raw SER or AVI is still better.

Build from source

What you need first

• A current stable Rust toolchain. The minimum version is the rust-version in the repository's Cargo.toml (1.95 at the time of writing). Install it with rustup.
• A source checkout of the repository.
• Optionally a GPU with a working driver. Helia runs without one; see GPU acceleration.

Windows

1. Install the Visual Studio Build Tools with the "Desktop development with C++" workload. Rust needs the Microsoft linker.
2. Install Rust with rustup-init.exe from rustup.rs, choosing the default x86_64-pc-windows-msvc host (or the ARM64 one on a Windows on Arm machine).
3. In a terminal, in the checkout:

cargo build --release

The programs are target\release\helia.exe and target\release\helia-gui.exe. Helia uses DX12 or Vulkan; your graphics driver provides them. If a corporate policy blocks programs built in the checkout (Windows Application Control can do this to build scripts), point CARGO_TARGET_DIR at a folder that policy allows.

Linux, including Raspberry Pi

Install a C toolchain, the Vulkan loader and, for the desktop app, the windowing libraries. On Debian and Ubuntu:

sudo apt-get install build-essential pkg-config libvulkan1 mesa-vulkan-drivers \
    libxkbcommon-dev libwayland-dev

mesa-vulkan-drivers covers AMD, Intel and the Raspberry Pi; NVIDIA owners use NVIDIA's own driver instead. Then:

cargo build --release

On a Raspberry Pi use a 64-bit operating system (Raspberry Pi OS 64-bit or Ubuntu for Pi). Helia lists the Pi 4 and Pi 5 as supported GPUs, through the Mesa Vulkan driver with GLES as a fallback. The project's automated tests run on 64-bit ARM Linux with a software GPU, but not on Raspberry Pi hardware, so report what you find. Compiling on a Pi is slow; cross-compiling from a PC is an option.

macOS

Install the Xcode command line tools (xcode-select --install) and Rust. Helia uses Metal, which needs no extra setup on Apple silicon or Intel Macs.

cargo build --release

Check it works

target/release/helia --version
target/release/helia info path/to/capture.ser

To try Helia without a capture, write a synthetic one with cargo xtask sample, described in the Quick start.

To install the programs on your PATH instead of running them from target:

cargo install --path crates/helia-cli
cargo install --path crates/helia-gui