Documentation / Installation

Install SynapSeq

Install the CLI, build it from source, and render your first sequence.

On this page

Installation

Choose a package manager or install a precompiled binary for your platform.

Windows

Install SynapSeq with WinGet from PowerShell. Copy and run each command in order:

winget update
winget install synapseq

For file associations, File Explorer actions, and Windows-specific command options, see the Windows section of the CLI documentation.

macOS

SynapSeq currently provides a native binary for Apple Silicon Macs (ARM64). Install it with Homebrew. Copy and run each command in order:

brew tap synapseq-foundation/synapseq
brew trust synapseq-foundation/synapseq
brew install synapseq

Intel-based Macs are not supported by the published macOS binary.

Linux

The installer supports Debian and Ubuntu derivatives, plus Fedora. Inspect the Bash installer before running it with administrator privileges:

curl -fsSL https://synapseq.org/install.sh | sudo bash

Fedora requires RPM Fusion Free and Nonfree. Configure RPM Fusion before installing SynapSeq.

Generic install

Download a precompiled binary from SynapSeq v4.43.0, published 2026-10-05. Each archive contains the executable and its SHA-256 checksum at the archive root; there is no nested folder.

Windows AMD64 (zip) Contains synapseq-v4.43.0-windows-amd64.exe and its checksum.

Windows ARM64 (zip) Contains synapseq-v4.43.0-windows-arm64.exe and its checksum.

Linux AMD64 (tar.gz) Contains synapseq-v4.43.0-linux-amd64 and its checksum.

Linux ARM64 (tar.gz) Contains synapseq-v4.43.0-linux-arm64 and its checksum.

macOS ARM64 (tar.gz) Contains synapseq-v4.43.0-macos-arm64 and its checksum.

Windows

  1. Extract the ZIP. It contains one versioned .exe and its .sha256 file.
  2. Create C:\Program Files\SynapSeq and move the executable there.
  3. Rename the executable to synapseq.exe.
  4. Add C:\Program Files\SynapSeq to your user Path environment variable, then open a new terminal.

macOS and Linux

Extract the archive, then install the executable in a directory on your $PATH. Copy and run each command in order:

tar -xzf synapseq-VERSION-OS-ARCH.tar.gz
chmod +x synapseq-VERSION-OS-ARCH
sudo mv synapseq-VERSION-OS-ARCH /usr/local/bin/synapseq

Replace VERSION-OS-ARCH with the filename shown in the downloaded archive.

Agents

Install the skills

Install create-spsq, explain-spsq, and review-spsq, then choose an agent and scope.

npx skills add synapseq-foundation/synapseq

Create a score

Open your project in the agent and describe the sequence you want.

Codex

$create-spsq Create a 20-minute binaural relaxation score with smooth fades.

Claude Code

/create-spsq Create a 20-minute binaural relaxation score with smooth fades.

Understand and review

Use explain-spsq to understand a score or review-spsq to check its syntax and sound structure. Invoke either skill with the agent's $ or / prefix and include the path to the SPSQ file. Both skills provide read-only feedback.

Validate and render

The skills install agent guidance; the CLI performs local validation and audio rendering. Install SynapSeq, then ask your agent to validate the score and render the WAV with these commands. Replace the example path with your score's path:

synapseq -test path/to/score.spsq
synapseq path/to/score.spsq

To create sequences with SynapSeq's native AI integration, explore AI.

Compilation

Compile SynapSeq from source on macOS, Linux, or Windows. Copy and run each command in order for your platform, choosing one option where alternatives are shown.

Prerequisites

Install Go 1.27.0 or later, make, and git.

Install Go and Make

macOS

Using Homebrew:

brew install go

Or using MacPorts:

sudo port install go

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install golang-go make

Or install a newer Go version using snap:

sudo snap install go --classic

Linux (CentOS/RHEL/Fedora)

Fedora:

sudo dnf install golang make

CentOS/RHEL:

sudo yum install golang make

Distribution packages can lag behind the required Go version. Check your Go version with the command below; if it is older than 1.27.0, install a current release from the official Go downloads.

go version

Windows

Use Git Bash because the Makefile relies on Unix-like shell commands. Install Git for Windows and Scoop, then run these commands in PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
scoop update
scoop install go make

Open Git Bash and verify the toolchain:

go version
make --version
git --version

Compile SynapSeq

Clone the repository if needed:

git clone https://github.com/synapseq-foundation/synapseq.git
cd synapseq

On macOS and Linux, run the test suite and build for the current platform:

make test
make build

This creates the binary in bin/.

Windows

Use the platform-specific targets to keep the .exe extension, application icon, and Windows command-line behavior. Do not use make build on Windows.

make test

Build for Windows 64-bit (Intel/AMD):

make build-windows-amd64

Or build for Windows 64-bit (ARM):

make build-windows-arm64

The build generates Windows resource metadata with goversioninfo. The first Windows build downloads and runs it through go run, so network access is required. The icon is in assets/synapseq.ico.

Cross-compile

Linux 64-bit (Intel/AMD):

make build-linux-amd64

Linux 64-bit (ARM):

make build-linux-arm64

macOS (Apple Silicon):

make build-macos

Install the binary

macOS and Linux

sudo make install

This installs SynapSeq at /usr/local/bin/synapseq.

Windows

In Git Bash as Administrator, install the executable:

mkdir -p "/c/Program Files/SynapSeq"
cp bin/synapseq-windows-amd64.exe "/c/Program Files/SynapSeq/synapseq.exe"

Add C:\Program Files\SynapSeq to the system Path through Environment Variables. For a per-user install without administrator rights, copy the executable to %LOCALAPPDATA%\SynapSeq and add that directory to the user Path. Open a new terminal and verify the installation:

synapseq -h

Additional Make targets

Run the Go test suite:

make test

Remove build artifacts:

make clean

Getting Started

Choose an example and run its score directly from the terminal. SynapSeq accepts HTTPS URLs as input. Audio files are written to the current directory.

Play in real time

-play requires ffplay.

synapseq -play https://synapseq.org/examples/binaural.spsq

Export MP3

-mp3 requires ffmpeg.

synapseq -mp3 https://synapseq.org/examples/binaural.spsq

Export WAV

With no output option, SynapSeq writes a WAV file to the current directory.

synapseq https://synapseq.org/examples/binaural.spsq

Read the SPSQ documentation to learn how sequence files define sounds, tracks, and timelines.

View all documentation