DecayCore

DecayCore Installation Guide

Install DecayCore from a packaged release or run it from Python source on Windows, Linux, and macOS.

For most users, the recommended option is:

  1. Download the latest packaged release
  2. Extract it
  3. Run DecayCore
  4. Open http://127.0.0.1:8080 if the browser does not open automatically

Latest release:

All releases:

Python and dependency baseline

All DecayCore versions released and documented in this repository are based on Python 3.12.3.

Current dependency baselines from the repository requirement files are:

From v1.1.6 onwards numba is no longer used. The hot DSP and scoring paths it previously accelerated are now provided by two optional Rust extensions (decaycore-dsp and decaycore-scoring). They are bundled and prebuilt in the packaged releases. If you run from source, see Optional Rust acceleration extensions below — DecayCore still runs without them using a pure-Python fallback, but they are strongly recommended for acceptable performance.

Run from release package

Windows

  1. Download DecayCore_<version>_windows.7z from Releases.
  2. Extract the ZIP.
  3. Run DecayCore.exe.
  4. If SmartScreen appears, choose More info -> Run anyway.
  5. Allow private firewall access if prompted. DecayCore runs on internal server on your computer.
  6. Open http://127.0.0.1:8080 if the browser does not open automatically.

Ubuntu / Debian Linux

  1. Download DecayCore_<version>_linux.7z from Releases.
  2. Extract the archive.
  3. Open Terminal in the extracted folder and run:
./run.sh

  1. Built-in measurement: Measurement has been verified to work on Windows. Linux has been verified to work at least on Ubuntu 22.04. macOS could not be tested due to unavailable test hardware. On platforms where measurement is unavailable, compatible external measurements can be used.

  2. Built-in measurement audio requires the system PortAudio library. If measurement audio reports a PortAudio/backend error, install it first:

sudo apt install libportaudio2
  1. Open http://127.0.0.1:8080 if the browser does not open automatically.

Raspberry Pi / Linux ARM64

  1. Download DecayCore_<version>_linux_arm64.7z from Releases.
  2. Extract the archive.
  3. Open Terminal in the extracted folder and run:
./run.sh
  1. Use this build for Raspberry Pi 4/5 running a 64-bit operating system, Debian/Ubuntu Linux ARM64 systems, and other 64-bit ARM Linux machines.
  2. This build does not support 32-bit Raspberry Pi OS.
  3. Open http://127.0.0.1:8080 if the browser does not open automatically.

macOS (Apple Silicon)

  1. Download DecayCore_<version>_macos_arm64.7z from Releases.
  2. Extract the archive.
  3. Double-click Start_Decay.command to launch DecayCore through Terminal.
  4. If macOS blocks the first launch, open System Settings -> Privacy & Security -> Open Anyway.
  5. If you prefer the bundle directly, you can also double-click DecayCore_<version>.app.
  6. If you prefer Terminal, open Terminal in the extracted folder and run:
./Start_Decay.command
  1. Built-in measurement: Measurement has been verified to work on Windows. Linux has been verified to work at least on Ubuntu 22.04. macOS could not be tested due to unavailable test hardware. macOS users can use compatible external measurements.
  2. If macOS asks for microphone access, allow DecayCore. Measurement files are saved under Documents/DecayCore/measurement by default and fall back to a writable app-data location if needed.
  3. Open http://127.0.0.1:8080 if the browser does not open automatically.

Run directly from Python source

Use this path if you want to run DecayCore from a cloned source tree instead of a packaged release. The documented baseline is Python 3.12.3.

Repository:

Get the source with Git

Install Git first:

Clone the repository:

git clone https://github.com/VilhoValittu/DecayCore.git
cd DecayCore

To update an existing clone later:

cd DecayCore
git pull

Optional Rust acceleration extensions

DecayCore ships two optional Rust extensions that accelerate the DSP and scoring paths that previously relied on numba:

These are prebuilt and bundled in the packaged releases, so release users do not need them. When you run from source they are not installed by requirements.txt. DecayCore will still start and produce correct results without them through a pure-Python fallback, but the fallback is significantly slower. Building the extensions is strongly recommended for source runs.

Building them requires a Rust toolchain. Install it once with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Restart your shell (or run . "$HOME/.cargo/env" on Linux/macOS) so cargo is on PATH, then verify:

cargo --version

With your DecayCore virtual environment activated (see the per-platform steps below), build and install both extensions from the source tree. pip reads the maturin build backend declared by each crate and compiles them automatically:

python -m pip install ./decaycore-scoring
python -m pip install ./decaycore-dsp

On Windows, run the same two commands from PowerShell after activating the virtual environment. The Rust toolchain on Windows also needs the MSVC build tools (the rustup-init.exe installer prompts to install them if they are missing).

You can confirm the extensions loaded after starting DecayCore: when an extension is missing, a fallback warning is logged and the Python implementation is used instead.

Windows

  1. Install Python from https://www.python.org/downloads/windows/ and enable Add python.exe to PATH.
  2. Open PowerShell in the cloned DecayCore source folder.
  3. Create and activate a virtual environment:
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
  1. Install dependencies:
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
  1. (Recommended) Build the optional Rust extensions. This requires a Rust toolchain — see Optional Rust acceleration extensions:
python -m pip install ./decaycore-scoring
python -m pip install ./decaycore-dsp
  1. Start DecayCore:
$env:PYTHONPATH = "src"
python -m decaycore
  1. Open http://127.0.0.1:8080 if the browser does not open automatically.

If PowerShell blocks activation, run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then activate the virtual environment again.

Ubuntu / Debian Linux

  1. Install Git, Python, venv support, pip :
sudo apt update
sudo apt install git python3 python3-venv python3-pip
  1. Open Terminal in the cloned DecayCore source folder.
  2. Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
  1. Install dependencies:
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
  1. (Recommended) Build the optional Rust extensions. This requires a Rust toolchain — see Optional Rust acceleration extensions:
python -m pip install ./decaycore-scoring
python -m pip install ./decaycore-dsp
  1. Start DecayCore:
PYTHONPATH=src python -m decaycore
  1. Open http://127.0.0.1:8080 if the browser does not open automatically.

macOS

  1. Install Python from https://www.python.org/downloads/macos/ or with Homebrew.
  2. Install Git with Xcode Command Line Tools or Homebrew:
xcode-select --install

or:

brew install git
  1. Open Terminal in the cloned DecayCore source folder.
  2. Create and activate a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
  1. Install dependencies:
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
  1. (Recommended) Build the optional Rust extensions. This requires a Rust toolchain — see Optional Rust acceleration extensions:
python -m pip install ./decaycore-scoring
python -m pip install ./decaycore-dsp
  1. Start DecayCore:
PYTHONPATH=src python -m decaycore
  1. Open http://127.0.0.1:8080 if the browser does not open automatically.

Output path

Output ZIP files are saved by default to:

Documents/DecayCore/filters/<version>/

If that path is not writable, DecayCore falls back to a safe writable directory and reports the final path in Results.

Browser and PNG notes

Known issue: Windows + Vivaldi

In some Windows setups, using Vivaldi can trigger NumPy MemoryError under browser memory pressure.

Workarounds: