> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-audio-sdk-and-neural-dsp.md).

# SONIC Audio SDK & Neural DSP

Preview TypeScript SDK contract for SONIC audio processing, neural DSP workflows, stem decomposition, high-resolution audio output and secure server-side API access.

**Status:** `Preview / MVP`

The SONIC Audio SDK is the proposed TypeScript client for high-resolution audio-processing workflows such as stem decomposition, analysis and creator-tool integrations.

> **MVP disclaimer** — Package names, DSP model versions, supported sample rates, output formats and performance characteristics remain subject to release validation. Documentation must not present an unverified latency figure or unsupported format as a production guarantee.

## Package

```bash
npm install @sonic/audio-sdk
```

The package name above is the canonical planned SDK namespace for this contract. Treat it as **Preview** until the package is published and explicitly promoted to `Live`.

## Initialize the client

```ts
import { SonicAudioEngine } from '@sonic/audio-sdk';

const sonic = new SonicAudioEngine({
  apiKey: process.env.SONIC_API_KEY,
  cluster: 'mainnet-beta',
});
```

`SONIC_API_KEY` is server-side application credential material. Do not expose it in browser bundles, public source maps, client-side environment variables or mobile application logs.

The `cluster` field identifies the SONIC/Solana environment used by the surrounding workflow. It does **not** imply that DSP inference itself executes on-chain.

## Decompose a master into stems

```ts
const stems = await sonic.dsp.decomposeStems({
  audioUrl: 'https://arweave.net/sonic-track-04.wav',
  stems: ['vocals', 'drums', 'bass', 'synths'],
  format: 'wav_24bit',
});

console.log(stems.map((stem) => stem.stemId));
```

The operation requests four isolated stems while preserving a lossless/high-resolution WAV output profile where supported by the active DSP backend.

### Request shape

| Field      | Type       | Meaning                               |
| ---------- | ---------- | ------------------------------------- |
| `audioUrl` | `string`   | Publicly retrievable source audio URL |
| `stems`    | `string[]` | Requested isolated stem classes       |
| `format`   | `string`   | Requested output encoding/profile     |

Public URL ingestion must follow the SONIC URL-safety contract: scheme validation, DNS/IP checks, redirect validation, bounded fetches and content validation.

See **Upload & Cover URL validation** for the shared ingestion boundary.

## Response model

A successful SDK call should normalize provider output into durable SONIC stem records rather than exposing provider-specific payloads directly.

```ts
type SonicStem = {
  stemId: string;
  kind: 'vocals' | 'drums' | 'bass' | 'synths' | string;
  audioUrl: string;
  format: string;
  sampleRateHz?: number;
  bitDepth?: number;
  durationMs?: number;
};
```

Optional technical fields are returned only when they are actually verified for the generated asset.

## 96 kHz and 24-bit terminology

`96 kHz` describes sample rate. `24-bit` describes bit depth. They are separate properties and must not be collapsed into one marketing label.

If a released DSP model supports 96 kHz output, the SDK/API should expose that capability explicitly through request/response metadata. A comment such as `96kHz Neural DSP Client` must not imply a fixed output rate unless the active contract guarantees it.

Likewise, `wav_24bit` should be treated as a requested output profile. The service should reject unsupported formats or return the verified effective format rather than silently transcoding to a different representation.

## Performance claims

Do **not** publish code such as:

```ts
console.log('Stems isolated in 12ms');
```

unless `12ms` is derived from measured runtime telemetry for that specific operation and environment.

Preferred pattern:

```ts
const startedAt = performance.now();
const stems = await sonic.dsp.decomposeStems(request);
const elapsedMs = performance.now() - startedAt;

console.log(`Stem decomposition completed in ${elapsedMs.toFixed(0)}ms`);
```

Documentation should describe latency as measured/observed, not as an unconditional SDK guarantee.

## Solana boundary

Do not import `Connection` or `Keypair` unless the example actually performs a Solana operation.

Audio DSP and blockchain responsibilities remain separate:

```
Audio source
   ↓
SONIC Audio SDK
   ↓
DSP operation
   ↓
normalized stem assets
   ↓
Project / Studio state
   ↓
optional Solana transaction workflow
```

When a later workflow writes provenance, ownership, payment or settlement state to Solana, use the normal SONIC transaction-intent path. A DSP result alone never authorizes a wallet transaction.

## Security requirements

The SDK must never expose or log:

* SONIC API secrets;
* Solana private keys or seed phrases;
* provider credentials;
* privileged model configuration;
* internal storage credentials;
* raw server exception traces.

Public audio URLs are untrusted input and must be validated server-side before provider dispatch.

## Operation lifecycle

Long-running DSP jobs should use the same durable operation model as generation:

```
request
→ validate
→ create/recover idempotent operation
→ reserve credits where applicable
→ dispatch DSP work
→ merge provider progress
→ persist normalized stem assets
→ settle or release credits
→ reconcile
```

A client timeout does not prove the DSP job failed. Recover by durable operation identity rather than creating a second provider job.

## Recommended production example

```ts
import { SonicAudioEngine } from '@sonic/audio-sdk';

const sonic = new SonicAudioEngine({
  apiKey: process.env.SONIC_API_KEY,
  cluster: 'mainnet-beta',
});

const startedAt = performance.now();

const stems = await sonic.dsp.decomposeStems({
  audioUrl: 'https://arweave.net/sonic-track-04.wav',
  stems: ['vocals', 'drums', 'bass', 'synths'],
  format: 'wav_24bit',
});

const elapsedMs = performance.now() - startedAt;

console.log({
  elapsedMs: Math.round(elapsedMs),
  stemIds: stems.map((stem) => stem.stemId),
});
```

This example avoids unused blockchain imports and avoids presenting a benchmark as a guaranteed runtime characteristic.

## Related contracts

* **Generation operations** — durable AI/provider operation lifecycle.
* **Credits lifecycle** — reserve, settle and release semantics.
* **Upload & Cover URL validation** — public URL ingestion controls.
* **Errors, decimals & transactions** — normalized errors and transaction boundaries.
* **Wallet, transaction intents & Solana Pay** — optional value-moving/on-chain workflows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-audio-sdk-and-neural-dsp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.