SynapSeq v4.41.0

[ruanklein]

SynapSeq v4.41.0

SynapSeq v4.41.0 expands how sequences can be created, converted, reviewed, and shared.

This release introduces AI-assisted SPSQ generation with validation and repair, an experimental SBaGen converter, an agent skill suite for creating and auditing sequences, and support for secure self-hosted SynapSeq Remote catalogs.

---

Highlights

AI-Assisted SPSQ Generation

SynapSeq can now generate a validated .spsq sequence from a natural-language prompt through an OpenAI-compatible API.

export SYNAPSEQ_AI_API_KEY="your-api-key"
synapseq -ai "Generate a 10 minute relaxation sequence"

When no output path is supplied, SynapSeq creates a descriptive new .spsq file in the current directory. Supply an output path to choose the destination, or use - to write SPSQ to standard output:

synapseq -ai "Generate a 30 minute study sequence" study-30m.spsq
synapseq -ai "Generate a 20 minute meditation sequence" -

Validation Before Writing

AI output is never written blindly.

Every response is parsed and validated as SPSQ before SynapSeq creates an output file. Invalid responses are returned as errors and existing destination files are never overwritten.

When a model returns invalid SPSQ, SynapSeq automatically sends the validation feedback back to the model and requests a repair, up to two times. Pending requests can be cancelled with Ctrl+C.

For documented English mental-state and profile terms, SynapSeq also validates relevant sound-design constraints such as audible carrier ranges, beat ranges, and profile progression. These checks help keep generated sessions structurally coherent; they do not promise a listener outcome.

OpenAI-Compatible Providers

The AI workflow works with OpenAI and compatible local or remote providers.

export SYNAPSEQ_AI_API_KEY="local-key"
export SYNAPSEQ_AI_MODEL="google/gemma-4-e4b"
export SYNAPSEQ_AI_BASE_URL="http://localhost:1234"
export SYNAPSEQ_AI_TEMPERATURE="0.2"
export SYNAPSEQ_AI_TIMEOUT="90s"

synapseq -ai "Generate a 15 minute focus sequence"

The same settings are available for one command through -ai-model, -ai-base-url, -ai-temperature, and -ai-timeout.

Public Go API

AI generation is also available through the public core package:

ctx := synapseq.NewAppContext()
loaded, err := ctx.AI(context.Background(), "Generate a 10 minute relaxation sequence", &synapseq.AIOptions{
    Model:       "local-model",
    BaseURL:     "http://localhost:1234",
    Temperature: 1,
    Timeout:     90 * time.Second,
})
if err != nil {
    panic(err)
}

content := loaded.RawContent()

AppContext.AI returns an already validated LoadedContext. Library callers provide Temperature and Timeout directly through AIOptions, while model and base URL can use the same optional environment defaults as the CLI. The supplied context.Context controls cancellation.

---

Experimental SBaGen Conversion

SynapSeq can now convert classic SBaGen .sbg sequences into .spsq files.

synapseq -sbg session.sbg
synapseq -sbg session.sbg converted.spsq
synapseq -sbg session.sbg - > converted.spsq

When no destination is given, SynapSeq writes a .spsq file beside the source with the same name. Use - to send converted SPSQ to standard output.

Public sbg Package

The conversion engine is also available as a public Go package for applications that need to import or automate SBaGen migration:

ctx := synapseq.NewAppContext()
converter, err := sbg.New(ctx)
if err != nil {
    panic(err)
}

loaded, err := converter.LoadFile("session.sbg")
if err != nil {
    panic(err)
}

content := loaded.RawContent()

Use converter.LoadContent(sbgContent) when the SBaGen source is already in memory. The returned LoadedContext follows the normal SynapSeq validation and rendering pipeline.

SBaGen conversion is experimental. SBaGen and SynapSeq do not share every sound source, transition behavior, or media capability, so complex files can require review or produce conversion errors. Validate generated output before using it:

synapseq -test converted.spsq

---

SPSQ Skills for AI Coding Agents

v4.41.0 ships a focused skill suite for AI coding agents that work with SPSQ files.

Skill	Purpose
create-spsq	Create a new validated sequence or a new derivative from a reference
explain-spsq	Explain syntax, presets, tracks, transitions, and timeline behavior without modifying files
review-spsq	Audit syntax, semantics, sound structure, and timeline composition without modifying files

Install the suite with the skills CLI:

npx skills add synapseq-foundation/synapseq

The skills have distinct responsibilities. Only create-spsq creates complete sequence files, always at a new path. explain-spsq and review-spsq remain read-only.

Examples for Codex:

$create-spsq Create a 20-minute relaxation sequence with a smooth binaural fade-in and fade-out.
$explain-spsq Explain the presets, tracks, and timeline in focus.spsq.
$review-spsq Audit focus.spsq and report technical, structural, and artistic findings.

---

Custom SynapSeq Remote Catalogs

SynapSeq Remote now supports self-hosted catalogs while keeping the official SynapSeq Remote service as the default.

Sync a custom catalog by passing its root URL:

synapseq -sync-url https://my-sequences.com

Custom catalogs serve their index directly at:

https://my-sequences.com/index.json

Set SYNAPSEQ_REMOTE_BASE_URL to select that catalog for later Remote commands:

export SYNAPSEQ_REMOTE_BASE_URL="https://my-sequences.com"

synapseq -list
synapseq -search focus
synapseq -info calm-state
synapseq -download calm-state
synapseq -get calm-state

Validation and Cache Isolation

Custom Remote URLs must be root HTTP(S) URLs. Paths, credentials, query strings, and fragments are rejected.

Each custom catalog uses an isolated cache directory derived from its host, so it cannot replace or mix with the official Remote cache.

Before caching a custom index, SynapSeq validates its JSON schema, required metadata, IDs, timestamps, durations, and sequence paths. Every downloaded SPSQ file is parsed and validated before it is cached or used by -download, -get, or -info.

This makes it possible to host and share catalogs without weakening the validation guarantees of the normal SynapSeq workflow.

---

Upgrade Notes

• Existing local .spsq files continue to use the same parser and renderer.
• The official SynapSeq Remote service remains the default when no custom Remote URL is configured.
• AI-generated and converted sequences should be reviewed in the same way as any newly created sequence.

---

This discussion was created from the release SynapSeq v4.41.0.