# Ausgabe, Metadaten & Auslieferung

Diese Seite dokumentiert alle Operationen zur Steuerung von Ausgabeformat, Qualität, Metadaten und Auslieferungsverhalten.

### Quality

```
q:%quality
```

Setzt die Ausgabequalität als Prozentwert. Gilt für verlustbehaftete Formate wie JPEG, WebP und AVIF. Bei `0` wird der serverseitige Standardwert verwendet.

| Parameter | Typ     | Standard              | Erlaubte Werte |
| --------- | ------- | --------------------- | -------------- |
| quality   | integer | `0` (Server-Standard) | 0–100          |

**Beispiele:**

```
# Hohe Qualität
q:95

# Gute Balance zwischen Qualität und Dateigröße
q:80

# Niedrige Qualität für Vorschauen
q:50
```

***

### Format Quality

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

Setzt unterschiedliche Qualitätswerte pro Ausgabeformat. Nützlich, wenn Bilder in mehreren Formaten ausgeliefert werden und für jedes Format unterschiedliche Qualitätsstufen gewünscht sind.

| Parameter | Typ     | Standard | Erlaubte Werte                     |
| --------- | ------- | -------- | ---------------------------------- |
| formatN   | string  | —        | `jpeg`, `webp`, `avif`, `png` usw. |
| qualityN  | integer | —        | 0–100                              |

Format- und Qualitätswerte werden als abwechselnde Paare angegeben.

**Beispiel:**

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

***

### Max Bytes

```
mb:%bytes
```

Begrenzt die Ausgabedateigröße, indem die Qualität automatisch reduziert wird, bis das Bild innerhalb der angegebenen Bytegrenze liegt. Funktioniert nur mit verlustbehafteten Formaten: JPEG, WebP, HEIC und TIFF.

| Parameter | Typ     | Standard          | Erlaubte Werte                         |
| --------- | ------- | ----------------- | -------------------------------------- |
| bytes     | integer | `0` (deaktiviert) | Beliebige positive Ganzzahl (in Bytes) |

{% hint style="warning" %}
**Wichtig:** Wenn `mb` gesetzt ist, wird das Bild intern möglicherweise mehrfach gespeichert, um die Zielgröße zu erreichen. Das erhöht die Verarbeitungszeit.
{% endhint %}

**Beispiele:**

```
# Maximal 50 KB
mb:51200

# Maximal 100 KB
mb:102400

# Maximal 200 KB
mb:204800
```

**Rewrite-Rule-Beispiel — bandbreitenoptimierte Thumbnails:**

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

Damit sind Thumbnails niemals größer als 20 KB, unabhängig vom Quellbild.

***

### Format

```
f:%extension
```

Setzt das Ausgabeformat des Bildes. Wenn nicht angegeben, verwendet smoxy das Quellformat (Fallback: `jpg`).

| Parameter | Typ    | Standard            | Erlaubte Werte                                                                          |
| --------- | ------ | ------------------- | --------------------------------------------------------------------------------------- |
| extension | string | Quellformat / `jpg` | `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `ico`, `heic`, `bmp`, `tiff`, `pdf`, `svg` |

{% hint style="warning" %}
**Wichtig:** smoxy übernimmt bereits die automatische Formatkonvertierung (z. B. zu WebP oder AVIF) basierend auf den Fähigkeiten des Browsers. In den meisten Fällen ist es **nicht** nötig, das Format manuell zu setzen — smoxy liefert automatisch das beste Format aus. Diese Option sollte nur verwendet werden, wenn ein bestimmtes Ausgabeformat unabhängig von der Browser-Unterstützung erzwungen werden soll.
{% endhint %}

**Beispiele:**

```
# Zu WebP konvertieren
f:webp

# Zu AVIF konvertieren
f:avif

# Zu PNG konvertieren (verlustfrei)
f:png
```

**Rewrite-Rule-Beispiel — automatische WebP-Konvertierung:**

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

***

### Strip Metadata

```
sm:%strip_metadata
```

Steuert, ob EXIF-, IPTC-, XMP- und andere Metadaten aus dem Ergebnisbild entfernt werden.

| Parameter       | Typ     | Standard        | Erlaubte Werte                                                    |
| --------------- | ------- | --------------- | ----------------------------------------------------------------- |
| strip\_metadata | boolean | Server-Standard | `1`, `t`, `true` zum Entfernen; `0`, `f`, `false` zum Beibehalten |

**Beispiele:**

```
# Alle Metadaten entfernen
sm:1

# Metadaten beibehalten
sm:0
```

***

### Keep Copyright

```
kcr:%keep_copyright
```

Bewahrt Copyright-bezogene Metadaten auch dann, wenn das Entfernen von Metadaten aktiviert ist. Hat nur Wirkung, wenn `sm:1` (Strip Metadata) aktiv ist.

| Parameter       | Typ     | Standard        | Erlaubte Werte                                                    |
| --------------- | ------- | --------------- | ----------------------------------------------------------------- |
| keep\_copyright | boolean | Server-Standard | `1`, `t`, `true` zum Beibehalten; `0`, `f`, `false` zum Entfernen |

**Beispiel:**

```
# Metadaten entfernen, aber Copyright-Infos beibehalten
sm:1/kcr:1
```

***

### Strip Color Profile

```
scp:%strip_color_profile
```

Steuert, ob das eingebettete ICC-Farbprofil in sRGB umgewandelt und entfernt wird. Das hilft, die Dateigröße zu reduzieren und gleichzeitig konsistente Farben auf verschiedenen Geräten sicherzustellen.

| Parameter             | Typ     | Standard        | Erlaubte Werte                                                    |
| --------------------- | ------- | --------------- | ----------------------------------------------------------------- |
| strip\_color\_profile | boolean | Server-Standard | `1`, `t`, `true` zum Entfernen; `0`, `f`, `false` zum Beibehalten |

**Beispiel:**

```
# Farbprofil entfernen
scp:1
```

***

### Enforce Thumbnail

```
eth:%enforce_thumbnail
```

Wenn aktiviert, wird die Verwendung eines eingebetteten Thumbnails anstelle des Hauptbildes erzwungen. Unterstützt derzeit nur Thumbnails in HEIC- und AVIF-Formaten.

| Parameter          | Typ     | Standard | Erlaubte Werte                                                      |
| ------------------ | ------- | -------- | ------------------------------------------------------------------- |
| enforce\_thumbnail | boolean | `false`  | `1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren |

**Beispiel:**

```
eth:1
```

***

### Skip Processing

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

Überspringt die gesamte Verarbeitung für Bilder in den angegebenen Formaten. Das Bild wird unverändert zurückgegeben. Funktioniert nur, wenn das angeforderte Ausgabeformat mit dem Quellformat übereinstimmt.

| Parameter  | Typ       | Standard | Erlaubte Werte                                      |
| ---------- | --------- | -------- | --------------------------------------------------- |
| extensionN | string(s) | leer     | Beliebige Format-Endungen: `svg`, `gif`, `png` usw. |

**Beispiele:**

```
# Verarbeitung für SVG und GIF überspringen
skp:svg:gif

# Verarbeitung für PNG überspringen
skp:png
```

***

### Raw

```
raw:%raw
```

Gibt die rohe, unverarbeitete Quelldatei direkt zurück. Alle Verarbeitungsoperationen und Prüfungen (Typ, Auflösung, Dateigröße) werden übersprungen. Die Datei wird direkt gestreamt, was weniger Arbeitsspeicher als die normale Verarbeitung benötigt.

| Parameter | Typ     | Standard | Erlaubte Werte                                                      |
| --------- | ------- | -------- | ------------------------------------------------------------------- |
| raw       | boolean | `false`  | `1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren |

{% hint style="info" %}
**Tipp:** Im Gegensatz zu `skp` funktioniert die `raw`-Option mit jedem Dateityp und führt keinerlei Prüfung des Quellbildes durch. Ideal, wenn Dateien unverändert über die Bildmanipulations-Pipeline ausgeliefert werden sollen.
{% endhint %}

**Beispiel:**

```
raw:1
```

***

### Cache Buster

```
cb:%string
```

Hat keinen Einfluss auf die Bildverarbeitung. Der einzige Zweck ist, die URL zu verändern, damit CDN-, Proxy- und Browser-Caches umgangen werden. Nützlich, wenn serverseitige Einstellungen (Qualität, Presets, Wasserzeichen) geändert wurden, die sich nicht in der URL widerspiegeln.

| Parameter | Typ    | Standard | Erlaubte Werte    |
| --------- | ------ | -------- | ----------------- |
| string    | string | leer     | Beliebiger String |

**Beispiele:**

```
# Versionsbasiertes Cache-Busting
cb:v2

# Datumsbasiertes Cache-Busting
cb:20250226
```

***

### Expires

```
exp:%timestamp
```

Setzt einen Unix-Zeitstempel, nach dem die URL ungültig wird. smoxy gibt einen 404-Fehler für abgelaufene URLs zurück. Nützlich für zeitlich begrenzten Bildzugriff.

| Parameter | Typ     | Standard           | Erlaubte Werte   |
| --------- | ------- | ------------------ | ---------------- |
| timestamp | integer | leer (kein Ablauf) | Unix-Zeitstempel |

**Beispiel:**

```
# Läuft am 1. Januar 2026 ab
exp:1767225600
```

***

### Filename

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

Setzt den Dateinamen, der im `Content-Disposition`-Response-Header verwendet wird. Wenn nicht angegeben, leitet smoxy den Dateinamen aus der Quell-URL ab.

| Parameter | Typ     | Standard                | Erlaubte Werte                                         |
| --------- | ------- | ----------------------- | ------------------------------------------------------ |
| filename  | string  | Dateiname der Quell-URL | Escaped String oder URL-safe Base64-kodierter String   |
| encoded   | boolean | `false`                 | `1`, `t`, `true` wenn der Dateiname Base64-kodiert ist |

**Beispiel:**

```
fn:produkt-foto.jpg
```

***

### Return Attachment

```
att:%return_attachment
```

Wenn aktiviert, wird der `Content-Disposition`-Header auf `attachment` gesetzt. Dadurch wird im Browser ein „Speichern unter"-Dialog ausgelöst, anstatt das Bild direkt anzuzeigen.

| Parameter          | Typ     | Standard | Erlaubte Werte                                                      |
| ------------------ | ------- | -------- | ------------------------------------------------------------------- |
| return\_attachment | boolean | `false`  | `1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren |

**Beispiel:**

```
# Download erzwingen
att:1
```

**Rewrite-Rule-Beispiel — herunterladbare Bilder:**

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

***

### Preset

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

Wendet ein oder mehrere benannte Presets an, die serverseitig konfiguriert sind. Presets sind Sammlungen von Verarbeitungsoptionen, die über mehrere URLs hinweg wiederverwendet werden können. Operationen, die explizit in der URL gesetzt sind, überschreiben die Werte aus dem Preset.

| Parameter     | Typ       | Standard | Erlaubte Werte                       |
| ------------- | --------- | -------- | ------------------------------------ |
| preset\_nameN | string(s) | leer     | Beliebige konfigurierte Preset-Namen |

**Beispiel:**

```
# Ein einzelnes Preset anwenden
pr:thumbnail

# Mehrere Presets anwenden
pr:sharp:small
```