🎉 SynapSeq v4.0.0 Released!

[ruanklein]

SynapSeq v4.0.0 - A Simpler, More Powerful Core

SynapSeq 4.0.0 is a major evolution of the project.

This release focuses on simplifying the architecture, improving composability, and expanding the expressive power of SPSQ, without losing the original goal: building deterministic brainwave sessions using plain text.

---

✨ What's New (Quick Overview)

• Multi-layer ambiance with @ambiance
• Modular composition with @extends
• Unified and expanded effects system
• New Doppler effect for tone tracks
• Noise smoothing (smooth)
• Visual HTML preview (-preview)
• Built-in manual (-manual)
• Starter templates (-new)
• Cleaner CLI and better error messages
• Removal of legacy complexity (tracking, multiple formats, embedded
  metadata)

---

🎧 Multi-Layer Ambiance

SynapSeq now supports multiple background audio layers using the new
@ambiance option.

@ambiance rain nature/rain
@ambiance river nature/river
@ambiance music music/music1

alpha
  ambiance rain amplitude 5
  ambiance river amplitude 10
  ambiance music amplitude 20

This allows you to create layered sound environments by mixing multiple
audio sources --- local or remote.

Ambiance is not meant to replace the core signal (tone/noise), but to
complement it.

Think of it as a controllable environmental layer that supports the main
brainwave structure.

WAV Size Limit

The maximum WAV file size has been increased from 10MB to 20MB,
enabling longer and more natural background audio.

---

🧩 Modular Sequences with @extends

The new @extends option allows you to split sequences into reusable
modules.

@extends common/options
@extends presets/relaxation

This makes it possible to:

• separate global options (samplerate, ambiance definitions)
• reuse preset libraries across multiple sessions
• keep large sequences clean and maintainable

SynapSeq now encourages modular composition instead of monolithic
files.

---

🎛️ Effects System (Reworked and Expanded)

Effects have been redesigned and are now available for all track types:

• tone
• noise
• ambiance

This allows more expressive sessions and reduces listener fatigue during
long playback.

---

🌌 New Effect: Doppler (Tone Only)

A new doppler effect has been introduced for tone tracks.

alpha
  tone 300 effect doppler 10 intensity 100 amplitude 20

It simulates motion and can increase perceived immersion and attention.

With binaural:

alpha
  tone 300 binaural 10 effect doppler 10 intensity 25 amplitude 30

Use carefully --- excessive motion can become distracting.

---

🔄 Pan and Modulation

Two core effects are now standardized:

• pan → stereo movement (left ↔ right)
• modulation → amplitude modulation (AM)

Both can be used with tone, noise, and ambiance tracks.

---

🌊 Noise Smoothing (smooth)

A new smooth parameter allows shaping the texture of noise:

alpha
  noise pink smooth 50 amplitude 30

• Lower values → sharper, more energetic noise\
• Higher values → softer, more diffuse noise

Default behavior remains smooth 0, preserving compatibility with
previous versions.

---

🧰 CLI Improvements

-new

Generate starter templates:

• meditation
• focus
• sleep
• relaxation
• example

These templates help users learn the syntax and start building sessions
quickly.

---

-preview

Generates an HTML visualization of the sequence timeline.

This makes it easier to understand:

• transitions
• parameter changes
• structure over time

Especially useful for users who prefer visual feedback.

---

-manual

Displays the full SynapSeq manual directly in the terminal.

No need to leave the CLI.

---

🎵 MP3 Export Simplified

The -mp3 flag has been removed.

To export MP3, simply use:

output.mp3

---

🖥️ CLI Experience Improvements

Color Output

SynapSeq now includes colorized output for better readability.

Disable with:

-no-color

---

Improved Error Messages

Error messages are now precise and actionable:

synapseq: file.spsq:5:12: unexpected token
  tone 200 binaura 5 amplitude 50
                  ^^^^^^
found: "binaura"
expected: "binaural", "monaural", "isochronic", "effect", or "amplitude"
did you mean "binaural"?

---

🧠 Updated Positioning

SynapSeq is now described as:

Text-Driven Audio Sequencer for Brainwave Entrainment

This better reflects what the system actually does:
a deterministic interpreter for building structured audio sessions from
text.

---

⚠️ Breaking Changes

@background Removed

Replaced by @ambiance.

@presetlist Removed

Replaced by @extends.

@gainlevel Removed.

---

Effect Renaming

• spin → pan
• pulse → modulation

More accurate naming and behavior.

---

Path Restrictions

SynapSeq now enforces self-contained projects:

• no parent directory traversal\
• no arbitrary absolute paths

---

Automatic File Extensions

• @ambiance → .wav\
• @extends → .spsc

You no longer need to specify extensions.

---

New File Type: .spsc

Used for modular sequence components loaded via @extends.

---

🔄 Project Simplification

Several features were removed to reduce complexity and focus on the core
system:

Removed

• Hub tracking\
• Hub website\
• JSON / XML / YAML support\
• SPSQ embedding in audio files

Why?

Because they added maintenance cost without meaningful usage.

SynapSeq is now focused on:

• CLI
• SPSQ format
• deterministic audio generation

---

🌐 Website Changes

• New website focused on SynapSeq CLI
• Playground removed\
• WASM version now includes a minimal editor (example.html)

---

🎯 Final Thoughts

SynapSeq v4 is not just an update --- it's a refinement of the original
idea.

• fewer moving parts
• more expressive power
• clearer mental model

The goal remains the same:

build precise, repeatable brainwave sessions using text

But now, the system is simpler, more modular, and more consistent.

---

If you have feedback, questions, or ideas --- feel free to share them.

[XenoxYT]

Will the custom waveforms get implemented next (Would be a great addition to the new ambiance system, like using a custom modulation waveform on a custom noise)?

[ruanklein]

Will the custom waveforms get implemented next (Would be a great addition to the new ambiance system, like using a custom modulation waveform on a custom noise)?

As mentioned in another discussion, there are still some refinements needed around syntax and constraints. The goal is to ensure that, if implemented, it remains both powerful and easy to use and understand.

That said, it’s not off the table. I’m currently evaluating whether this feature provides meaningful benefits beyond existing capabilities, rather than just adding complexity.