Extract Audio

The extractAudio recipe pulls the first audio track from a video (or audio-in-video container) and saves it as a standalone file.

Xora probes the input and chooses the best path:

Stream copy when the source codec maps to a web-friendly file extension (fast, no quality loss).
Transcode to your output.format fallback when stream copy is not possible (for example AC-3, DTS, or E-AC-3).

How output format is chosen

After probing, Xora resolves the output file extension:

Source audio codec	Output file	Method
`mp3`	`.mp3`	Stream copy
`aac`	`.aac`	Stream copy
`opus`	`.opus`	Stream copy
`vorbis`	`.ogg`	Stream copy
`flac`	`.flac`	Stream copy
`pcm_*` (for example `pcm_s16le`)	`.wav`	Stream copy
Anything else (for example `ac3`, `dts`, `eac3`)	`.mp3`, `.aac`, or `.wav`	Transcode to `output.format`

The default output key is outputs/{jobId}/result.{ext} where {ext} is the resolved extension above — not always the extension from output.format.

Fallback transcode settings

When transcoding is required, output.format must be one of mp3, aac, or wav:

`output.format`	Encoder	Notes
`mp3` (default if invalid)	`libmp3lame`	Best universal compatibility
`aac`	AAC @ 192 kbps	Smaller than MP3 at similar quality
`wav`	16-bit PCM	Lossless, large files

Basic usage

Request MP3 as the fallback (used only when stream copy is not possible):

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "recipe",
    "input": {
      "url": "https://example.com/interview.mp4"
    },
    "output": {
      "format": "mp3"
    },
    "recipe": {
      "name": "extractAudio"
    }
  }'

const response = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'recipe',
    input: {
      url: 'https://example.com/interview.mp4'
    },
    output: {
      format: 'mp3'
    },
    recipe: {
      name: 'extractAudio'
    }
  })
});
const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.xora.sh/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "mode": "recipe",
        "input": {
            "url": "https://example.com/interview.mp4"
        },
        "output": {
            "format": "mp3"
        },
        "recipe": {
            "name": "extractAudio"
        }
    }
)
data = response.json()
print(data)

Response

{
  "jobId": "01JXYZ1234ABCDEF56789000",
  "state": "queued"
}

When the job completes, check the output file metadata (extension and MIME type) — it reflects the resolved format, which may differ from output.format.

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Must be `"extractAudio"`
`startSeconds`	number	No	Start offset into the input (seconds)
`durationSeconds`	number	No	Maximum duration to extract (seconds)
`stageInput`	boolean	No	Set `false` to stream directly from your URL when the host supports HTTP byte ranges (skips copying the full video to engine storage). Default: `true`. See Input Staging.

Job field	Type	Required	Description
`output.format`	string	Yes	Fallback transcode target: `mp3`, `aac`, or `wav`. Ignored when stream copy applies.

Examples

AAC in MP4 → `.aac` (stream copy)

Input has AAC audio; output.format is only used if copy is impossible:

{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mp4" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" }
}

Completed output: result.aac (not result.mp3).

AC-3 in MKV → `.mp3` (transcode)

Unsupported for stream copy; falls back to output.format:

{
  "mode": "recipe",
  "input": { "url": "https://example.com/movie.mkv" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" }
}

Completed output: result.mp3.

Fast extract (skip staging)

{
  "mode": "recipe",
  "input": { "url": "https://cdn.example.com/video.mp4" },
  "output": { "format": "mp3" },
  "recipe": { "name": "extractAudio" },
  "stageInput": false
}

Transcode fallback to AAC

Use when you know the source needs re-encoding and you prefer AAC over MP3:

{
  "mode": "recipe",
  "input": { "url": "https://example.com/video.mkv" },
  "output": { "format": "aac" },
  "recipe": { "name": "extractAudio" }
}

Custom `outputPath`

If you set outputPath, the file extension must match output.format at request time. The engine still resolves copy vs transcode from the source; prefer the default output key when you want the resolved extension (for example .aac from an AAC source).

Browser and player compatibility

Stream-copied formats vary in HTML5 <audio> support:

Extension	Broad web support	Notes
`.mp3`, `.aac`, `.wav`	Excellent	Safest for universal delivery
`.opus`, `.flac`, `.ogg`	Good on modern browsers	Older Safari / iOS may need a transcode fallback

If you need guaranteed playback everywhere, use a source that transcodes (for example AC-3 → output.format: "mp3") or post-process to MP3.

Common use cases

Scenario	Suggested `output.format`	Typical result
Podcast from video interview	`mp3`	`.aac` or `.mp3` depending on source
Audio for transcription API	`mp3`	`.mp3` if source is AC-3/DTS; else copy
Music from live performance	`aac`	Copy if already AAC/FLAC; else transcode
Audio for further editing	`wav`	`.wav` if PCM source; else transcode to WAV
Voice memo from video	`mp3`	Copy if MP3/AAC; else MP3 transcode

Output formats — format reference and recipe matrix
Input staging — when to set stageInput: false
Transcode — full container/codec conversion (always re-encodes to output.format)