# Output, Metadata & Delivery

This page documents all operations for controlling output format, quality, metadata handling, and delivery behavior.

### Quality

```
q:%quality
```

Sets the output quality as a percentage. Applies to lossy formats like JPEG, WebP, and AVIF. When set to `0`, the quality falls back to the server-side default.

| Parameter | Type    | Default              | Allowed Values |
| --------- | ------- | -------------------- | -------------- |
| quality   | integer | `0` (server default) | 0–100          |

**Examples:**

```
# High quality
q:95

# Good balance of quality and file size
q:80

# Low quality for previews
q:50
```

***

### Format Quality

```
fq:%format1:%quality1:%format2:%quality2:...
```

Sets different quality values per output format. This is useful when you serve images in multiple formats and want different quality levels for each.

| Parameter | Type    | Default | Allowed Values                      |
| --------- | ------- | ------- | ----------------------------------- |
| formatN   | string  | —       | `jpeg`, `webp`, `avif`, `png`, etc. |
| qualityN  | integer | —       | 0–100                               |

The format and quality values are provided as alternating pairs.

**Example:**

```
# JPEG at 80%, WebP at 75%, AVIF at 60%
fq:jpeg:80:webp:75:avif:60
```

***

### Max Bytes

```
mb:%bytes
```

Limits the output file size by automatically reducing quality until the image fits within the specified byte limit. Only works with lossy formats: JPEG, WebP, HEIC, and TIFF.

| Parameter | Type    | Default        | Allowed Values                  |
| --------- | ------- | -------------- | ------------------------------- |
| bytes     | integer | `0` (disabled) | Any positive integer (in bytes) |

{% hint style="warning" %}
**Important:** When `mb` is set, the image may be saved multiple times internally to reach the target size. This increases processing time.
{% endhint %}

**Examples:**

```
# Max 50 KB
mb:51200

# Max 100 KB
mb:102400

# Max 200 KB
mb:204800
```

**Rewrite rule example — bandwidth-optimized thumbnails:**

Regex: `^/small/(.*)` Target: `/_sx/img/_/rs:fit:200:200/mb:20480/plain/$1`

This ensures thumbnails are never larger than 20 KB, regardless of the source image.

***

### Format

```
f:%extension
```

Sets the output image format. If not specified, smoxy uses the source format (falling back to `jpg`).

| Parameter | Type   | Default               | Allowed Values                                                                          |
| --------- | ------ | --------------------- | --------------------------------------------------------------------------------------- |
| extension | string | source format / `jpg` | `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `ico`, `heic`, `bmp`, `tiff`, `pdf`, `svg` |

**Examples:**

```
# Convert to WebP
f:webp

# Convert to AVIF
f:avif

# Convert to PNG (lossless)
f:png
```

**Rewrite rule example — automatic WebP conversion:**

Regex: `^/webp/(.*)` Target: `/_sx/img/_/f:webp/q:80/plain/$1`

{% hint style="warning" %}
**Important:** smoxy already handles automatic format conversion (e.g., to WebP or AVIF) based on what the browser supports. In most cases, you do **not** need to set the format manually — smoxy will serve the best format automatically. Only use this option when you need to enforce a specific output format regardless of browser support.
{% endhint %}

***

### Strip Metadata

```
sm:%strip_metadata
```

Controls whether EXIF, IPTC, XMP, and other metadata is stripped from the output image.

| Parameter       | Type    | Default        | Allowed Values                                       |
| --------------- | ------- | -------------- | ---------------------------------------------------- |
| strip\_metadata | boolean | server default | `1`, `t`, `true` to strip; `0`, `f`, `false` to keep |

**Examples:**

```
# Strip all metadata
sm:1

# Keep metadata
sm:0
```

***

### Keep Copyright

```
kcr:%keep_copyright
```

Preserves copyright-related metadata even when metadata stripping is enabled. Only has an effect when `sm:1` (strip metadata) is active.

| Parameter       | Type    | Default        | Allowed Values                                       |
| --------------- | ------- | -------------- | ---------------------------------------------------- |
| keep\_copyright | boolean | server default | `1`, `t`, `true` to keep; `0`, `f`, `false` to strip |

**Example:**

```
# Strip metadata but keep copyright info
sm:1/kcr:1
```

***

### Strip Color Profile

```
scp:%strip_color_profile
```

Controls whether the embedded ICC color profile is transformed to sRGB and removed. This helps reduce file size while maintaining consistent colors across devices.

| Parameter             | Type    | Default        | Allowed Values                                       |
| --------------------- | ------- | -------------- | ---------------------------------------------------- |
| strip\_color\_profile | boolean | server default | `1`, `t`, `true` to strip; `0`, `f`, `false` to keep |

**Example:**

```
# Strip color profile
scp:1
```

***

### Enforce Thumbnail

```
eth:%enforce_thumbnail
```

When enabled, forces the use of an embedded thumbnail instead of the main image. Currently supports thumbnails embedded in HEIC and AVIF formats only.

| Parameter          | Type    | Default | Allowed Values                                           |
| ------------------ | ------- | ------- | -------------------------------------------------------- |
| enforce\_thumbnail | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

**Example:**

```
eth:1
```

***

### Skip Processing

```
skp:%extension1:%extension2:...
```

Skips all processing for images that match the listed formats. The image is returned as-is. This only works when the requested output format matches the source format.

| Parameter  | Type      | Default | Allowed Values                                     |
| ---------- | --------- | ------- | -------------------------------------------------- |
| extensionN | string(s) | empty   | Any format extension(s): `svg`, `gif`, `png`, etc. |

**Examples:**

```
# Skip processing for SVG and GIF files
skp:svg:gif

# Skip processing for PNG files
skp:png
```

***

### Raw

```
raw:%raw
```

Returns the raw, unprocessed source file directly. All processing operations and checks (type, resolution, file size) are skipped. The file is streamed directly, using less memory than normal processing.

| Parameter | Type    | Default | Allowed Values                                           |
| --------- | ------- | ------- | -------------------------------------------------------- |
| raw       | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

{% hint style="info" %}
**Tip:** Unlike `skp`, the `raw` option works with any file type and doesn't check the source image at all. Use this when you need to serve files as-is through the image manipulation pipeline.
{% endhint %}

**Example:**

```
raw:1
```

***

### Cache Buster

```
cb:%string
```

Does not affect image processing. Its sole purpose is to change the URL so that CDN, proxy, and browser caches are bypassed. Use this when you've changed server-side settings (quality, presets, watermarks) that aren't reflected in the URL itself.

| Parameter | Type   | Default | Allowed Values       |
| --------- | ------ | ------- | -------------------- |
| string    | string | empty   | Any arbitrary string |

**Examples:**

```
# Version-based cache busting
cb:v2

# Date-based cache busting
cb:20250226
```

***

### Expires

```
exp:%timestamp
```

Sets a Unix timestamp after which the URL becomes invalid. smoxy returns a 404 error for expired URLs. This is useful for time-limited image access.

| Parameter | Type    | Default           | Allowed Values |
| --------- | ------- | ----------------- | -------------- |
| timestamp | integer | empty (no expiry) | Unix timestamp |

**Example:**

```
# Expires on January 1, 2026
exp:1767225600
```

***

### Filename

```
fn:%filename:%encoded
```

Sets the filename used in the `Content-Disposition` response header. When not specified, smoxy derives the filename from the source URL.

| Parameter | Type    | Default             | Allowed Values                                     |
| --------- | ------- | ------------------- | -------------------------------------------------- |
| filename  | string  | source URL filename | Escaped string or URL-safe Base64-encoded string   |
| encoded   | boolean | `false`             | `1`, `t`, `true` if the filename is Base64-encoded |

**Example:**

```
fn:product-photo.jpg
```

***

### Return Attachment

```
att:%return_attachment
```

When enabled, sets the `Content-Disposition` header to `attachment`, which triggers a "Save As" dialog in the browser instead of displaying the image.

| Parameter          | Type    | Default | Allowed Values                                           |
| ------------------ | ------- | ------- | -------------------------------------------------------- |
| return\_attachment | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

**Example:**

```
# Force download
att:1
```

**Rewrite rule example — downloadable images:**

Regex: `^/download/(.*)` Target: `/_sx/img/_/att:1/fn:download/plain/$1`

***

### Preset

```
pr:%preset_name1:%preset_name2:...
```

Applies one or more named presets that are configured on the server side. Presets are collections of processing options that can be reused across multiple URLs. Operations set explicitly in the URL override the values from the preset.

| Parameter     | Type      | Default | Allowed Values                |
| ------------- | --------- | ------- | ----------------------------- |
| preset\_nameN | string(s) | empty   | Any configured preset name(s) |

**Example:**

```
# Apply a single preset
pr:thumbnail

# Apply multiple presets
pr:sharp:small
```