> ## Documentation Index
> Fetch the complete documentation index at: https://developer.audioshake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for AudioShakeSeparator and SourceSeparationTask

## AudioShakeSeparator

The core processing class. Takes raw audio buffers in, returns separated stem buffers. Multiple instances can run in parallel; each operates in a single thread.

### Constructor

```cpp theme={null}
AudioShakeSeparator(
    const char*  clientID,
    const char*  clientSecret,
    void*        model,
    unsigned int modelSizeBytes,
    unsigned int inputSamplerate,
    unsigned int flags = useFastestBackend | inputFloat |
                         inputNonInterleaved | outputFloat |
                         outputNonInterleaved | chunkNormal
);
```

| Parameter         | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `clientID`        | Your AudioShake Client ID                                                                          |
| `clientSecret`    | Your AudioShake Client Secret                                                                      |
| `model`           | Pointer to the encrypted model data loaded into memory                                             |
| `modelSizeBytes`  | Size of the model data in bytes                                                                    |
| `inputSamplerate` | Sample rate of input audio in Hz (e.g. `44100`, `48000`). Automatically resampled to match output. |
| `flags`           | Configuration flags — see [Flags](#flags)                                                          |

### Methods

```cpp theme={null}
const char* getInitializationError();  // NULL on success, error string on failure
const char* getBackendName();          // Active backend (e.g. "LiteRT GPU", "Metal", "CPU")
const char* getVersion();              // SDK and model version string
```

```cpp theme={null}
unsigned char getNumberOfStems();
const char*   getStemName(unsigned char stemIndex);
```

```cpp theme={null}
unsigned int getNumberOfChannels();    // Channels per output stem
unsigned int getOutputSamplerate();    // May differ from input
unsigned int getFramesNeeded();        // Frames required per process() call
```

### Processing

```cpp theme={null}
int process(void** inputChannels, unsigned int numInputFrames, void*** outputChannels);
```

* Returns number of output frames produced
* Returns `0` if more input is needed before output is available
* Returns `-1` on error
* Pass `NULL` for `inputChannels` to flush remaining audio (e.g. end of file)
* Mono input is valid — the separator duplicates it across channels

### Reuse

```cpp theme={null}
void prepareForNewContent(unsigned int inputSamplerate, unsigned int flags);
```

Reset internal state to process a new audio source without reconstructing the separator.

***

## SourceSeparationTask

High-level wrapper that manages file reading, writing, and progress callbacks.

### Constructor

```cpp theme={null}
SourceSeparationTask(
    const char*              clientID,
    const char*              clientSecret,
    SourceSeparationInput*   input,
    SourceSeparationOutput*  output,
    const PathStr&           modelPath,
    void*                    model = nullptr,
    unsigned int             modelSizeBytes = 0,
    unsigned int             additionalFlags = 0
);
```

### Processing

```cpp theme={null}
bool run(ProgressCallback cb = nullptr, void* clientData = nullptr);  // Run to completion
bool processOneIteration(ProgressCallback cb = nullptr, void* clientData = nullptr);  // Process one chunk
```

### Status

```cpp theme={null}
double getProgress();          // 0.0–1.0
bool   isFinished();
const char* getErrorMessage(); // NULL on success
```

### Progress callback

```cpp theme={null}
typedef void (*ProgressCallback)(SourceSeparationTask* task, double progress, void* clientData);
```

***

## Input classes

**AudioFileReader** — reads from a file on disk (WAV, MP3, etc.):

```cpp theme={null}
AudioFileReader(const char* filePath);
```

**RingBufferInput** — accepts audio frames from a ring buffer for streaming:

```cpp theme={null}
RingBufferInput(size_t size, bool isStereoInterleaved, int sampleRate);
```

***

## Output classes

**WAVOutput** — writes each stem as a separate WAV file:

```cpp theme={null}
WAVOutput(const char* outputPath);
```

**RingBufferOutput** — exposes stems via a ring buffer:

```cpp theme={null}
RingBufferOutput(size_t size, bool isStereoInterleaved);
```

***

## Flags

Combine with `|`. Pass to `AudioShakeSeparator` or as `additionalFlags` to `SourceSeparationTask`.

### Backend

| Flag                | Description                                   |
| ------------------- | --------------------------------------------- |
| `useFastestBackend` | GPU if available, CPU otherwise. **Default.** |
| `useCPUBackendOnly` | Force CPU-only processing                     |

### Input format

| Flag                     | Description                            |
| ------------------------ | -------------------------------------- |
| `inputFloat`             | 32-bit float. **Default.**             |
| `inputInt16`             | 16-bit signed integer                  |
| `inputNonInterleaved`    | Separate channel buffers. **Default.** |
| `inputInterleavedStereo` | Interleaved stereo                     |

### Output format

| Flag                      | Description                            |
| ------------------------- | -------------------------------------- |
| `outputFloat`             | 32-bit float. **Default.**             |
| `outputInt16`             | 16-bit signed integer                  |
| `outputNonInterleaved`    | Separate channel buffers. **Default.** |
| `outputInterleavedStereo` | Interleaved stereo                     |

### Chunk size

Durations are approximate and vary by model. Smaller chunks reduce latency but increase compute cost.

| Flag          | Approx. duration | Compute cost     |
| ------------- | ---------------- | ---------------- |
| `chunkNormal` | \~3 sec          | 1x. **Default.** |
| `chunk2X`     | \~1.5 sec        | 2x               |
| `chunk4X`     | \~0.75 sec       | 4x               |
| `chunk8X`     | \~375 ms         | 8x               |
| `chunk16X`    | \~185 ms         | 16x              |
| `chunk32X`    | \~92 ms          | 32x              |
| `chunk64X`    | \~46 ms          | 64x              |

### Residual

| Flag                        | Description                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `addResidual`               | Add a residual stem containing audio remaining after subtracting all extracted stems |
| `residualIsInputMinusStem0` | Residual = input minus stem 0                                                        |
| `residualIsInputMinusStem1` | Residual = input minus stem 1                                                        |
| `residualIsInputMinusStem2` | Residual = input minus stem 2                                                        |
| `residualIsInputMinusStem3` | Residual = input minus stem 3                                                        |