SampleToNES Contents View online

Installation

You can install SampleToNES in several ways. If you are unsure, download a release.

  • Download a release. This is the easiest way on Windows and Linux.
  • Install from PyPI. This works on Windows, macOS and Linux.
  • Run from source. Use this to change the code or to build the app yourself.

▍Download a release

  1. Open the releases page.
  2. Download the file for your system: Windows or Linux.
  3. Extract the file.
  4. Start sampletones in the extracted folder. On Windows, double-click sampletones.exe.

On Linux, you may need to make the file executable first: chmod +x sampletones.

▍Install from PyPI

You need Python 3.12 or newer.

On Linux and macOS, install the audio and file dialog libraries first:

sudo apt-get install libportaudio2 libasound2 python3-tk    # Debian and Ubuntu
brew install portaudio                                      # macOS

Then install SampleToNES in an environment of its own, and start it:

uv tool install sampletones      # or: pipx install sampletones
sampletones

You can also run pip install sampletones inside an active virtual environment.

▍Run from source

You need:

Get the code and set it up:

git clone https://github.com/JakimPL/SampleToNES.git
cd SampleToNES
make system-deps    # Linux and macOS: installs the system libraries
make setup          # creates the environment and installs the sampletones command
make run            # starts the app

After you pull new changes, run make setup again.

On Windows and Linux, you can also build a standalone app from the source code:

  • Windows: double-click install.bat. It builds bin\sampletones\sampletones.exe.
  • Linux: run make system-deps, then ./install.sh. It builds bin/sampletones/sampletones.

The build adds GPU support when it finds an NVIDIA graphics card. See GPU acceleration.

▍GPU acceleration

SampleToNES can use an NVIDIA graphics card to build libraries and convert recordings faster. It needs an NVIDIA card with a current driver, on Windows or Linux. On macOS, the app runs without GPU acceleration.

  • Standalone app you build: install.bat and ./install.sh check your NVIDIA driver and bundle the matching GPU support. The app folder then holds the NVIDIA libraries and grows to a few gigabytes. Add --gpu 0 to build the smaller app for the CPU alone: ./install.sh --gpu 0, or install.bat --gpu 0. The build finishes only once the app has computed on your card.
  • From source: make setup checks your NVIDIA driver and installs the matching GPU support. make setup GPU=0 installs the app for the CPU alone.
  • From PyPI: add the gpu extra, uv tool install "sampletones[gpu]". If your driver supports CUDA 11 only, use the gpu-cuda11 extra instead.

The apps on the releases page run on the CPU. To see which one your app uses, run sampletones self-check and read the "array backend" line.

Once the app runs, Getting started walks you through your first reconstruction and your first song.