README.md

---
title: Neuralis Stem Worker
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# Neuralis Stem Worker

Private Hugging Face Space worker for Neuralis stem separation.

It accepts an uploaded audio file, runs Demucs, and returns a ZIP.

For testing, the browser page defaults to MP3 320 kbps output. WAV output remains available for quality/parity tests.

Available modes:

- `fast-2stem`: returns `vocals` and `instrumental`
- `premium-4stem`: returns `vocals`, `drums`, `bass`, and `other`

The default mode is `fast-2stem` so Neuralis can test quicker AI music vocal enhancement before using the heavier full-stem path.

In `premium-4stem` with WAV output, the ZIP contains:

- `vocals.wav`
- `drums.wav`
- `bass.wav`
- `other.wav`

## Required Secret

Set this in the Hugging Face Space settings:

```text
NEURALIS_STEM_API_KEY
```

The same key must be sent as either:

```text
X-Neuralis-Api-Key: your-key
```

or:

```text
Authorization: Bearer your-key
```

## API

Health:

```text
GET /health
```

Browser/progress workflow:

```text
POST /jobs
GET /jobs/{job_id}
GET /jobs/{job_id}/download
```

Direct separate audio endpoint:

```text
POST /separate
```

Form fields:

- `file`: audio file
- `mode`: optional, `fast-2stem` or `premium-4stem`
- `format`: optional, `wav` or `mp3`
- `model`: optional, defaults to `htdemucs`

The browser page uses `/jobs` so it can show progress while separation is running. `/separate` remains available for direct API callers that want one request returning a ZIP.

## Suggested Hardware

Start on CPU Basic to confirm the app builds, then switch to Nvidia T4 small for real stem separation tests.