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

# Video Transformations

> Transcode, trim, and stream adaptive HLS video dynamically.

Dreep uses a proprietary, high-performance video engine to transform video on the fly. You can combine query parameters to adjust dimensions, re-encode video formats, adjust frame rates, trim clips, or convert videos into animated GIFs.

## Inline vs. Asynchronous Processing

* **Fast Jobs (Inline 200 OK):** Lightweight operations like container remuxing (e.g. `MOV` → `MP4` stream copy) are processed quickly inline and served immediately with a `200 OK`.
* **Heavy Jobs (Async 202 Accepted):** Intensive operations (like full H.264/VP9 re-encodes, HLS segmentation, or GIF conversion) run asynchronously in the background.

### How Asynchronous Processing Works:

1. **First Request:** You request a heavy video transformation (e.g., `?format=webm&fps=30`).
2. **Dreep Responds:** Dreep queues the job and responds with an HTTP `202 Accepted` status code.
   * If requested by a browser (`Accept: text/html`), Dreep serves a "Processing" page with a loading spinner that automatically refreshes.
   * If requested via an API client (`Accept: application/json`), Dreep returns `{ "error": "Asset is processing" }`.
3. **Completion:** Once the background worker finishes, subsequent requests to that exact URL return `200 OK` and serve the transformed video file directly from cache.

***

## 1. Dimensions, Fit & Quality

Control output resolution, aspect ratio scaling, and visual quality.

| Parameter | Valid Options              | Description                                              | Try It                              |
| :-------- | :------------------------- | :------------------------------------------------------- | :---------------------------------- |
| `width`   | number                     | Target width in pixels.                                  | `?width=1280`                       |
| `height`  | number                     | Target height in pixels.                                 | `?height=720`                       |
| `fit`     | `cover`, `contain`, `fill` | Scaling behavior when both `width` and `height` are set. | `?width=640&height=360&fit=contain` |
| `quality` | 1 - 100                    | Encoding quality / CRF scaling (1-100). Defaults to 80.  | `?quality=75`                       |

**Example:**
Resize a video to 720p HD with aspect-ratio containment:

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?width=1280&height=720&fit=contain&quality=80
```

***

## 2. Trimming & Clipping

You can extract a specific portion of a video by defining start and end timestamps.

| Parameter   | Description                 | Try It          |
| :---------- | :-------------------------- | :-------------- |
| `trimStart` | Start timestamp in seconds. | `?trimStart=10` |
| `trimEnd`   | End timestamp in seconds.   | `?trimEnd=25`   |

**Example:**
Extract a 15-second clip starting at the 10-second mark:

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?trimStart=10&trimEnd=25
```

***

## 3. Formatting & Codecs

Convert videos to different web-optimized formats or codecs. Supported source video formats include **MP4**, **MOV**, and **WebM**.

| Parameter    | Valid Options                              | Description                                                                     | Try It             |
| :----------- | :----------------------------------------- | :------------------------------------------------------------------------------ | :----------------- |
| `format`     | `mp4`, `webm`, `mov`, `gif`, `hls`, `m3u8` | The output container format.                                                    | `?format=webm`     |
| `videoCodec` | `libx264`, `libvpx-vp9`, `h264`, `hevc`    | The internal video encoding codec. Defaults to web-optimized H.264 (`libx264`). | `?videoCodec=hevc` |
| `fps`        | number (e.g., `24`, `30`, `60`)            | Output frame rate.                                                              | `?fps=30`          |

<Note>
  **Conversion Boundaries**: Video conversions must remain within video formats
  (`mp4`, `webm`, `mov`), HLS (`hls`, `m3u8`), or animated `gif`. If you request
  an image format (like `jpeg` or `webp`) on a video asset, Dreep will extract a
  static thumbnail frame.
</Note>

**Example: Converting Video to Animated GIF**
You can easily create GIF previews of your videos. It is highly recommended to use `trimStart` and `trimEnd` alongside `fps` when generating GIFs to keep the file size manageable.

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.gif?trimStart=0&trimEnd=3&fps=12
```

***

## 4. HLS Adaptive Streaming

For large videos, serving a single massive `.mp4` file is inefficient. Dreep supports **HTTP Live Streaming (HLS)**, which chunks your video into smaller `.ts` segments and generates an `.m3u8` manifest file.

This allows players to stream the video smoothly and buffer only what is needed.

To generate an HLS stream, request the video with `format=hls` or append the `.m3u8` extension:

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.m3u8
```

### Implementing an HLS Player

Standard HTML5 `<video>` tags do not support HLS natively in all browsers (Safari does, but Chrome/Firefox do not). You must use a library like [HLS.js](https://github.com/video-dev/hls.js/) or [Video.js](https://videojs.com/).

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>
<script>
  var video = document.getElementById("video");
  var videoSrc = "https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.m3u8";

  if (Hls.isSupported()) {
    var hls = new Hls();
    hls.loadSource(videoSrc);
    hls.attachMedia(video);
  } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
    // Safari fallback
    video.src = videoSrc;
  }
</script>
```

<Note>
  Like all video transformations, requesting `.m3u8` for the first time will
  trigger a `202 Accepted` response while the video is chunked and the manifest
  is generated.
</Note>

***

## 4. Audio Extraction

Because it does not require a full video re-encode, Dreep can extract audio tracks from your video assets at lightning speeds (often returning in under 200ms).

To strip the video track and return just the audio, simply request one of our supported audio formats (`mp3`, `wav`, or `aac`).

**Supported Audio Formats:**

* `mp3`: Highly compressed, great for general web usage.
* `wav`: Uncompressed lossless audio for professional use.
* `aac`: High-quality compressed audio format.

**Example: Extract MP3 Audio**

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?format=mp3
```

**Example: Extract WAV Audio**

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?format=wav
```

***

## 5. Thumbnail Extraction

To generate a static thumbnail image from your video, simply request a supported image format (`jpeg`, `jpg`, `png`, or `webp`) and use the `time` parameter to specify the exact timestamp (in seconds) to capture. If `time` exceeds the video's actual duration, Dreep intelligently clamps it to the final frame.

**Supported Thumbnail Formats:**

* `jpeg` or `jpg`: Standard compressed image format, highly compatible.
* `webp`: Modern web format with superior compression.
* `png`: Lossless image format, good for high fidelity.

**Example: Extract a JPEG Thumbnail at 5 seconds**

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?format=jpeg&time=5
```

*(You can also use `.jpg` or `format=jpg` interchangeably with `jpeg`!)*

**Example: Extract a WebP Thumbnail at 15 seconds**

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?format=webp&time=15
```

***

## Combining Parameters

You can chain multiple video parameters together in a single request:

```text theme={null}
https://cdn.dreep.cloud/api/v1/fetch/2f928a3f.mp4?width=1280&height=720&trimStart=5&trimEnd=20&fps=30&quality=85
```