> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Media: yt-dlp Downloads and MVSEP Vocal Separation

> Use Freesona to download video and audio from any yt-dlp supported URL, or separate vocals and instrumentals with MVSEP — all from Discord.

Freesona's media commands let you download video and audio from thousands of platforms, separate vocals from instrumentals with MVSEP's BS Roformer model, run web searches with AI-generated summaries, and solve equations — all without leaving Discord. Downloads are sent directly in the channel as Discord file uploads.

## Video Downloader

Download a video at the best available resolution and receive it directly in the channel.

```text theme={null}
~download https://www.youtube.com/watch?v=example
~dl https://www.youtube.com/watch?v=example
```

The bot tries resolutions in this order and stops at the first file that fits within the upload limit:

| Attempt | Resolution                     |
| ------- | ------------------------------ |
| 1       | 1080p                          |
| 2       | 720p                           |
| 3       | 480p                           |
| 4       | Compressed (re-encoded to fit) |

Audio stream integrity is verified after every merge — if the merged file has no audio track, the bot retries at the next lower resolution automatically.

**Limits and constraints:**

* File size limit: **10 MB** (Discord's free upload limit)
* Per-user cooldown: **30 seconds**
* Requires `ffmpeg` and `yt-dlp` installed on the host machine

### Audio Download

Extract audio from any URL and receive it as an MP3:

```text theme={null}
~audio https://soundcloud.com/artist/track
~mp3 https://www.youtube.com/watch?v=example
```

<Note>
  `~download` and `~audio` both use yt-dlp under the hood, so they support the same wide range of platforms — YouTube, SoundCloud, TikTok, Vimeo, and thousands more.
</Note>

## Audio Separation

Separate vocals and instrumentals from any audio source using MVSEP's **BS Roformer** model (SDR vocals: 11.89 / SDR instrum: 18.20).

```text theme={null}
~separate https://www.youtube.com/watch?v=example
~sep https://soundcloud.com/artist/track
~stems https://example.com/audio.mp3
```

You can also attach an audio file directly to the command message instead of providing a URL.

### Input Options

| Input type       | How to use                                                                            |
| ---------------- | ------------------------------------------------------------------------------------- |
| File attachment  | Attach an audio file to the `~separate` message                                       |
| Direct audio URL | Pass a URL ending in `.mp3`, `.wav`, `.flac`, `.m4a`, `.ogg`, or `.aac`               |
| Platform URL     | Pass any URL supported by yt-dlp — the bot downloads the audio first, then submits it |

### Output

The bot sends an embed with labeled download links once separation is complete:

* **Vocals** — isolated vocal track
* **Instrumental** — music without vocals

Links are hosted by MVSEP and expire after some time. On the free tier, only one job can run at a time — the bot will tell you if a job is already running.

### Setup for Audio Separation

<Steps>
  <Step title="Get an MVSEP API key">
    Sign up at [mvsep.com](https://mvsep.com) and retrieve your API key from your account settings.
  </Step>

  <Step title="Add credentials to .env">
    ```dotenv theme={null}
    MVSEP_API_KEY=your_mvsep_api_key
    MVSEP_WEBHOOK_URL=https://your-public-host.example.com/webhooks/mvsep
    ```

    `MVSEP_WEBHOOK_URL` is optional but recommended — it lets MVSEP notify your bot the moment a job finishes, instead of the bot polling repeatedly.
  </Step>
</Steps>

<Note>
  `MVSEP_WEBHOOK_URL` must be a publicly accessible HTTPS URL that MVSEP can reach. Without it, the bot polls the MVSEP API every 10 seconds and times out after 10 minutes if the job hasn't completed.
</Note>

<Tip>
  Tune polling behavior at runtime with `/config set mvsep_poll_interval <seconds>` and `/config set mvsep_poll_timeout <seconds>` — no restart required.
</Tip>

## Web Search

Search the web and get an AI-generated summary, all in one command:

```text theme={null}
~search latest Python 3.13 features
/search what is the capital of Norway
~s best free vector databases 2024
```

The bot uses Gemini grounding as the primary search path. If grounding is unavailable, it falls back to Google Custom Search.

**Required:** `GOOGLE_API_KEY` in `.env`<br />**Optional (for fallback):** `GOOGLE_SEARCH_API_KEY` and `SEARCH_ENGINE_ID`

## Math Solver

Solve equations and get step-by-step results rendered with LaTeX:

```text theme={null}
~math integrate x^2 from 0 to 3
~math solve x^2 - 5x + 6 = 0
~math derivative of sin(x)*cos(x)
```

The bot queries the Wolfram|Alpha Short Answer API first and falls back to the LLM API for more complex expressions. Results include bolded headers and a LaTeX-rendered image where applicable.

**Required:** `WOLFRAM_APPID_SHORT` in `.env`<br />**Optional:** `WOLFRAM_APPID_LLM` for extended LLM fallback

## Commands Summary

| Command                                      | Description                                 | Requires              |
| -------------------------------------------- | ------------------------------------------- | --------------------- |
| `~download <url>` (alias `~dl`)              | Download video at best available resolution | `ffmpeg`, `yt-dlp`    |
| `~audio <url>` (alias `~mp3`)                | Download audio as MP3                       | `ffmpeg`, `yt-dlp`    |
| `~separate <url>` (aliases `~sep`, `~stems`) | Separate vocals and instrumental            | `MVSEP_API_KEY`       |
| `~search <query>` (alias `~s`)               | Web search with AI summary                  | `GOOGLE_API_KEY`      |
| `~math <equation>`                           | Solve equations via Wolfram\|Alpha          | `WOLFRAM_APPID_SHORT` |

All media commands are available as both prefix (`~download`) and slash (`/download`) commands. There are no permission requirements — anyone in the server can use them.