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:

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:

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.42.0, published 2026-09-12. 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.42.0-windows-amd64.exe and its checksum.

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

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

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

macOS ARM64 (tar.gz) Contains synapseq-v4.42.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:

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 run synapseq -test path/to/score.spsq and render the WAV with 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.

Prerequisites

Install Go 1.27.0 or later, make, and git.

Install Go and Make

macOS

# Using Homebrew
brew install go

# Using MacPorts
sudo port install go

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install golang-go make

# Or install a newer 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 go version; if it is older than 1.27.0, install a current release from the official Go downloads.

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
make build-windows-amd64    # Windows 64-bit (Intel/AMD)
make build-windows-arm64    # Windows 64-bit (ARM)

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
make build-linux-amd64
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 with synapseq -h.

Additional Make targets

make test     # Run the Go test suite
make clean    # Remove build artifacts

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