# Clip video and convert to animations

> Use range syntax in frame to clip videos and extract segments of animated images, and convert between video and animated images.

Besides selecting a single frame, `frame` accepts a **range** to select a segment of content. Combined with `fmt`, it supports four operations:

| Source         | Output format                                     | Operation                                  |
| :------------- | ------------------------------------------------- | ------------------------------------------ |
| Video          | `mp4` / `mov`, or not specified                   | **Clip video**                             |
| Video          | `gif` / `webp` / `avif` / `png`                   | **Convert video to animated image**        |
| Animated image | `gif` / `webp` / `avif` / `png`, or not specified | **Extract a segment of an animated image** |
| Animated image | `mp4` / `mov`                                     | **Convert animated image to video**        |

## Range syntax

Format: `start:end`. Separate multiple segments with commas; they are joined in order.

| Source         | Unit                          | Range bounds                   |
| :------------- | ----------------------------- | ------------------------------ |
| Video          | Milliseconds                  | Start inclusive, end exclusive |
| Animated image | Frame number, starting from 1 | Start and end both inclusive   |

| Syntax               | Video                                   | Animated image                           |
| :------------------- | --------------------------------------- | ---------------------------------------- |
| `3000:8000`          | From 3 s to 8 s                         | –                                        |
| `1:10`               | –                                       | Frames 1 through 10                      |
| `:5000`              | From the start to 5 s                   | From the start to frame 5000             |
| `-3000:`             | The last 3 seconds                      | From the 3000th-to-last frame to the end |
| `-5:`                | The last 5 milliseconds                 | The last 5 frames                        |
| `0:2000,10000:12000` | Two segments joined, 4 seconds in total | –                                        |

- A **negative** value counts back from the end. **Omitting the start** means from the beginning; **omitting the end** means through to the end.
- If the end exceeds the actual length, it is clamped to the end. If the start exceeds the actual length, an error is returned.
- Up to 20 segments.

## Clip video

<https://example.com/video.mp4?frame=3000:8000>

- Frame-accurate, with audio trimmed in sync.
- You can also use `w`, `h`, watermark, and other parameters at the same time.
- The output duration (the sum of all segments) can be at most 60 seconds; the source video can be at most 100 MB.

## Convert video to animated image

<https://example.com/video.mp4?frame=0:3000&fmt=gif&w=320>

| Parameter | Description                                                                                                 | Default |
| :-------- | ----------------------------------------------------------------------------------------------------------- | :-----: |
| `fps`     | **Frame rate**. Must be lower than the source video's frame rate                                            |    15   |
| `w`, `h`  | **Dimensions**. If not specified, the long edge is capped automatically: 480 for GIF, 720 for other formats |    –    |

- The total selected duration can be at most 30 seconds.
- HDR video is automatically converted to SDR.
- All image parameters, such as resize, crop, watermark, and quality, are supported.

## Extract a segment of an animated image

<https://example.com/anim.gif?frame=1:10>

The output is still an animated image. You can use `fmt` at the same time to convert the format.

## Convert animated image to video

<https://example.com/anim.gif?fmt=mp4>

- Without `frame`, the entire animation is converted; with a range, only the selected frames are converted.
- Each frame is displayed for the same duration as in the original animation.
- The default codec is H.264. Use `vcodec=hevc` to switch to HEVC.

## Animation playback parameters

The following parameters apply to animated image output:

| Parameter  | Description                                                                                                               | Values      |
| :--------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `loop`     | **Play count**. `0` loops forever. Not supported for AVIF                                                                 | 0 \~ 65535  |
| `reverse`  | **Reverse playback**                                                                                                      | `1`         |
| `skip`     | **Frame dropping**: for every frame kept, drop the next N frames. Total duration stays the same while file size decreases | 0 \~ 100    |
| `interval` | **Uniform frame duration** in milliseconds, used to change playback speed                                                 | 10 \~ 60000 |

<https://example.com/anim.gif?skip=1&fmt=webp>
