# How to Download Audio Only with ReClip: A Complete Guide to MP3 Extraction

> Learn how to download audio only with ReClip. This guide explains how ReClip extracts MP3 audio from videos using yt-dlp for seamless conversion.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-03

---

**ReClip downloads audio-only files by sending a POST request to `/api/download` with `"format": "audio"`, which triggers yt‑dlp with the `-x --audio-format mp3` flags to extract and convert the stream.**

ReClip is a Flask-based wrapper around yt‑dlp that simplifies video and audio downloads through a clean web interface and REST API. When you need just the audio track from a YouTube video or other supported platform, ReClip handles the extraction, conversion, and file delivery automatically. This guide explains exactly how audio-only downloads work in the averygan/reclip repository and provides working code examples for both API and frontend integration.

## How Audio-Only Downloads Work in ReClip

### The Backend Flow: From Request to MP3 File

Audio-only downloads in ReClip follow a specific pipeline defined in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py). When your client sends a download request with `"format": "audio"`, the system executes three distinct phases.

**Phase 1: Request Reception**

The `/api/download` endpoint receives your JSON payload. Inside [`app.py`](https://github.com/averygan/reclip/blob/main/app.py), the `run_download` function inspects the `format` field and constructs the appropriate yt‑dlp command.

**Phase 2: Audio Extraction**

For audio requests, ReClip appends `-x --audio-format mp3` to the yt‑dlp invocation (see [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines 38-40). The `-x` flag tells yt‑dlp to extract audio streams only, discarding video data. The `--audio-format mp3` parameter ensures ffmpeg converts the extracted audio to MP3 format regardless of the source codec.

**Phase 3: File Delivery**

After yt‑dlp and ffmpeg complete, the job status transitions to `"done"`. The `/api/status/<job_id>` endpoint returns metadata including the generated `.mp3` filename. You then retrieve the actual file through `/api/file/<job_id>` (see [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines 99-105).

### Key Files in the Audio Download Pipeline

- **[`app.py`](https://github.com/averygan/reclip/blob/main/app.py)** — Core Flask backend containing `run_download`, `/api/download`, `/api/status/<job_id>`, and `/api/file/<job_id>` endpoints
- **[`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html)** — Frontend template with the MP3 button that sets `"format":"audio"` in requests
- **[`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh)** — Startup script for launching the Flask server
- **[`README.md`](https://github.com/averygan/reclip/blob/main/README.md)** — Documentation covering audio download capabilities

## API Method: Downloading Audio with curl

The most direct way to download audio only with ReClip is through its HTTP API. Below is the complete workflow using curl commands.

### Step 1: Start the Audio Download

Send a POST request to `/api/download` with your target URL and the audio format specified:

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/watch?v=example","format":"audio"}' \
     http://localhost:8899/api/download

```

The response contains a `job_id` for tracking:

```json
{"job_id":"abc123def456"}

```

### Step 2: Poll for Completion

Query the status endpoint until `'status': 'done'` appears:

```bash
curl http://localhost:8899/api/status/abc123def456

```

Example completed response:

```json
{"status":"done","filename":"Video Title-abc123def456.mp3","progress":"100%"}

```

### Step 3: Retrieve the MP3 File

Once completed, download the file with the `-OJ` flags to preserve the original filename:

```bash
curl -OJ http://localhost:8899/api/file/abc123def456

```

### Optional: Fetch Video Info First

To display the title or thumbnail before downloading, call the info endpoint (this step works for both video and audio formats):

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/watch?v=example"}' \
     http://localhost:8899/api/info

```

## JavaScript Method: Downloading Audio in the Browser

For frontend integration, use the Fetch API to orchestrate the same workflow. This implementation matches how [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) interacts with the ReClip backend.

```javascript
async function downloadAudio(url) {
  // Initiate audio-only download
  const start = await fetch('/api/download', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url, format: 'audio' })
  }).then(r => r.json());

  const jobId = start.job_id;

  // Poll status until processing completes
  let status;
  while (true) {
    status = await fetch(`/api/status/${jobId}`).then(r => r.json());
    if (status.status === 'done') break;
    await new Promise(r => setTimeout(r, 1000));
  }

  // Trigger browser download of the MP3
  const link = document.createElement('a');
  link.href = `/api/file/${jobId}`;
  link.download = status.filename;
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
}

```

## Understanding the yt‑dlp Audio Flags

ReClip's audio extraction relies on two specific yt‑dlp parameters you can see in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines 38-40:

| Flag | Purpose |
|------|---------|
| `-x` | **Extract audio** — downloads only audio streams, ignores video |
| `--audio-format mp3` | **Output format** — converts extracted audio to MP3 using ffmpeg |

These flags handle sources with varying codecs (AAC, Opus, Vorbis, etc.) and normalize output to MP3 for maximum compatibility. The conversion happens server-side; your client receives a ready-to-play file.

## Technical Architecture: Why This Design Works

ReClip uses a **job queue pattern** for audio downloads rather than synchronous processing. This approach matters because:

- **yt‑dlp extraction** can take 30-300 seconds depending on video length and server bandwidth
- **ffmpeg conversion** adds additional processing time for format transcoding
- **Flask remains responsive** — the `/api/download` endpoint returns immediately with a job ID

The `run_download` function spawns a background thread that executes yt‑dlp, updates a shared `jobs` dictionary with progress, and marks completion when the MP3 file is ready.

## Summary

- **Audio-only downloads with ReClip** require setting `"format": "audio"` in your POST request to `/api/download`
- **The backend constructs a yt‑dlp command** with `-x --audio-format mp3` flags in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines 38-40
- **ffmpeg handles format conversion** automatically, delivering standardized MP3 files
- **Poll `/api/status/<job_id>`** to track progress and retrieve the filename
- **Fetch the completed file** from `/api/file/<job_id>` once status shows `"done"`
- **Both curl and JavaScript clients** can implement this workflow using the code examples above

## Frequently Asked Questions

### What audio formats does ReClip support?

ReClip outputs MP3 exclusively for audio downloads. The `--audio-format mp3` flag in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) hardcodes this behavior, ensuring consistent cross-platform compatibility. If you need other formats (M4A, WAV, FLAC), you would need to modify the command construction in `run_download` or handle post-processing yourself.

### Can I download audio without the web interface?

Yes. ReClip's REST API accepts requests from any HTTP client. The curl examples above demonstrate pure API usage without opening the browser interface. The [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) frontend is optional — it simply provides a convenient button that sends the same JSON payload with `"format":"audio"`.

### Where are downloaded MP3 files stored?

According to the source code analysis, completed files reside in the `downloads/` directory relative to the Flask application root. The `/api/file/<job_id>` endpoint serves files from this location without exposing the full filesystem path to clients.

### Does ReClip require ffmpeg for audio downloads?

Yes. The `-x` (extract audio) flag in yt‑dlp delegates codec conversion to ffmpeg. Without ffmpeg installed on the server, audio extraction would fail or fall back to the original container format. Ensure ffmpeg is available in your system PATH before running [`reclip.sh`](https://github.com/averygan/reclip/blob/main/reclip.sh) to start the server.