StemSplit GitHub Action

Official GitHub Action for StemSplit — AI stem separation and vocal removal from public audio URLs in CI/CD workflows. Isolate vocals, drums, bass, piano, guitar, and other stems via the StemSplit API; optional wait-for-completion and credit balance check.

Run stem separation from a public audio URL inside GitHub Actions workflows.

• Homepage: https://stemsplit.io
• Developer docs: https://stemsplit.io/developers/guides/github-actions
• API reference: https://stemsplit.io/developers/reference
• API base: https://stemsplit.io/api/v1

Usage

Store your API key as a repository secret (STEMSPLIT_API_KEY). Create keys at Settings → API Keys.

Separate stems

jobs:
  separate-stems:
    runs-on: ubuntu-latest
    steps:
      - uses: StemSplit/stemsplit-github-action@v0.1.0
        id: stems
        with:
          api-key: ${{ secrets.STEMSPLIT_API_KEY }}
          source-url: https://example.com/song.mp3
          output-type: FOUR_STEMS
          quality: BEST
          wait: "true"
          timeout-seconds: "600"

      - name: Print download URLs
        run: echo "${{ steps.stems.outputs.result-json }}"

Check credit balance

- uses: StemSplit/stemsplit-github-action@v0.1.0
  id: balance
  with:
    operation: balance
    api-key: ${{ secrets.STEMSPLIT_API_KEY }}

- run: echo "Balance ${{ steps.balance.outputs.balance-formatted }}"

Inputs

Input	Required	Default	Description
operation	No	create-job	create-job or balance
api-key	Yes	—	StemSplit API key (sk_live_...)
source-url	For create-job	—	Public URL to an audio file
output-type	No	BOTH	VOCALS, INSTRUMENTAL, BOTH, FOUR_STEMS, SIX_STEMS
quality	No	BEST	FAST, BALANCED, BEST
output-format	No	MP3	MP3, WAV, FLAC
denoise-vocals	No	false	Run Voice Cleaner on extracted vocals
wait	No	false	Poll until COMPLETED or FAILED
timeout-seconds	No	300	Max wait time when wait is true
api-base-url	No	https://stemsplit.io/api/v1	Override API base (testing)
metadata	No	—	JSON object string for job metadata

Outputs

Output	Description
job-id	Job id (create-job)
status	Job status (create-job)
balance-seconds	Credit balance in seconds (balance)
balance-formatted	Human-readable balance (balance)
result-json	Full API JSON response

When wait is true and the job completes, result-json includes presigned outputs download URLs (expire after one hour).

Development

npm test

License

MIT — see LICENSE.