Announcing n8n-nodes-stemsplit: Stem Separation as a Native n8n Node (2026)

fire-and-forget for batch processing.

Architecture Decisions

1. Input Source Selection: The node accepts binary data or public URLs. For files under 50 MB, binary input is convenient. However, for larger files or memory-constrained environments, providing a public URL offloads the transfer to the StemSplit API, reducing n8n memory pressure.
2. Operation Selection:
   • Use Separate Stems (Wait for Completion) when the workflow requires immediate results, such as responding to a user request. The node handles polling internally and returns presigned URLs upon completion.
   • Use Separate Stems combined with Get Job for high-volume batch jobs. This pattern submits jobs instantly and decouples submission from retrieval, allowing n8n to process thousands of items without holding executions open.
3. Output Configuration: The Output Type parameter determines stem granularity. VOCALS and INSTRUMENTAL are standard. FOUR_STEMS adds drums and bass. SIX_STEMS provides piano and guitar isolation but requires Quality: Best. Selecting the appropriate output type balances credit consumption against separation fidelity.

Implementation Pattern 1: Synchronous Vocal Extraction

This pattern demonstrates a user-facing workflow where a webhook triggers stem separation and the result is archived immediately.

Workflow Structure: Webhook Trigger → StemSplit Processor (Wait) → Vocal Downloader

Configuration JSON:

{
  "name": "Vocal Extraction Pipeline",
  "nodes": [
    {
      "parameters": {
        "path": "/extract",
        "httpMethod": "POST",
        "responseMode": "onReceived"
      },
      "name": "AudioWebhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [200, 300]
    },
    {
      "parameters": {
        "operation": "separateStemsWait",
        "inputSource": "url",
        "audioUrl": "={{ $json.body.audioUrl }}",
        "outputType": "VOCALS",
        "quality": "BALANCED",
        "outputFormat": "WAV",
        "timeoutSeconds": 900,
        "pollIntervalSeconds": 10
      },
      "name": "StemSplitProcessor",
      "type": "n8n-nodes-stemsplit.stemSplit",
      "typeVersion": 1,
      "position": [450, 300],
      "credentials": {
        "stemSplitApi": "Production StemSplit Key"
      }
    },
    {
      "parameters": {
        "url": "={{ $json.vocalsUrl }}",
        "responseFormat": "file",
        "options": {}
      },
      "name": "VocalDownloader",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.1,
      "position": [700, 300]
    }
  ],
  "connections": {
    "AudioWebhook": {
      "main": [[{ "node": "StemSplitProcessor", "type": "main", "index": 0 }]]
    },
    "StemSplitProcessor": {
      "main": [[{ "node": "VocalDownloader", "type": "main", "index": 0 }]]
    }
  }
}

Rationale:

• URL Input: The workflow accepts a URL from the webhook payload, avoiding binary transfer overhead in n8n.
• Timeout Tuning: timeoutSeconds is set to 900 to accommodate longer tracks. pollIntervalSeconds is increased to 10 to reduce API call frequency during polling.
• Direct Download: The VocalDownloader consumes the vocalsUrl field directly, ensuring the presigned URL is used before expiration.

Implementation Pattern 2: Asynchronous Batch Processing

For high-volume scenarios, decouple submission from retrieval using database state.

Workflow A: Submission Schedule Trigger → Database Query (Pending) → StemSplit (Fire) → Database Update (Job ID)

Workflow B: Retrieval Schedule Trigger → Database Query (Submitted) → StemSplit (Get Job) → IF (Completed) → Storage Upload → Database Update (Done)

Key Configuration for Workflow A:

• Operation: separateStems
• Input: url
• Result: Returns jobId immediately.

Key Configuration for Workflow B:

• Operation: getJob
• Input: jobId from database.
• Result: Returns status and URLs if completed.

Rationale: This pattern ensures n8n executions remain short-lived. State is persisted in the database, enabling retries, monitoring, and idempotency. Workflow B can run independently, polling for completions without blocking submission throughput.

Pitfall Guide

Production deployments of audio processing workflows must account for API constraints and lifecycle management. The following pitfalls are common in early implementations.

1. Presigned URL Expiration

   • Explanation: StemSplit generates presigned URLs valid for only 1 hour after job completion. Downstream nodes that delay processing or cache URLs will encounter 403 errors.
   • Fix: Download or transfer files immediately upon receiving URLs. Do not store URLs for later use.

2. Credit Consumption Miscalculation

   • Explanation: The credit model deducts 1 credit per second of audio at submission time. Large batches can deplete balances rapidly, causing subsequent jobs to fail with 402 INSUFFICIENT_CREDITS.
   • Fix: Implement a Get Balance check before batch submission. Estimate total credits based on audio duration and pause workflows if balance is low.

3. Quality and Stem Count Mismatch

   • Explanation: The SIX_STEMS output type requires Quality: Best. Submitting SIX_STEMS with lower quality tiers may result in errors or degraded output.
   • Fix: Validate configuration parameters. Ensure quality is set to BEST when requesting six stems.

4. Ephemeral Storage Assumption

   • Explanation: StemSplit retains processed files for 14 days. Relying on these URLs for long-term storage will result in data loss.
   • Fix: Implement downstream archiving to persistent storage (e.g., S3, GCS, or local disk) immediately after download.

5. File Size Limit Violations

   • Explanation: The API enforces a 50 MB maximum file size. Submissions exceeding this limit will fail.
   • Fix: Compress audio or split tracks before submission. Verify file size in the workflow and reject oversized inputs early.

6. Silent Failures on Insufficient Credits

   • Explanation: A 402 error stops the workflow but may not trigger alerts if error handling is not configured.
   • Fix: Wire the error branch of the StemSplit node to a notification service (e.g., Slack, Email) to alert on credit exhaustion.

7. Polling Interval Misconfiguration

   • Explanation: The default polling interval is 5 seconds. For very long tracks, this may generate excessive API calls. Conversely, too long an interval delays result retrieval.
   • Fix: Tune pollIntervalSeconds based on expected processing time. A 10-second interval is often sufficient for multi-minute jobs.

Production Bundle

Action Checklist

• Install n8n-nodes-stemsplit via the Community Nodes UI or npm.
• Create a StemSplit API credential using the sk_live_ key format.
• Run a Get Balance test to verify credential validity and account status.
• Define a storage strategy for processed stems, accounting for the 14-day retention limit.
• Configure error handling on the StemSplit node to capture 402 and timeout errors.
• Set timeoutSeconds based on maximum expected audio duration.
• Validate Output Type and Quality compatibility before batch submissions.
• Implement immediate download or transfer of presigned URLs to avoid expiration.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Real-time user request	Separate Stems (Wait)	Provides immediate feedback; simplifies workflow logic.	Higher execution time cost; blocks concurrency.
Nightly batch processing	Separate Stems + Get Job	Decouples submission; enables high throughput; state persists in DB.	Lower execution cost; requires DB maintenance.
Memory-constrained environment	Input via URL	Offloads file transfer to API; reduces n8n memory usage.	No direct cost impact; improves stability.
High-fidelity separation	SIX_STEMS + Quality: Best	Maximizes stem isolation; required for six-stem output.	Higher credit consumption per second.

Configuration Template

Use this template as a base for a robust StemSplit node configuration. Adjust parameters based on your specific requirements.

{
  "parameters": {
    "operation": "separateStemsWait",
    "inputSource": "url",
    "audioUrl": "={{ $json.sourceUrl }}",
    "outputType": "FOUR_STEMS",
    "quality": "BALANCED",
    "outputFormat": "MP3",
    "timeoutSeconds": 600,
    "pollIntervalSeconds": 8
  },
  "type": "n8n-nodes-stemsplit.stemSplit",
  "typeVersion": 1,
  "credentials": {
    "stemSplitApi": "Your Credential Name"
  }
}

Notes:

• Replace audioUrl with your dynamic input expression.
• Set outputType to VOCALS, INSTRUMENTAL, BOTH, FOUR_STEMS, or SIX_STEMS.
• Ensure quality matches outputType constraints.
• Adjust timeoutSeconds to prevent premature termination.

Quick Start Guide

1. Install the Node: Navigate to Settings → Community Nodes in n8n, search for n8n-nodes-stemsplit, and install.
2. Add Credential: Create a new credential of type StemSplit API and paste your sk_live_ key.
3. Create Workflow: Add a StemSplit node to a new workflow. Select Separate Stems (Wait for Completion).
4. Configure Input: Set inputSource to url and provide a test audio URL. Set outputType to VOCALS.
5. Execute: Run the workflow. Verify that the node returns vocalsUrl and that the URL is accessible within the 1-hour window.