SynapSeq

Text-Driven Audio Sequencer for Brainwave Entrainment

SynapSeq is a text-driven audio sequencer for building clear, repeatable brainwave and ambient sessions using a simple domain-specific language, written as SynapSeq sequences (.spsq).

What It Looks Like

A basic .spsq sequence is plain text: define options, declare presets with indented tracks, then place presets on a timeline.

# Options
@samplerate 44100
@volume 80

# Presets
focus
  tone 220 binaural 12 amplitude 25
  noise pink smooth 15 amplitude 12

# Timeline
00:00:00 silence
00:00:15 focus
00:04:30 focus 
00:05:00 silence

See SYNTAX for the complete language reference.

Quick Start

The recommended way to install SynapSeq is through the platform package manager.

Homebrew (macOS & Linux)

Install with Homebrew:

brew tap synapseq-foundation/synapseq
brew trust synapseq-foundation/synapseq # For homebrew >= 6.x
brew install synapseq

Winget (Windows)

Install with Winget:

winget update
winget install synapseq

After installation, you can run synapseq -install-file-association to associate .spsq files with SynapSeq and enable additional Explorer context menu actions.

Manual Downloads

If you prefer to install manually, download the appropriate archive from the latest GitHub release: 4.40.1.

If you want to build SynapSeq from source, see the Compilation Guide.

Usage

After installation on any platform, read the repository docs in this order:

• SYNTAX
• HOW IT WORKS

Examples

SynapSeq Remote provides ready-to-use sequences. Sync the local index before listing, searching, downloading, or generating a remote sequence:

synapseq -sync

List all available sequences:

synapseq -list

Search sequences by a word found in their name, description, or category:

synapseq -search focus

Use the sequence ID shown by -list or -search to download its .spsq file. This is the recommended option when you want to keep and inspect the sequence on your machine:

synapseq -download calm-state

The file is saved as calm-state.spsq in the current directory. You can also provide a destination directory:

synapseq -download calm-state ./sequences

To download a remote sequence and generate its audio in one step, use -get:

synapseq -get calm-state

By default, the output uses the sequence name and the .wav extension. An output file can be specified explicitly:

synapseq -get calm-state calm-state.wav

You can export to mp3 using the -mp3 flag:

synapseq -mp3 -get calm-state calm-state.mp3

Or with .mp3 extension:

synapseq -get calm-state calm-state.mp3

Programmatic API

Example:

package main

import (
	"fmt"
	"os"
	"time"

	synapseq "github.com/synapseq-foundation/synapseq/v4/core"
	"github.com/synapseq-foundation/synapseq/v4/spsq"
)

func main() {
	// Create a new app context with colorized verbose logging
	ctx := synapseq.NewAppContext().WithVerbose(os.Stderr, true)
	// Create a new spsq builder with a sample rate of 44100 Hz and volume of 80%
	builder := spsq.New().SampleRate(44100).Volume(80)

	// Create a new preset for focus mode
	focus := builder.NewPreset("focus")
	// Add tone with 220 Hz, binaural with 12 Hz, and amplitude of 25%
	focus.Tone(220).Binaural(12).Amplitude(25)
	// Add pink noise with 15% of smoothness and amplitude of 12%
	focus.Pink(15).Amplitude(12)

	// Create the timeline
	timeline := builder.
		// Fade in 00:00:00
		SilenceAt(0).
		// Focus preset starts at 00:00:15
		PresetAt(15*time.Second, focus).
		// Focus preset ends at 00:04:30
		PresetAt(4*time.Minute+30*time.Second, focus).
		// Fade out at 00:05:00
		SilenceAt(5 * time.Minute)

	// Load the sequence into memory
	loaded, err := timeline.Load(ctx)
	if err != nil {
		panic(err)
	}

	// Print the spsq sequence
	fmt.Println(string(loaded.RawContent()))

	// Save the sequence as a WAV file
	if err := loaded.WAV("output.wav"); err != nil {
		panic(err)
	}
}

Docs:

• core
• spsq

Contributing

We welcome contributions!

Please read the CONTRIBUTING file for guidelines on how to contribute code, bug fixes, and documentation to the project.

License

SynapSeq is distributed under the GPL v3 or later license. See the COPYING file for details.

Third-Party Licenses

All original code in SynapSeq is licensed under the GNU GPL v3 or later, but the following components are included and redistributed under their respective terms:

• fatih/color
  License: MIT
  Used for colorized terminal output.

• beep
  License: MIT
  Used for audio encoding/decoding.

• golang.org/x/sys
  License: BSD 3-Clause
  Used for platform-specific system integration.

• go-colorable
  License: MIT
  Used indirectly for cross-platform ANSI color support.

• go-isatty
  License: MIT
  Used indirectly for terminal capability detection.

• pkg/errors
  License: BSD 2-Clause
  Used indirectly for error wrapping and stack trace utilities.

All third-party copyright notices and licenses are preserved in this repository in compliance with their original terms.

Contact

We'd love to hear from you! Here's how to get in touch:

Issues (Bug Reports & Feature Requests)

Use GitHub Issues for:

• Bug reports and technical problems
• Feature requests and enhancement suggestions
• Documentation improvements

Discussions (Questions & Community)

Use GitHub Discussions for:

• General questions and support (e.g., "How do I use @extends?")
• Help with your sequences (e.g., "My sequence isn't working, can you help?")
• Sharing your own sequences and presets with the community
• Discussing ideas and best practices
• Showcasing creative use cases

Quick Guidelines

• Found a bug? → Open an Issue
• Want a new feature? → Open an Issue
• Need help or have questions? → Start a Discussion
• Want to share your sequences? → Post in Discussions
• General feedback or ideas? → Start a Discussion

Credits

Check out the CREDITS to see a list of all contributors and special thanks!