latentscore 0.1.6

Generate ambient music from text. Locally. No GPU required.

LatentScore

Generate ambient music from text. Locally. No GPU required. - Read more about how it works.

https://private-user-images.githubusercontent.com/140295281/557606724-22889dcc-9287-4712-8ffb-ec19381444c9.mp4?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzI1NTQ3OTcsIm5iZiI6MTc3MjU1NDQ5NywicGF0aCI6Ii8xNDAyOTUyODEvNTU3NjA2NzI0LTIyODg5ZGNjLTkyODctNDcxMi04ZmZiLWVjMTkzODE0NDRjOS5tcDQ_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwMzAzJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDMwM1QxNjE0NTdaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT03Y2IzMzNlMzhiYTAyZDRmMjE0OWY4ZmNiMmUxNzE4ZTE0YjMzZWU0OGE5MmQyOWYzMzYzZWViYmY5MWNjZWM4JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.VDGlSlEVudf_rmavZpjUqkImO0O1gUYxEqDvDx6PQNo

---

1. Try it now

Four ways:

• 🎧 Hear it now - latentscore.com/demo. Browser, no install.
• 🐳 Run the demo + JupyterLab locally - docker compose gives you the demo UI and a JupyterLab playground where you can poke at the SDK without pip install. ~60s on any OS. See Try the demo.
• 🟧 Open in Colab - free CPU runtime, no local setup, no key required.
• 🛠 Build with it locally - pip install latentscore on macOS, Linux, or Windows WSL2. See Try the SDK.

import latentscore as ls

ls.render("warm sunset over water").play()

That's it. One line. You get audio playing on your speakers.

---

2. Try the demo

No install needed: open latentscore.com/demo in your browser.

Run it locally - works on macOS, Linux, or Windows WSL2 with Docker Desktop.

Fast - pull pre-built images (~60 s):

docker compose -f demo/docker-compose.yml up

From source - reproducibility build (~10 min, first time only):

docker compose -f demo/docker-compose.yml up --build

Either way, open:

• localhost:4242 - demo UI
• localhost:8889 - JupyterLab playground (SDK pre-installed)

See the demo documentation for architecture, dev setup, and troubleshooting.

---

3. Contents

• Try it now - four ways to get going (browser, Docker, Colab, pip)
• Try the demo - deeper Docker setup
• Try the SDK - Colab (recommended) or local install
• CLI - latentscore doctor, download, demo
• Quick start - Python in 5 lines
• Controlling the sound - MusicConfig parameters
• Read more - docs, FAQ, research pipeline, contributing
• Citation - SIGGRAPH Talks '26 BibTeX
• Documentation - streaming, live playlists, async, bring-your-own-LLM
• FAQ - common questions

---

4. Try the SDK

🟧 Easiest path: Open the Colab notebook — same SDK, free CPU runtime, no install, no system deps to wrangle.

If you'd rather install locally, read on.

⚠️ System dependencies vary by OS. Local audio playback and WAV I/O depend on native libraries that don't ship with pip — libportaudio (for live playback via sounddevice) and libsndfile (for soundfile). Typical install:

• macOS: brew install sox
• Linux: apt install sox libasound2-dev
• Windows: WSL2 only (see FAQ)

Skip all of this by running in Colab — everything's preinstalled.

4.1 Requirements

• OS - macOS, Linux, or Windows ONLY via WSL2. For the web UI on any OS, use the Docker demo instead.
• python 3.11 to python 3.12 - we test against 3.12 (matches our Docker image). Or use conda for environment management.

4.2 Install

With venv (regular Python):

python3.12 -m venv .venv
source .venv/bin/activate
pip install latentscore

With conda:

conda create -n latentscore python=3.12 -y
conda activate latentscore
pip install latentscore

4.3 What you get

The default install gives you text prompts, full parameter control, and local playback. See the Quick start below.

Optional extras:

Install	Adds
pip install "latentscore[external]"	bring-your-own hosted LLM via LiteLLM (Anthropic, Gemini, OpenAI, …)
pip install "latentscore[heavy]"	CLAP audio-based retrieval (fast_heavy model)
🚧 pip install "latentscore[expressive]"	local LLM inference. Extremely experimental, under testing.

4.4 Verify your install

latentscore doctor --strict --offline

Exits non-zero with a clear hint if anything's broken. Add --json for machine-readable output.

---

5. CLI

⚠️ The CLI ships with the SDK install — same system-deps caveats as Try the SDK above. Skip the headache by running the Colab notebook instead; most of these CLI commands have equivalent Python calls (ls.prefetch(...), ls.render(...)) you can run there.

# Verify your install
latentscore doctor                       # human-readable summary
latentscore doctor --strict --offline    # nonzero exit if anything's broken
latentscore doctor --json                # machine-readable output

# Pre-download model assets (otherwise the first render call appears to hang)
latentscore download fast                # ~90 MB, MiniLM embedding model
latentscore download fast_heavy          # ~1.8 GB, LAION-CLAP weights

# Render a sample clip
latentscore demo                         # play a short ambient clip
latentscore demo --duration 30 --output ambient.wav   # 30 seconds, save to file

---

6. Quick start

🟧 Don't want to install? Try the same code in Colab — free CPU runtime, no install.

6.1 Render and play

import latentscore as ls

# Optional one-time setup: pre-download the embedding model (~90 MB) so
# the first render() call doesn't appear to hang. The download happens
# on the first render anyway; this just makes it explicit and visible.
ls.prefetch("fast")

audio = ls.render("morning coffee shop", duration=10.0)
audio.play()              # plays on your speakers
audio.save("output.wav")  # save to WAV

6.2 Different vibes

ls.render("morning coffee shop").play()
ls.render("thunderstorm on a tin roof").play()
ls.render("tension over a treasured object").play()

---

7. Controlling the sound

Beyond text prompts, you can drive synthesis directly:

import latentscore as ls

# Full control: build a MusicConfig with human-readable labels
config = ls.MusicConfig(
    tempo="slow",
    mode="dorian",
    root="d",
    bass="drone",
    pad="ambient_drift",
    melody="contemplative",
    rhythm="minimal",
    texture="shimmer",
    echo="heavy",
    density=3,
    brightness="dark",
    space="vast",
)
ls.render(config, duration=10.0).play()

# Or start from a vibe and slam knobs to opposites
ls.render(
    "morning coffee shop",
    update=ls.MusicConfigUpdate(
        tempo="very_fast",
        brightness="very_dark",
        echo="infinite",
    ),
).play()

See the full documentation for the parameter reference, relative-step updates, streaming, live playlists, async API, and bring-your-own-LLM cookbook.

---

8. Read more

• Documentation - parameter reference, streaming, async API, bring-your-own-LLM
• FAQ - first-call hang, system deps, Windows, citation, …
• Retrieval map card - what powers the default fast model: row schema, construction pipeline, models used, biases, license
• Research pipeline - how the dataset was built
• Contributing - setup + style rules
• Demo - run the web demo locally

---

9. Citation

If you use LatentScore in your research, please cite the SIGGRAPH Talks '26 paper:

@inproceedings{gupta2026latentscore,
  author    = {Gupta, Prabal},
  title     = {LatentScore: Sketching Soundscapes with LLM-Distilled Retrieval for Procedural Synthesis},
  booktitle = {SIGGRAPH Talks '26},
  year      = {2026},
  publisher = {ACM},
  doi       = {10.1145/3799818.3812120}
}

---

10. License

LatentScore is released under the Apache License 2.0.