# Bildoptimierung

smoxy optimiert automatisch Bilder, die über deine Site ausgeliefert werden — reduziert Dateigrößen ohne sichtbaren Qualitätsverlust und konvertiert Bilder in moderne Formate wie WebP und AVIF. Das verbessert Ladezeiten und reduziert den Bandbreitenverbrauch.

***

### Wie es funktioniert

Wenn die Bildoptimierung aktiviert ist:

1. Ein Besucher fordert ein Bild an (z. B. `product.jpg`)
2. smoxy holt das Bild von deinem Origin
3. smoxy komprimiert das Bild und konvertiert es optional zu WebP oder AVIF
4. Das optimierte Bild wird gecacht und dem Besucher ausgeliefert
5. Die Original-URL ändert sich nicht — die Formatverhandlung erfolgt automatisch über den `Accept`-Header

**Unterstützte Eingabeformate:** JPEG, PNG

**Unterstützte Ausgabeformate:** JPEG, PNG, WebP, AVIF

***

### Bildoptimierung aktivieren

1. Navigiere zu deiner **Site** in smoxy
2. Öffne die **Bildoptimierung**-Einstellungen
3. Aktiviere den Schalter **Bildoptimierung**
4. Konfiguriere Qualitäts- und Formateinstellungen
5. Speichern

***

### Formatkonvertierung

#### Konvertierung zu WebP

Wenn aktiviert, konvertiert smoxy JPEG- und PNG-Bilder in das **WebP**-Format für Browser, die es unterstützen. WebP erreicht typischerweise 25–35% kleinere Dateigrößen im Vergleich zu JPEG bei gleicher visueller Qualität.

| Einstellung       | Standard  |
| ----------------- | --------- |
| `convert_to_webp` | Aktiviert |
| `webp_quality`    | 75        |

Browser, die WebP nicht unterstützen, erhalten das optimierte Originalformat (JPEG oder PNG).

#### Konvertierung zu AVIF

Wenn aktiviert, konvertiert smoxy JPEG- und PNG-Bilder in das **AVIF**-Format für Browser, die es unterstützen. AVIF erreicht typischerweise noch bessere Komprimierung als WebP.

| Einstellung       | Standard  |
| ----------------- | --------- |
| `convert_to_avif` | Aktiviert |
| `avif_quality`    | 50        |

Browser, die AVIF nicht unterstützen, fallen auf WebP zurück (falls aktiviert), oder auf das optimierte Originalformat.

> **Hinweis:** Einige Dienste wie Google Merchant Center akzeptieren keine AVIF-Bilder. Wenn du Google Merchant Feeds verwendest, siehe Google Merchant Crawler für Details.

***

### Qualitätseinstellungen

Die Bildoptimierung verwendet einen Qualitätsbereich (Min/Max), um die beste Balance zwischen Dateigröße und visueller Qualität zu finden. smoxy nutzt die **SSIM**-Methode (Structural Similarity Index), um sicherzustellen, dass komprimierte Bilder visuell identisch mit den Originalen bleiben.

#### JPEG

| Einstellung           | Bereich       | Standard | Beschreibung                                 |
| --------------------- | ------------- | -------- | -------------------------------------------- |
| `jpeg_quality_min`    | 1–100         | 40       | Minimal akzeptable Qualität (untere Grenze)  |
| `jpeg_quality_max`    | 1–100         | 98       | Maximale Qualität (obere Grenze)             |
| `jpeg_quality_target` | 0,0001–0,9999 | 0,9997   | SSIM-Ziel — höher bedeutet näher am Original |

Das SSIM-Ziel steuert, wie aggressiv smoxy komprimiert. Der Standard von `0,9997` ist sehr konservativ — kaum vom Original zu unterscheiden. Senke das Ziel für kleinere Dateien auf Kosten leicht reduzierter Qualität.

#### PNG

| Einstellung       | Bereich | Standard | Beschreibung                |
| ----------------- | ------- | -------- | --------------------------- |
| `png_quality_min` | 1–100   | 40       | Minimal akzeptable Qualität |
| `png_quality_max` | 1–100   | 98       | Maximale Qualität           |

#### WebP

| Einstellung    | Bereich | Standard | Beschreibung                           |
| -------------- | ------- | -------- | -------------------------------------- |
| `webp_quality` | 1–100   | 75       | Ausgabequalität für WebP-Konvertierung |

#### AVIF

| Einstellung    | Bereich | Standard | Beschreibung                           |
| -------------- | ------- | -------- | -------------------------------------- |
| `avif_quality` | 1–100   | 50       | Ausgabequalität für AVIF-Konvertierung |

***

### Pro-Request-Überschreibungen

Du kannst Bildoptimierungseinstellungen für bestimmte Anfragen mit Conditional Rules überschreiben. Das ermöglicht dir:

* Unterschiedliche Qualitätsstufen für mobile Nutzer setzen
* Formatkonvertierung für bestimmte Pfade deaktivieren
* Aggressivere Komprimierung für bestimmte Regionen anwenden

**Beispiel:** Bildqualität für mobile Besucher reduzieren, um Bandbreite zu sparen:

| Bedingung                                      | Einstellung       | Wert |
| ---------------------------------------------- | ----------------- | ---- |
| User Agent enthält `(Mobile\|Android\|iPhone)` | JPEG Max Qualität | 75   |
| User Agent enthält `(Mobile\|Android\|iPhone)` | WebP Qualität     | 65   |

***

### Wichtige Hinweise

* **Automatische Formatverhandlung:** smoxy prüft den `Accept`-Header des Besuchers, um zu bestimmen, welche Formate der Browser unterstützt. Die URL bleibt gleich — nur das Antwortformat ändert sich.
* **Gecacht pro Format:** Optimierte Bilder werden für jedes Ausgabeformat separat gecacht. Eine JPEG-, WebP- und AVIF-Version desselben Bildes können im Cache koexistieren.
* **Nur JPEG und PNG als Eingabe:** smoxy optimiert JPEG- und PNG-Bilder. Andere Formate (GIF, SVG, etc.) werden ohne Änderung durchgereicht.
* **Verlustfrei wird nicht unterstützt:** Bildoptimierung wendet immer verlustbehaftete Komprimierung an. Wenn du pixelgenaue Bildauslieferung benötigst, deaktiviere die Optimierung für diese Pfade mit einer Conditional Rule.
* **Cloudflare-Nutzer:** Wenn du Cloudflare vor smoxy verwendest, deaktiviere Cloudflares Bildoptimierung (Polish), um doppelte Optimierung zu vermeiden. Siehe [Cloudflare Setup](https://docs.smoxy.eu/developer-guide/cloudflare-setup).