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

# Advanced Options

> Audio extraction, resolution selection, video clipping, and live stream recording

## Overview

Tornado supports advanced download options including audio-only extraction, resolution selection, video clipping, and live stream recording.

## Audio-Only Extraction

Extract just the audio track from any video. By default, the audio is saved as `m4a` (native AAC from YouTube) with no re-encoding for maximum quality and speed.

### Default (m4a, no re-encoding)

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "audio_only": true
  }'
```

### MP3 Output

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "audio_only": true,
    "format": "mp3",
    "audio_bitrate": "320k"
  }'
```

### Audio Formats

| Format | Codec | Re-encoding | Notes                                   |
| ------ | ----- | ----------- | --------------------------------------- |
| `m4a`  | AAC   | No          | Default. Native YouTube format, fastest |
| `mp3`  | MP3   | Yes         | Universal compatibility                 |
| `ogg`  | Opus  | Yes         | Smaller files, great quality            |
| `opus` | Opus  | Yes         | Same as ogg                             |

<Tip>
  Use `m4a` (default) for the fastest processing since it skips re-encoding entirely. Use `mp3` only if you need broad device compatibility.
</Tip>

<Note>
  `audio_only` can be combined with `clip_start`/`clip_end` to extract a specific audio segment, and with `audio_bitrate` to control output quality.
</Note>

## Resolution Selection

Limit the maximum video resolution to reduce file size and download time.

### Available Resolutions

| Value  | Resolution | Landscape                   | Portrait (Shorts) |
| ------ | ---------- | --------------------------- | ----------------- |
| `best` | Maximum    | Highest available (default) | Highest available |
| `2160` | 4K UHD     | 3840x2160                   | 2160x3840         |
| `1440` | 2K QHD     | 2560x1440                   | 1440x2560         |
| `1080` | Full HD    | 1920x1080                   | 1080x1920         |
| `720`  | HD         | 1280x720                    | 720x1280          |
| `480`  | SD         | 854x480                     | 480x854           |
| `360`  | Low        | 640x360                     | 360x640           |

<Note>
  `max_resolution` checks the **shorter dimension** of the video. This means `1080` correctly keeps both 1920x1080 landscape videos and 1080x1920 vertical videos (YouTube Shorts), while filtering out anything above 1080p in either orientation.
</Note>

### Example

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "max_resolution": "720"
  }'
```

<Note>
  If the requested resolution is not available, Tornado downloads the next best available quality.
</Note>

## Video Clipping

Extract a specific segment from a video using start and end timestamps.

### Timestamp Formats

Both formats are supported:

* `HH:MM:SS` - Hours, minutes, seconds (e.g., `01:30:45`)
* Seconds - Raw seconds (e.g., `5445`)

### Examples

```bash theme={null}
# Extract 1:30 to 3:00
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_start": "00:01:30",
    "clip_end": "00:03:00"
  }'
```

```bash theme={null}
# Extract first 60 seconds
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_start": "0",
    "clip_end": "60"
  }'
```

```bash theme={null}
# Extract from 5 minutes to end
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_start": "00:05:00"
  }'
```

<Warning>
  `clip_end` must be greater than `clip_start`. Invalid timestamps will return a 400 error.
</Warning>

## Live Stream Recording

Record ongoing YouTube or Twitch live streams.

### Parameters

| Parameter         | Type    | Description                             |
| ----------------- | ------- | --------------------------------------- |
| `live_recording`  | boolean | Enable live stream mode                 |
| `live_from_start` | boolean | Record from stream beginning (VOD mode) |
| `max_duration`    | integer | Maximum recording duration in seconds   |
| `wait_for_video`  | boolean | Wait for scheduled streams to start     |

### Basic Live Recording

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/live/abc123",
    "live_recording": true,
    "max_duration": 3600
  }'
```

### Record from Start (VOD Mode)

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/live/abc123",
    "live_recording": true,
    "live_from_start": true,
    "max_duration": 7200
  }'
```

### Wait for Scheduled Stream

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=scheduled_stream_id",
    "live_recording": true,
    "wait_for_video": true,
    "max_duration": 3600
  }'
```

<Tip>
  Always set `max_duration` for live streams to prevent indefinite recordings. Recommended: 2-4 hours maximum.
</Tip>

## Combining Options

You can combine multiple options in a single request:

```bash theme={null}
curl -X POST "https://api.tornadoapi.io/jobs" \
  -H "x-api-key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "max_resolution": "1080",
    "clip_start": "00:00:30",
    "clip_end": "00:02:00",
    "format": "mp4",
    "webhook_url": "https://myapp.com/webhook",
    "enable_progress_webhook": true
  }'
```

## Error Handling

### Invalid Resolution

```json theme={null}
{
  "error": "Invalid resolution '4k'. Valid options: [\"best\", \"2160\", \"1440\", \"1080\", \"720\", \"480\", \"360\"]"
}
```

### Invalid Timestamps

```json theme={null}
{
  "error": "Invalid clip_start format 'abc'. Use HH:MM:SS or seconds"
}
```

```json theme={null}
{
  "error": "clip_end must be greater than clip_start"
}
```