# Farmer — Sound-Effekte + Musik (TODO via ElevenLabs Sound-Effects API + Musik-Quelle)

Aktueller Stand: `playSound(name, opts)` ist als **Stub** in `game.html`
implementiert (loggt nur in die Konsole). Mute-Toggle 🔊/🔇 ist in der
Topbar vorbereitet. Sobald MP3-Dateien unter `assets/sounds/` liegen,
ersetzt der Stub durch echtes `Audio.play()` und der Mute-Toggle wird
funktional.

## Workflow zum Generieren (sobald API-Zugang da ist)

1. **ElevenLabs Sound Effects API**: `POST /v1/sound-generation`
   mit Prompt + duration_seconds
2. MP3 unter `App/sims/farmer/assets/sounds/<name>.mp3` ablegen
3. `playSound()`-Stub durch echtes Audio-Play ersetzen (siehe
   `// TODO ElevenLabs`-Marker im Code)
4. Audio-Cache: alle Sounds beim Boot mit `new Audio()` vorladen,
   damit die erste Wiedergabe nicht stockt
5. Mute-Toggle ist schon eingebaut — wird automatisch aktiv wenn
   Audio-Dateien da sind

## Sound-Effekte (15 Stück)

| Name (Datei) | Wann wird abgespielt | ElevenLabs-Prompt | Dauer |
|---|---|---|---|
| `plant.mp3` | Nach jeder Pflanzung (Karten-Klick) | "Soft natural sound of seeds being scattered onto soil, single brief gesture, no music" | 0.6 s |
| `harvest_start.mp3` | Klick auf „Erntejahr starten" | "Distant farm bell ringing twice, calling workers to harvest, warm ambient countryside" | 1.2 s |
| `report_open.mp3` | Wenn eine Bericht-Card erscheint | "Soft paper page turning, gentle crisp sound" | 0.4 s |
| `report_next.mp3` | Klick auf „Weiter" zwischen Cards | "Soft tap on wooden table, very brief" | 0.2 s |
| `vehicle_truck.mp3` | Beim Start einer LKW-Animation | "Heavy diesel truck engine starting and driving away, departing motor sound" | 1.5 s |
| `vehicle_ship.mp3` | Beim Start einer Schiff-Animation | "Cargo ship horn, deep low blast, single foghorn" | 2.0 s |
| `vehicle_plane.mp3` | Beim Start einer Flugzeug-Animation | "Cargo plane taking off, jet engine spinning up and lifting" | 2.0 s |
| `vehicle_arrive.mp3` | Wenn Vehicle den Hub erreicht | "Cash register cha-ching sound, coins falling into drawer, brief and bright" | 0.7 s |
| `disease_outbreak.mp3` | Bei Krankheits-Ausbruch im Bericht | "Ominous low drone with subtle crackling and whispering wind, foreboding agricultural disaster" | 1.5 s |
| `monoculture_warn.mp3` | Sanfte Warnung wenn Bodenmüdigkeit > 30 % im Bericht | "Subtle dry rustling of leaves, gentle warning tone" | 0.8 s |
| `year_advance.mp3` | Beim Übergang ins nächste Jahr | "Soft mechanical calendar page flipping, with gentle clock chime" | 0.8 s |
| `unlock_crop.mp3` | Wenn eine neue Sorte freigeschaltet wird | "Bright magical chime, discovery sound, hopeful and brief" | 1.0 s |
| `negative_balance.mp3` | Wenn Geld-Anzeige negativ wird | "Sad descending two-note tone, very subtle, regretful" | 0.7 s |
| `end_report_open.mp3` | Wenn der Endbericht-Modal aufgeht | "Triumphant ascending chime, festive but warm, harvest celebration" | 1.5 s |
| `reset.mp3` | Beim Neustart-Klick | "Soft swoosh, gentle reset, brief and clean" | 0.5 s |

## Hintergrundmusik

Empfohlener Stil: **Ambient-akustisch mit leichten Folk-Elementen.**
- Sanftes Klavier oder akustische Gitarre
- Sehr dezente Naturgeräusche (Wind, ferne Vögel)
- Keine starken Rhythmen, keine Vocals
- Tonart: meistens Dur-Variationen
- Lautstärke: bewusst leise (Vordergrund: Lernarbeit + Sound-Effekte)

**Referenz-Stile** (zur Orientierung wenn mit Suno/Stable Audio generiert):
- Banished-Soundtrack (Mark Engberg) — landwirtschaftlich-ambient
- Stardew Valley „Spring" — sanft, melodisch, nicht zu süßlich
- Brian Eno „Music for Airports" — minimalistisch
- Ludovico Einaudi (Klavier-Minimalismus)

**Empfohlene Musik-Dateien** (mehrere Loops für Abwechslung):

| Datei | Stil | Dauer | Generierungs-Prompt |
|---|---|---|---|
| `music_main.mp3` | Hauptloop (default) | 3–5 min, loop-tauglich | "Gentle ambient acoustic guitar with soft piano, peaceful pastoral atmosphere, subtle nature sounds wind and distant birds, no vocals, calm tempo around 70 BPM, in C major, loopable seamlessly" |
| `music_hamburg.mp3` (optional) | EU-Markt aktiv | 2–3 min | "Slow folk waltz with accordion and acoustic guitar, gentle European countryside feel, no vocals, 80 BPM" |
| `music_shanghai.mp3` (optional) | Asien-Markt aktiv | 2–3 min | "Peaceful East Asian instrumental with guzheng and bamboo flute, no vocals, slow 70 BPM" |
| `music_saopaulo.mp3` (optional) | Südamerika-Markt aktiv | 2–3 min | "Gentle bossa nova guitar instrumental, no vocals, warm and laid-back, 80 BPM" |
| `music_dubai.mp3` (optional) | Naher Osten aktiv | 2–3 min | "Atmospheric instrumental with oud and ney flute, peaceful desert evening, no vocals, 70 BPM" |
| `music_newyork.mp3` (optional) | NA-Markt aktiv | 2–3 min | "Gentle Americana acoustic with light banjo and harmonica, no vocals, 80 BPM" |

**Hinweis zur Generierung:** ElevenLabs Sound Effects ist primär für kurze
Sounds — für Musik-Loops empfehle ich **Suno** (suno.com) oder
**Stable Audio** (Stability AI). Beide können 2–5 Min lange Loops mit
deutschen oder englischen Prompts erzeugen. Lizenz prüfen für Schul-
Einsatz (Suno gibt CC-BY für Free-Tier, Pro-Plan kommerzielle Rechte).

## Aufruf-Stellen im Code (bereits eingebaut als Stub)

| Funktion in `game.html` | Aufruf |
|---|---|
| `onMapClick` (nach erfolgreichem `plant`) | `playSound('plant')` |
| `onHarvest` | `playSound('harvest_start')` |
| `showReportCard` (Eintritt) | `playSound('report_open')` ODER `playSound('disease_outbreak')` falls Disease |
| `onReportNext` (mittendrin) | `playSound('report_next')` |
| `animateOneTrade` (Start) | `playSound('vehicle_' + modeKey)` |
| `animateOneTrade` (Ankunft) | `playSound('vehicle_arrive')` |
| `onReportNext` (letzte Card → nextYear) | `playSound('year_advance')` |
| `unlockNewCrops` (wenn neue Sorte freigeschaltet) | `playSound('unlock_crop')` |
| `updateMoneyDisplay` (Übergang positiv→negativ) | `playSound('negative_balance')` |
| `showEndReport` | `playSound('end_report_open')` (TODO einfügen) |
| `resetGame` | `playSound('reset')` (TODO einfügen) |
| Boot | Hintergrundmusik starten (wenn audioEnabled) |
| `toggleAudio` | Hintergrundmusik mute/unmute |

## API-Zugangsdaten (TODO Thomas)

- **ElevenLabs API-Key** in `App/.env.local` als `ELEVENLABS_API_KEY=...`
- **Suno API-Key** (für Musik) in `App/.env.local` als `SUNO_API_KEY=...`
- Generierungs-Skript wird unter `scripts/generate-sounds.sh` analog zum
  Bildstil-Generator (Logistik) angelegt sobald Keys da sind
- **Keine Live-API-Calls im Produkt** — Sounds + Musik werden vorab generiert,
  als statische MP3-Dateien ausgeliefert (Memory `feedback_no_ai_in_product`)