Add ambience generation features and assets. Introduced ambience.py for procedural and sampled ambience beds, updated app.py to integrate ambience selection into music generation, and modified requirements.txt to include new dependencies. Added scripts for fetching and rendering ambience samples, along with new audio assets and credits for attribution.

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text

ambience.py

@@ -0,0 +1,197 @@
+"""Ambience beds for LoFinity tapes.
+
+MusicGen ignores texture words ("vinyl crackle", "ocean waves"), so the
+background layer is mixed in here instead: a bed is rendered at song length
+and summed a few dB under the music. Lofi ambience loops through the whole
+track anyway, so nothing needs to be generated per song.
+
+vinyl_crackle and tape_hiss are synthesized procedurally (cheap, and never
+sound repeated); the other seven are loops in assets/ambience/<slug>.wav,
+rendered once by scripts/make_ambience.py and tiled with crossfades. A
+missing asset falls back to vinyl crackle so every tape still has texture.
+"""
+
+import wave
+from pathlib import Path
+
+import numpy as np
+
+ASSETS = Path(__file__).parent / "assets" / "ambience"
+
+# Bed RMS relative to the music RMS, in dB. Starting points — tune by ear:
+# spiky textures (crackle, fire) read louder than their RMS suggests.
+GAIN_DB = {
+    "vinyl_crackle": -14.0,
+    "tape_hiss": -18.0,
+    "soft_rain": -14.0,
+    "ocean_waves": -12.0,
+    "fireplace_crackle": -14.0,
+    "birdsong": -16.0,
+    "night_crickets": -16.0,
+    "cafe_murmur": -16.0,
+    "wind_in_trees": -14.0,
+}
+DEFAULT = "vinyl_crackle"
+
+# Checked in order; first hit wins ("fireplace crackle" must match fire
+# before crackle can claim it for vinyl).
+_KEYWORDS = (
+    ("fire", "fireplace_crackle"),
+    ("rain", "soft_rain"),
+    ("wave", "ocean_waves"),
+    ("ocean", "ocean_waves"),
+    ("sea", "ocean_waves"),
+    ("bird", "birdsong"),
+    ("cricket", "night_crickets"),
+    ("cafe", "cafe_murmur"),
+    ("coffee", "cafe_murmur"),
+    ("murmur", "cafe_murmur"),
+    ("chatter", "cafe_murmur"),
+    ("wind", "wind_in_trees"),
+    ("tree", "wind_in_trees"),
+    ("leaves", "wind_in_trees"),
+    ("vinyl", "vinyl_crackle"),
+    ("crackle", "vinyl_crackle"),
+    ("static", "vinyl_crackle"),
+    ("record", "vinyl_crackle"),
+    ("hiss", "tape_hiss"),
+    ("tape", "tape_hiss"),
+    ("noise", "tape_hiss"),
+)
+
+
+def normalize_slug(value) -> str:
+    """Map whatever the LLM produced onto a known slug ("Ocean waves!" ->
+    ocean_waves); anything unrecognizable becomes the default crackle."""
+    text = str(value or "").strip().lower()
+    slug = text.replace(" ", "_").replace("-", "_")
+    if slug in GAIN_DB:
+        return slug
+    for word, match in _KEYWORDS:
+        if word in text:
+            return match
+    return DEFAULT
+
+
+# --- procedural beds ----------------------------------------------------------
+
+
+def _lowpassed_noise(n: int, rate: int, cutoff: float, rng) -> np.ndarray:
+    """Cheap dull noise: draw at ~2*cutoff and linearly upsample (the
+    interpolation is the lowpass)."""
+    low_rate = max(int(cutoff * 2), 200)
+    m = max(int(n * low_rate / rate) + 2, 2)
+    coarse = rng.standard_normal(m)
+    return np.interp(np.arange(n) * (low_rate / rate), np.arange(m), coarse)
+
+
+def _vinyl_crackle(n: int, rate: int, rng) -> np.ndarray:
+    """Dusty surface noise plus sparse pops, tiny pops, not loud."""
+    out = _lowpassed_noise(n, rate, 2500, rng) * 0.06
+    for pos in rng.integers(0, n, max(int(n / rate * 9), 1)):
+        length = int(rate * rng.uniform(0.001, 0.004))
+        amp = rng.uniform(0.15, 1.0) ** 2 * np.sign(rng.standard_normal())
+        pop = amp * np.exp(-np.arange(length) / (length / 5))
+        end = min(pos + length, n)
+        out[pos:end] += pop[: end - pos]
+    return out
+
+
+def _tape_hiss(n: int, rate: int, rng) -> np.ndarray:
+    white = rng.standard_normal(n)
+    # first difference tilts the spectrum toward the highs, where hiss lives
+    tilted = np.zeros(n)
+    tilted[1:] = np.diff(white)
+    hiss = 0.35 * white + 0.65 * tilted
+    # slow wobble so it breathes like a real transport
+    lfo = 0.3  # Hz
+    phase = rng.uniform(0, 2 * np.pi)
+    return hiss * (1.0 + 0.08 * np.sin(2 * np.pi * lfo * np.arange(n) / rate + phase))
+
+
+_PROCEDURAL = {"vinyl_crackle": _vinyl_crackle, "tape_hiss": _tape_hiss}
+
+
+# --- sampled beds ---------------------------------------------------------------
+
+
+def _read_wav(path: Path) -> tuple[np.ndarray, int]:
+    with wave.open(str(path), "rb") as w:
+        rate, channels, width = w.getframerate(), w.getnchannels(), w.getsampwidth()
+        raw = w.readframes(w.getnframes())
+    if width != 2:
+        raise ValueError(f"{path.name}: expected 16-bit wav, got {width * 8}-bit")
+    data = np.frombuffer(raw, dtype="<i2").astype(np.float64) / 32768.0
+    if channels > 1:
+        data = data.reshape(-1, channels).mean(axis=1)
+    return data, rate
+
+
+def _resample(data: np.ndarray, src_rate: int, dst_rate: int) -> np.ndarray:
+    if src_rate == dst_rate:
+        return data
+    m = int(len(data) * dst_rate / src_rate)
+    return np.interp(np.arange(m) * (src_rate / dst_rate), np.arange(len(data)), data)
+
+
+def _tile(loop: np.ndarray, n: int, rate: int) -> np.ndarray:
+    """Repeat the loop out to n samples, crossfading each seam so it
+    doesn't click. The loop does not need to be seamless.
+
+    The fade uses equal-power (sqrt) ramps, not linear: the tail and head
+    being blended are uncorrelated audio, so linear ramps would sum to ~3-6 dB
+    below the surrounding level at the crossfade midpoint (an audible dip every
+    loop). With sqrt ramps gain_out**2 + gain_in**2 == 1, holding power steady."""
+    if len(loop) >= n:
+        return loop[:n].copy()
+    fade = min(int(rate * 0.5), len(loop) // 4)
+    if fade == 0:
+        return np.tile(loop, n // len(loop) + 1)[:n]
+    ramp = np.sqrt(np.linspace(0.0, 1.0, fade))
+    out = np.zeros(n + len(loop))
+    pos = 0
+    while pos < n:
+        seg = loop.copy()
+        if pos:
+            seg[:fade] *= ramp
+        seg[-fade:] *= ramp[::-1]
+        out[pos : pos + len(seg)] += seg
+        pos += len(loop) - fade
+    return out[:n]
+
+
+# --- public API -----------------------------------------------------------------
+
+
+def render(slug: str, n: int, rate: int) -> np.ndarray:
+    """A peak-normalized bed of n samples at `rate`; the caller sets the level."""
+    if slug in _PROCEDURAL:
+        bed = _PROCEDURAL[slug](n, rate, np.random.default_rng())
+    else:
+        loop, loop_rate = _read_wav(ASSETS / f"{slug}.wav")
+        bed = _tile(_resample(loop, loop_rate, rate), n, rate)
+    return bed / (float(np.abs(bed).max()) or 1.0)
+
+
+def mix(music, rate: int, slug: str) -> np.ndarray:
+    """Sum the ambience bed under the music at its slug's relative RMS level."""
+    slug = normalize_slug(slug)
+    if slug not in _PROCEDURAL and not (ASSETS / f"{slug}.wav").exists():
+        print(
+            f"[lofinity] no ambience asset for {slug!r} "
+            "(run scripts/make_ambience.py), using vinyl crackle"
+        )
+        slug = DEFAULT
+    music = np.asarray(music, dtype=np.float64)
+    music_rms = float(np.sqrt(np.mean(music**2)))
+    if music_rms < 1e-6:  # silence in, silence out
+        return music
+    bed = render(slug, len(music), rate)
+    bed_rms = float(np.sqrt(np.mean(bed**2))) or 1.0
+    bed *= music_rms * 10 ** (GAIN_DB[slug] / 20) / bed_rms
+    edge = min(int(rate * 0.75), len(bed) // 4)
+    if edge:
+        ramp = np.linspace(0.0, 1.0, edge)
+        bed[:edge] *= ramp
+        bed[-edge:] *= ramp[::-1]
+    return music + bed

app.py

@@ -4,7 +4,9 @@ Gradio Server backend: serves the Three.js frontend and exposes the
 generation API.
 
 Pipeline: user vibe -> Ollama (small LLM) enriches it into a MusicGen
-prompt + cassette title -> MusicGen renders the audio.
+prompt + cassette title + ambience pick -> MusicGen renders the music ->
+ambience.py loops a background bed (waves, crackle, rain…) underneath.
+MusicGen ignores texture words in prompts, hence the separate bed.
 
 Env knobs:
   LOFINITY_ENGINE   musicgen (default) | stub
@@ -15,9 +17,7 @@ Env knobs:
 """
 
 import json
-import math
 import os
-import struct
 import threading
 import time
 import uuid
@@ -48,32 +48,35 @@ app = Server(title="LoFinity")
 ENRICH_SYSTEM = """\
 You are the creative brain of LoFinity, a magical vending machine that sells
 lofi cassette tapes. The user gives you a vibe. Reply ONLY with JSON with
-exactly these two keys: {"music_prompt": "...", "title": "..."}
+exactly these three keys: {"music_prompt": "...", "title": "...", "ambience": "..."}
 
 Build music_prompt from this template, in this order:
-"lofi chill, <instrument 1>, <instrument 2>, <instrument 3>, <background noise>, <mood>, slow tempo, 75 bpm, instrumental"
+"lofi chill, <instrument 1>, <instrument 2>, <instrument 3>, <mood>, slow tempo, 75 bpm, instrumental"
 
 - instruments: 2-3 picked to EVOKE the user's vibe, never a default set
   (island -> ukulele, kalimba, steel pan; rainy city -> rhodes piano, soft
   guitar; winter -> felt piano, soft strings; desert -> slide guitar, hand drums)
-- background noise: exactly one, matched to the vibe: vinyl crackle, tape
-  hiss, soft rain, ocean waves, fireplace crackle, birdsong, night crickets,
-  cafe murmur, or wind in trees
 - mood: one or two calm words; never energetic, no vocals
 
+ambience: the background sound layered under the music. Exactly one of:
+vinyl_crackle, tape_hiss, soft_rain, ocean_waves, fireplace_crackle,
+birdsong, night_crickets, cafe_murmur, wind_in_trees. Match it to the vibe.
+
 title: a cozy cassette tape title inspired by the vibe, max 5 words,
 Title Case, no quotes or emoji.
 
 Examples:
 user: island summer
-{"music_prompt": "lofi chill, ukulele, kalimba, steel pan, ocean waves in the background, breezy and warm, slow tempo, 75 bpm, instrumental", "title": "Coconut Daydream"}
+{"music_prompt": "lofi chill, ukulele, kalimba, steel pan, breezy and warm, slow tempo, 75 bpm, instrumental", "title": "Coconut Daydream", "ambience": "ocean_waves"}
 user: studying at midnight
-{"music_prompt": "lofi chill, rhodes piano, muted guitar, soft bass, vinyl crackle in the background, focused and calm, slow tempo, 75 bpm, instrumental", "title": "Midnight Study Session"}"""
+{"music_prompt": "lofi chill, rhodes piano, muted guitar, soft bass, focused and calm, slow tempo, 75 bpm, instrumental", "title": "Midnight Study Session", "ambience": "vinyl_crackle"}"""
+
 
+def enrich_prompt(prompt: str) -> tuple[str, str, str]:
+    """Vibe -> (music_prompt, cassette title, ambience slug), with a plain
+    fallback if the local LLM is unreachable or returns junk."""
+    import ambience
 
-def enrich_prompt(prompt: str) -> tuple[str, str]:
-    """Vibe -> (music_prompt, cassette title), with a plain fallback if the
-    local LLM is unreachable or returns junk."""
     try:
         r = httpx.post(
             f"{OLLAMA_URL}/api/chat",
@@ -97,21 +100,16 @@ def enrich_prompt(prompt: str) -> tuple[str, str]:
             # belt and suspenders: the genre must lead even if the LLM drifts
             if "lofi" not in music_prompt.lower():
                 music_prompt = f"lofi chill, {music_prompt}"
-            # …and there must always be a background noise layer
-            noise_words = (
-                "crackle", "hiss", "rain", "waves", "noise", "birdsong",
-                "crickets", "murmur", "wind", "fireplace", "static",
-            )
-            if not any(w in music_prompt.lower() for w in noise_words):
-                music_prompt += ", soft vinyl crackle in the background"
-            return music_prompt, title
+            # whatever the LLM picked, snap it to a bed we can actually render
+            return music_prompt, title, ambience.normalize_slug(data.get("ambience"))
     except Exception as e:  # noqa: BLE001 — any failure means "use fallback"
         print(f"[lofinity] ollama enrichment failed ({e!r}), using fallback")
     fallback_title = f"{prompt[:28].title()} Tape" if prompt.strip() else "Untitled Tape"
     return (
         f"lofi chill, {prompt}, mellow and warm, soft drums, "
-        "vinyl crackle, slow tempo, instrumental",
+        "slow tempo, instrumental",
         fallback_title,
+        ambience.DEFAULT,
     )
 
 
@@ -161,7 +159,8 @@ def write_wav(samples, rate: int) -> Path:
     return out
 
 
-def musicgen_engine(music_prompt: str) -> Path:
+def musicgen_engine(music_prompt: str) -> tuple:
+    """Returns (samples, sample_rate); the caller mixes and writes."""
     import torch
 
     processor, model, device = load_musicgen()
@@ -186,27 +185,18 @@ def musicgen_engine(music_prompt: str) -> Path:
             samples = run("cpu")
         else:
             raise
-    rate = model.config.audio_encoder.sampling_rate
-    return write_wav(samples, rate)
+    return samples, model.config.audio_encoder.sampling_rate
 
 
-def stub_engine(_music_prompt: str) -> Path:
+def stub_engine(_music_prompt: str) -> tuple:
     """A short audible tone — handy when developing without the heavy model."""
-    sample_rate = 22050
-    seconds = 2.0
-    frames = bytearray()
-    for i in range(int(sample_rate * seconds)):
-        t = i / sample_rate
-        fade = min(1.0, t * 4, (seconds - t) * 4)
-        sample = int(0.25 * fade * 32767 * math.sin(2 * math.pi * 220 * t))
-        frames += struct.pack("<h", sample)
-    out = SONGS_DIR / f"{uuid.uuid4().hex}.wav"
-    with wave.open(str(out), "wb") as w:
-        w.setnchannels(1)
-        w.setsampwidth(2)
-        w.setframerate(sample_rate)
-        w.writeframes(bytes(frames))
-    return out
+    import numpy as np
+
+    rate = 22050
+    seconds = 8.0
+    t = np.arange(int(rate * seconds)) / rate
+    fade = np.minimum(1.0, np.minimum(t * 4, (seconds - t) * 4))
+    return 0.25 * fade * np.sin(2 * np.pi * 220 * t), rate
 
 
 # --- API -----------------------------------------------------------------------
@@ -214,13 +204,22 @@ def stub_engine(_music_prompt: str) -> Path:
 
 @app.api(name="generate_song", concurrency_limit=1)
 def generate_song(prompt: str) -> dict:
-    music_prompt, title = enrich_prompt(prompt)
-    print(f"[lofinity] brewing {title!r} :: {music_prompt}")
+    import ambience
+
+    music_prompt, title, bed = enrich_prompt(prompt)
+    print(f"[lofinity] brewing {title!r} :: {music_prompt} [+ {bed}]")
     engine = stub_engine if ENGINE == "stub" else musicgen_engine
-    out = engine(music_prompt)
+    samples, rate = engine(music_prompt)
+    try:
+        samples = ambience.mix(samples, rate, bed)
+    except Exception as e:  # noqa: BLE001 — a dry tape beats a failed vend
+        print(f"[lofinity] ambience mix failed ({e!r}), vending without the bed")
+    out = write_wav(samples, rate)
     # sidecar metadata so the tape shows up in the collection later
     out.with_suffix(".json").write_text(
-        json.dumps({"title": title, "prompt": prompt, "created": time.time()})
+        json.dumps(
+            {"title": title, "prompt": prompt, "ambience": bed, "created": time.time()}
+        )
     )
     return {
         "title": title,

assets/ambience/CREDITS.md

@@ -0,0 +1,46 @@
+# Ambience sample credits
+
+Auto-fetched from Wikimedia Commons by `scripts/fetch_ambience.py`.
+vinyl_crackle and tape_hiss are synthesized in `ambience.py` and not listed.
+
+## birdsong
+- **Birds singing in Fribourg 01.ogg**
+- Author: Martin Thurnherr
+- Licence: CC BY-SA 4.0
+- Source: https://commons.wikimedia.org/wiki/File:Birds_singing_in_Fribourg_01.ogg
+
+## cafe_murmur
+- **Shopping mall less crowded.ogg**
+- Author: natalie
+- Licence: Public domain
+- Source: https://commons.wikimedia.org/wiki/File:Shopping_mall_less_crowded.ogg
+
+## fireplace_crackle
+- **WWS Fireoftheforge.ogg**
+- Author: Work With Sounds / La Fonderie
+- Licence: CC BY 4.0
+- Source: https://commons.wikimedia.org/wiki/File:WWS_Fireoftheforge.ogg
+
+## night_crickets
+- **Black-Prince-Cicada- Psaltoda-plaga.wav**
+- Author: 7575u
+- Licence: CC BY-SA 4.0
+- Source: https://commons.wikimedia.org/wiki/File:Black-Prince-Cicada-_Psaltoda-plaga.wav
+
+## ocean_waves
+- **Sea waves.wav**
+- Author: Ganesh Mohan T
+- Licence: CC BY-SA 4.0
+- Source: https://commons.wikimedia.org/wiki/File:Sea_waves.wav
+
+## soft_rain
+- **Lluvia en techo de lamina.wav**
+- Author: Doggo19292
+- Licence: CC BY-SA 4.0
+- Source: https://commons.wikimedia.org/wiki/File:Lluvia_en_techo_de_lamina.wav
+
+## wind_in_trees
+- **Wind in forest (Gravity Sound).wav**
+- Author: Gravity Sound
+- Licence: CC BY 4.0
+- Source: https://commons.wikimedia.org/wiki/File:Wind_in_forest_(Gravity_Sound).wav

assets/ambience/birdsong.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f3dcf170ccf3838158b83ef34e667d111838a46a97d1854aa9aaea5d6981e73c
+size 960044

assets/ambience/cafe_murmur.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5d27ec1738dcae636032775479478d797cfb51f9cd79ce43e8f7bd61cdd28777
+size 1920044

assets/ambience/credits.json

@@ -0,0 +1,51 @@
+{
+  "birdsong": {
+    "artist": "Martin Thurnherr",
+    "license": "CC BY-SA 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:Birds_singing_in_Fribourg_01.ogg",
+    "slug": "birdsong",
+    "title": "Birds singing in Fribourg 01.ogg"
+  },
+  "cafe_murmur": {
+    "artist": "natalie",
+    "license": "Public domain",
+    "page": "https://commons.wikimedia.org/wiki/File:Shopping_mall_less_crowded.ogg",
+    "slug": "cafe_murmur",
+    "title": "Shopping mall less crowded.ogg"
+  },
+  "fireplace_crackle": {
+    "artist": "Work With Sounds / La Fonderie",
+    "license": "CC BY 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:WWS_Fireoftheforge.ogg",
+    "slug": "fireplace_crackle",
+    "title": "WWS Fireoftheforge.ogg"
+  },
+  "night_crickets": {
+    "artist": "7575u",
+    "license": "CC BY-SA 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:Black-Prince-Cicada-_Psaltoda-plaga.wav",
+    "slug": "night_crickets",
+    "title": "Black-Prince-Cicada- Psaltoda-plaga.wav"
+  },
+  "ocean_waves": {
+    "artist": "Ganesh Mohan T",
+    "license": "CC BY-SA 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:Sea_waves.wav",
+    "slug": "ocean_waves",
+    "title": "Sea waves.wav"
+  },
+  "soft_rain": {
+    "artist": "Doggo19292",
+    "license": "CC BY-SA 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:Lluvia_en_techo_de_lamina.wav",
+    "slug": "soft_rain",
+    "title": "Lluvia en techo de lamina.wav"
+  },
+  "wind_in_trees": {
+    "artist": "Gravity Sound",
+    "license": "CC BY 4.0",
+    "page": "https://commons.wikimedia.org/wiki/File:Wind_in_forest_(Gravity_Sound).wav",
+    "slug": "wind_in_trees",
+    "title": "Wind in forest (Gravity Sound).wav"
+  }
+}

assets/ambience/fireplace_crackle.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a96f285a6d709bbff6812ec66db19fa023e8fd4e392758ca15e278e63d85dbc
+size 1129090

assets/ambience/night_crickets.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c3b5583e377e7c18ea2ab0d2efad75e27a51ba367fb9129a48ffaf151947439f
+size 1920044

assets/ambience/ocean_waves.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:53a245f048e3f5f11673e5917fd0694696dfa841ca649d23a601ee99e0188adb
+size 1336364

assets/ambience/soft_rain.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ecb4d29fe29b3d9012f3614f4312aeb36a6bcf03c238b60470a6bc564a306344
+size 741420

assets/ambience/wind_in_trees.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3de3eb816e3ba8aacc3de300efafd8a2994b62278b44340be4d65b39a94b6ba3
+size 1920044

requirements.txt

@@ -3,3 +3,9 @@ torch
 transformers
 # Ollama must be running locally with the model below pulled:
 #   ollama pull llama3.2:3b
+# The app runtime needs nothing more (ambience.py reads beds via stdlib `wave`).
+# To (re)populate the sampled ambience beds in assets/ambience/, pick one:
+#   download from Wikimedia Commons:  uv pip install soundfile av
+#                                     python scripts/fetch_ambience.py
+#   or generate them:                 uv pip install diffusers
+#                                     python scripts/make_ambience.py

scripts/fetch_ambience.py

@@ -0,0 +1,405 @@
+"""Download the sampled ambience beds from Wikimedia Commons.
+
+A no-GPU alternative to make_ambience.py: instead of generating the seven
+sampled beds, this pulls real field recordings from Wikimedia Commons
+(public-domain / CC-licensed), trims each to a steady ~14 s loop, and writes
+mono 16-bit wavs into assets/ambience/ — the format ambience.py expects.
+
+It auto-selects: for each slug it searches Commons, drops obvious junk
+(alarms, music, traffic…) by keyword, then downloads candidates in turn and
+measures them, keeping the first that is long enough and not near-silent.
+Provenance + licence for every pick is written to assets/ambience/CREDITS.md
+so attribution can be honored when the Space ships.
+
+Usage:
+    uv pip install soundfile          # bundles libsndfile (ogg/mp3/flac/wav)
+    python scripts/fetch_ambience.py                 # fill in what's missing
+    python scripts/fetch_ambience.py ocean_waves --force
+"""
+
+import argparse
+import io
+import json
+import re
+import sys
+import time
+import unicodedata
+import urllib.parse
+import urllib.request
+import wave
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT_DIR = ROOT / "assets" / "ambience"
+API = "https://commons.wikimedia.org/w/api.php"
+UA = "LoFinity/0.1 (lofi hackathon ambience fetcher; https://huggingface.co/spaces)"
+
+TARGET_S = 30.0          # loop length we keep == default song length, so a bed
+                         # this long tiles to a 30 s song with zero seams
+MIN_SRC_DUR = 8.0        # too short to be useful ambience
+MAX_SRC_DUR = 400.0      # skip anything longer (podcasts, mixes)
+MAX_BYTES = 30_000_000   # don't pull giant wavs
+MAX_RATE = 32000         # cap stored rate (== musicgen rate); keeps files small
+
+# How to find each bed: a list of probes whose results are unioned. Commons
+# search ANDs every word in a probe, so each probe stays 1-2 words; more
+# probes = more candidates to fall back through. ("category", name) lists a
+# curated category; ("search", terms) is a File-namespace full-text search.
+SOURCES = {
+    "soft_rain": [("category", "Sounds of rain"), ("search", "rain ambience")],
+    "ocean_waves": [("search", "ocean waves"), ("search", "sea waves"),
+                    ("search", "surf beach")],
+    "fireplace_crackle": [("search", "campfire"), ("search", "fireplace"),
+                          ("search", "fire crackling")],
+    "birdsong": [("search", "birdsong"), ("search", "dawn chorus"),
+                 ("search", "birds chirping")],
+    "night_crickets": [("search", "crickets"), ("search", "cricket chirping"),
+                       ("search", "cicada")],
+    "wind_in_trees": [("search", "wind trees"), ("search", "wind forest"),
+                      ("search", "wind leaves")],
+    "cafe_murmur": [("search", "restaurant ambience"), ("search", "cafe ambience"),
+                    ("search", "crowd murmur")],
+}
+
+# Hand-vetted Commons files tried before falling back to search — auto-selection
+# can't judge "continuous dawn chorus" vs "one repetitive cuckoo", so the good
+# picks found during development are pinned here. Still run through every gate
+# below, so a renamed/deleted file just falls through to search.
+PREFERRED = {
+    "soft_rain": "File:Lluvia en techo de lamina.wav",
+    "ocean_waves": "File:Sea waves.wav",
+    "fireplace_crackle": "File:WWS Fireoftheforge.ogg",
+    "birdsong": "File:Birds singing in Fribourg 01.ogg",
+    "night_crickets": "File:Black-Prince-Cicada- Psaltoda-plaga.wav",
+    "wind_in_trees": "File:Wind in forest (Gravity Sound).wav",
+    "cafe_murmur": "File:Shopping mall less crowded.ogg",
+}
+
+# Title contains any of these (lowercased) -> not ambience, skip it. This is
+# what keeps "fire" from returning fire *alarms*, "sea" from podcasts, and
+# "waves" from sine-wave test tones.
+BLOCKLIST = (
+    "alarm", "podcast", "episode", "interview", "speech", "talk", "lecture",
+    "music", "song -", "band", "orchestra", "anthem", "hymn", "vocal", "choir",
+    "dance", "ritual", "march", "siren", "horn", "traffic", "tram", "engine",
+    "motor", "gun", "explosion", "war", "radio", "national", "voice", "demo",
+    "sine", "tone", "hz", "sweep", "beep", "dtmf", "calibration", "signal",
+    "woodwind", "clarinet", "flute", "accordion", "instrument", "guitar",
+)
+
+# Chosen file's title must contain one of these (accent-stripped) — a sound
+# actually related to the slug. Multilingual because Commons is international.
+RELEVANCE = {
+    "soft_rain": ("rain", "lluvia", "regen", "pluie", "pioggia", "chuva",
+                  "downpour", "drizzle", "storm"),
+    "ocean_waves": ("ocean", "wave", "sea", "surf", "beach", "mar", "ola",
+                    "vague", "welle", "tide", "shore", "playa", "costa"),
+    "fireplace_crackle": ("fire", "campfire", "fireplace", "crackl", "crepit",
+                          "feu", "fuego", "hoguera", "fogata", "ember", "hearth"),
+    "birdsong": ("bird", "song", "chorus", "dawn", "chirp", "cuckoo", "wren",
+                 "sparrow", "robin", "blackbird", "finch", "warbler", "thrush",
+                 "nightingale", "lark", "vogel", "oiseau", "pajaro", "canto"),
+    "night_crickets": ("cricket", "cicada", "cicad", "cigarra", "grasshopper",
+                       "grillo", "grille", "katydid", "locust", "insect", "chirp"),
+    "wind_in_trees": ("wind", "breeze", "gust", "rustl", "viento", "vent",
+                      "howl", "gale", "brisa", "blowing"),
+    "cafe_murmur": ("cafe", "restaurant", "crowd", "murmur", "coffee", "bar",
+                    "pub", "chatter", "ambien", "mall", "station", "people",
+                    "plaza", "market", "tunnel", "hall", "lobby", "gente"),
+}
+
+
+def _norm(s):
+    """Lowercase + strip accents so 'pájaro'/'Pajaro' both match 'pajaro'."""
+    s = unicodedata.normalize("NFKD", str(s))
+    return "".join(c for c in s if not unicodedata.combining(c)).lower()
+
+
+def commons_api(params, tries=5):
+    params = {**params, "format": "json", "formatversion": "2"}
+    url = API + "?" + urllib.parse.urlencode(params)
+    for i in range(tries):
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": UA})
+            with urllib.request.urlopen(req, timeout=30) as r:
+                return json.load(r)
+        except urllib.error.HTTPError as e:
+            if e.code == 429 and i < tries - 1:
+                time.sleep(2 * (i + 1))
+                continue
+            raise
+    return {}
+
+
+def find_titles(slug):
+    titles = []
+    for kind, value in SOURCES[slug]:
+        if kind == "category":
+            res = commons_api({"action": "query", "list": "categorymembers",
+                               "cmtitle": f"Category:{value}", "cmtype": "file",
+                               "cmlimit": "30"})
+            hits = [m["title"] for m in res.get("query", {}).get("categorymembers", [])]
+        else:
+            res = commons_api({"action": "query", "list": "search", "srnamespace": "6",
+                               "srsearch": f"filetype:audio {value}", "srlimit": "15"})
+            hits = [h["title"] for h in res.get("query", {}).get("search", [])]
+        titles += hits
+        time.sleep(1)
+    # dedupe (keep order); drop junk, then require a slug-relevant word
+    seen, kept = set(), []
+    for t in titles:
+        nt = _norm(t)
+        if t in seen or any(b in nt for b in BLOCKLIST):
+            continue
+        if not any(kw in nt for kw in RELEVANCE[slug]):
+            continue
+        seen.add(t)
+        kept.append(t)
+    return kept
+
+
+def file_info(titles):
+    """title -> dict(url, dur, license, artist, page) for a batch of titles."""
+    out = {}
+    for i in range(0, len(titles), 20):
+        info = commons_api({"action": "query", "titles": "|".join(titles[i:i + 20]),
+                            "prop": "imageinfo",
+                            "iiprop": "url|size|mediatype|extmetadata"})
+        for page in info.get("query", {}).get("pages", []):
+            ii = (page.get("imageinfo") or [{}])[0]
+            ext = ii.get("extmetadata", {})
+            def field(k):
+                return ext.get(k, {}).get("value", "")
+            out[page.get("title", "?")] = {
+                "url": ii.get("url", ""),
+                "dur": float(ii.get("duration") or 0.0),
+                "mediatype": ii.get("mediatype", ""),
+                "license": field("LicenseShortName") or "?",
+                "artist": _strip_html(field("Artist")) or "Unknown",
+                "page": ii.get("descriptionurl", ""),
+            }
+        time.sleep(1)
+    return out
+
+
+def _strip_html(s):
+    return re.sub(r"<[^>]+>", "", s).strip()
+
+
+def spectral_flatness(mono, rate):
+    """Ratio of geometric to arithmetic mean of the power spectrum. ~0 for a
+    pure tone, higher for broadband texture — catches test tones that slip
+    past the title filter (a 'Sine Wave' file is named like a sea 'wave').
+
+    The signal is detrended and high-passed (first difference) first: crowd
+    and surf ambience carries heavy low-frequency rumble that otherwise
+    dominates the spectrum and reads as falsely 'tonal' (calibration showed
+    real cafe recordings at 2e-5 raw vs 1e-12 for a true sine — too close;
+    after the high-pass they separate to 2e-3 vs 1e-12)."""
+    seg = mono[: rate * 4].astype(np.float64)
+    if len(seg) < 256:
+        return 1.0
+    seg = np.diff(seg - seg.mean())
+    power = np.abs(np.fft.rfft(seg * np.hanning(len(seg)))) ** 2 + 1e-12
+    return float(np.exp(np.mean(np.log(power))) / np.mean(power))
+
+
+def download(url):
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    with urllib.request.urlopen(req, timeout=60) as r:
+        length = int(r.headers.get("Content-Length") or 0)
+        if length and length > MAX_BYTES:
+            raise ValueError(f"too big ({length / 1e6:.0f} MB)")
+        return r.read(MAX_BYTES + 1)
+
+
+def decode_mono(blob):
+    import soundfile as sf
+
+    try:
+        data, rate = sf.read(io.BytesIO(blob), dtype="float64", always_2d=True)
+        return data.mean(axis=1), rate
+    except sf.LibsndfileError:
+        return _decode_av(blob)  # Opus/other codecs libsndfile can't open
+
+
+def _decode_av(blob):
+    """Fallback decoder via PyAV (bundles ffmpeg) — most Commons crowd/cafe
+    recordings are Ogg/Opus, which libsndfile doesn't support."""
+    import av
+
+    with av.open(io.BytesIO(blob)) as container:
+        stream = container.streams.audio[0]
+        rate = stream.codec_context.sample_rate
+        chunks = []
+        resampler = av.AudioResampler(format="flt", layout="mono", rate=rate)
+        for frame in container.decode(stream):
+            for out in resampler.resample(frame):
+                chunks.append(out.to_ndarray().reshape(-1))
+    if not chunks:
+        raise ValueError("no audio frames decoded")
+    return np.concatenate(chunks).astype(np.float64), rate
+
+
+def steady_window(mono, rate):
+    """Pick the best TARGET_S loop window. Short clips are returned whole (the
+    mixer tiles them). The window is scored on three things, because the mixer
+    crossfades the loop's tail back into its head:
+      - steady interior (low RMS variation) so it doesn't swell or drop
+      - head and tail at matched energy, so the crossfade blends like-for-like
+      - neither boundary in a lull, so the loop point doesn't briefly drop out
+    The last two matter for sparse textures (birdsong, fireplace): a window
+    that merely minimizes variance can still start/end in a gap, dipping ~10 dB
+    every loop."""
+    n = int(TARGET_S * rate)
+    if len(mono) <= n:
+        return mono
+    hop = max(int(rate * 0.1), 1)          # 100 ms frames: fine enough to see the seam
+    frame_rms = np.array([
+        np.sqrt(np.mean(mono[i:i + hop] ** 2)) for i in range(0, len(mono) - hop, hop)
+    ])
+    median = float(np.median(frame_rms)) or 1.0
+    win_frames = max(n // hop, 1)
+    edge = max(int(rate * 0.5) // hop, 1)  # frames spanning one crossfade (~0.5 s)
+    best, best_score = None, 1e9
+    for start in range(0, len(frame_rms) - win_frames, max(win_frames // 8, 1)):
+        seg = frame_rms[start:start + win_frames]
+        mean = float(seg.mean())
+        if mean < 0.5 * median:            # window mostly in a lull
+            continue
+        head, tail = float(seg[:edge].mean()), float(seg[-edge:].mean())
+        cv = float(seg.std()) / (mean or 1.0)
+        mismatch = abs(head - tail) / median
+        lull = max(0.0, 1.0 - min(head, tail) / median)  # 0 once boundary >= median
+        score = cv + 2.0 * mismatch + 2.0 * lull
+        if score < best_score:
+            best_score, best = score, start * hop
+    start = best if best is not None else (len(mono) - n) // 2
+    return mono[start:start + n]
+
+
+def resample(mono, src, dst):
+    if src <= dst:
+        return mono, src
+    m = int(len(mono) * dst / src)
+    return np.interp(np.arange(m) * (src / dst), np.arange(len(mono)), mono), dst
+
+
+def write_wav(mono, rate, path):
+    peak = float(np.abs(mono).max() or 1.0)
+    pcm = (mono * (0.9 / peak) * 32767).astype("<i2")
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        w.writeframes(pcm.tobytes())
+
+
+def fetch_one(slug):
+    """Return a credit dict on success, or None if nothing usable was found."""
+    found = find_titles(slug)
+    pref = PREFERRED.get(slug)
+    # the pinned pick is tried first; search results (relevance order) back it up
+    lookup, seen = [], set()
+    for t in ([pref] if pref else []) + found:
+        if t not in seen:
+            seen.add(t)
+            lookup.append(t)
+    if not lookup:
+        print(f"  no candidates found for {slug}")
+        return None
+    info = file_info(lookup)
+    for title in [t for t in lookup if info.get(t, {}).get("url")][:8]:
+        meta = info[title]
+        if meta["dur"] and meta["dur"] > MAX_SRC_DUR:
+            continue
+        try:
+            blob = download(meta["url"])
+            mono, rate = decode_mono(blob)
+        except Exception as e:  # noqa: BLE001 — try the next candidate
+            print(f"    skip {title[5:][:40]!r}: {e}")
+            continue
+        dur = len(mono) / rate
+        rms = float(np.sqrt(np.mean(mono ** 2)))
+        flat = spectral_flatness(mono, rate)
+        if dur < MIN_SRC_DUR or dur > MAX_SRC_DUR or rms < 5e-3:
+            print(f"    skip {title[5:][:40]!r}: dur={dur:.0f}s rms={rms:.3f}")
+            continue
+        if flat < 1e-3:  # essentially a pure tone, not ambience (sines ~1e-12)
+            print(f"    skip {title[5:][:40]!r}: too tonal (flatness {flat:.0e})")
+            continue
+        seg = steady_window(mono, rate)
+        seg, out_rate = resample(seg, rate, MAX_RATE)
+        write_wav(seg, out_rate, OUT_DIR / f"{slug}.wav")
+        seams = "no seam" if len(seg) / out_rate >= 30 else "1 seam @30s"
+        print(f"  {slug} <- {title[5:][:42]!r}  "
+              f"({dur:.0f}s src -> {len(seg)/out_rate:.0f}s, {seams}, {meta['license']})")
+        return {"slug": slug, "title": title[5:], "license": meta["license"],
+                "artist": meta["artist"], "page": meta["page"]}
+    print(f"  no usable file for {slug} (all candidates failed checks)")
+    return None
+
+
+def save_credits(new_credits):
+    """Merge this run's picks into credits.json (the source of truth, keyed by
+    slug) and re-render CREDITS.md. Merging means fetching one slug doesn't
+    drop the others' attribution."""
+    store = OUT_DIR / "credits.json"
+    merged = {}
+    if store.exists():
+        try:
+            merged = json.loads(store.read_text())
+        except ValueError:
+            pass
+    for c in new_credits:
+        merged[c["slug"]] = c
+    store.write_text(json.dumps(merged, indent=2, sort_keys=True))
+
+    lines = ["# Ambience sample credits", "",
+             "Auto-fetched from Wikimedia Commons by `scripts/fetch_ambience.py`.",
+             "vinyl_crackle and tape_hiss are synthesized in `ambience.py` and not listed.", ""]
+    for slug in sorted(merged):
+        c = merged[slug]
+        lines += [
+            f"## {slug}",
+            f"- **{c['title']}**",
+            f"- Author: {c['artist']}",
+            f"- Licence: {c['license']}",
+            f"- Source: {c['page']}",
+            "",
+        ]
+    (OUT_DIR / "CREDITS.md").write_text("\n".join(lines))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("slugs", nargs="*", choices=[*SOURCES, []], metavar="slug",
+                        help=f"beds to fetch (default: missing ones). One of: {', '.join(SOURCES)}")
+    parser.add_argument("--force", action="store_true", help="re-fetch even if the wav exists")
+    args = parser.parse_args()
+
+    todo = args.slugs or [s for s in SOURCES if args.force or not (OUT_DIR / f"{s}.wav").exists()]
+    if not todo:
+        print("all sampled beds already present — use --force to refetch")
+        return 0
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    credits = []
+    for slug in todo:
+        print(f"\n[{slug}]")
+        c = fetch_one(slug)
+        if c:
+            credits.append(c)
+        time.sleep(1)
+
+    if credits:
+        save_credits(credits)  # merges into credits.json, won't drop other slugs
+    got = len(credits)
+    print(f"\nfetched {got}/{len(todo)} beds -> {OUT_DIR.relative_to(ROOT)}")
+    return 0 if got else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/make_ambience.py

@@ -0,0 +1,109 @@
+"""One-off renderer for the sampled ambience beds.
+
+vinyl_crackle and tape_hiss are synthesized live in ambience.py; the seven
+beds below only need to exist once on disk. This script fills
+assets/ambience/ with text-to-audio renders from AudioLDM2.
+
+(AudioGen would also work, but it lives in the unmaintained audiocraft
+package which doesn't install on Python 3.13; AudioLDM2 ships in diffusers
+and runs next to the project's torch/transformers as-is.)
+
+Usage:
+    pip install diffusers
+    python scripts/make_ambience.py              # render whatever is missing
+    python scripts/make_ambience.py ocean_waves --force   # redo one
+
+Each clip is ~12 s; the runtime mixer tiles it with crossfades, so it does
+not need to loop perfectly. Re-run any slug whose render sounds off —
+text-to-audio is a slot machine, two pulls usually land one keeper.
+"""
+
+import argparse
+import os
+import sys
+import wave
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT_DIR = ROOT / "assets" / "ambience"
+
+PROMPTS = {
+    "soft_rain": "gentle steady rain falling on leaves, calm rain ambience, no thunder",
+    "ocean_waves": "calm ocean waves gently rolling onto a sandy beach, soft surf",
+    "fireplace_crackle": "cozy fireplace, fire crackling and popping softly",
+    "birdsong": "soft morning birdsong, small birds chirping in a quiet garden",
+    "night_crickets": "crickets chirping steadily on a calm summer night",
+    "cafe_murmur": "quiet coffee shop ambience, soft murmur of distant conversation, occasional clink of cups",
+    "wind_in_trees": "soft wind rustling through tree leaves, gentle breeze",
+}
+NEGATIVE = "music, melody, singing, speech, voice, loud, harsh, low quality, distortion"
+
+
+def write_wav(samples, rate: int, path: Path) -> None:
+    import numpy as np
+
+    peak = float(np.abs(samples).max() or 1.0)
+    pcm = (samples * (0.9 / peak) * 32767).astype("<i2")
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        w.writeframes(pcm.tobytes())
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("slugs", nargs="*", choices=[*PROMPTS, []], metavar="slug",
+                        help=f"which beds to render (default: all missing). One of: {', '.join(PROMPTS)}")
+    parser.add_argument("--force", action="store_true", help="re-render even if the wav exists")
+    parser.add_argument("--duration", type=float, default=12.0, help="clip length in seconds")
+    parser.add_argument("--steps", type=int, default=200, help="diffusion steps (more = cleaner, slower)")
+    parser.add_argument("--candidates", type=int, default=2,
+                        help="waveforms per prompt; the pipeline keeps the best text match")
+    args = parser.parse_args()
+
+    todo = args.slugs or [s for s in PROMPTS if args.force or not (OUT_DIR / f"{s}.wav").exists()]
+    if not todo:
+        print("all ambience beds already rendered — use --force to redo")
+        return 0
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    import torch
+    from diffusers import AudioLDM2Pipeline
+
+    device = os.getenv("LOFINITY_DEVICE") or ("mps" if torch.backends.mps.is_available() else "cpu")
+    print(f"first run downloads ~3 GB (cvssp/audioldm2); rendering on {device}")
+    pipe = AudioLDM2Pipeline.from_pretrained("cvssp/audioldm2")
+    pipe.to(device)
+
+    for slug in todo:
+        path = OUT_DIR / f"{slug}.wav"
+        if path.exists() and not args.force and not args.slugs:
+            continue
+        print(f"rendering {slug}: {PROMPTS[slug]!r}")
+
+        def run():
+            return pipe(
+                prompt=PROMPTS[slug],
+                negative_prompt=NEGATIVE,
+                num_inference_steps=args.steps,
+                audio_length_in_s=args.duration,
+                num_waveforms_per_prompt=args.candidates,
+            ).audios[0]  # audios come back ranked by text alignment
+
+        try:
+            audio = run()
+        except Exception as e:  # noqa: BLE001 — mps kernels are still patchy
+            if device == "cpu":
+                raise
+            print(f"  {device} failed ({e!r}), retrying on cpu")
+            pipe.to("cpu")
+            device = "cpu"
+            audio = run()
+        write_wav(audio, 16000, path)
+        print(f"  -> {path.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())