LatentScore

May 29, 2026 · View on GitHub

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 builds the full demo from source in an isolated environment — demo UI and a JupyterLab playground, no local Python needed. ~15 min first build. 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 or Linux (Python 3.11/3.12). Secondary path — use Docker for the full demo. See Try the SDK.

import latentscore as ls

ls.render("morning coffee shop").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 — tested on Linux, macOS, and Windows with Docker Desktop (WSL2 backend on Windows).

Build from source (~15 min first time, near-instant after):

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

⚠️ Apple Silicon (M-series) Macs: the build defaults to linux/amd64 for reproducibility, which runs under emulation and is slow. For a native, much faster build, prefix the command:
LATENTSCORE_DOCKER_PLATFORM=linux/arm64 docker compose -f demo/docker-compose.yml up --build

The first prompt after build takes ~30 seconds as model weights load; subsequent responses are near-instant.

Then 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

🐳 For the full demo, use Docker. The pip install path is for library/scripting use on macOS and Linux.

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

If you'd rather install locally, read on.

⚠️ Local pip installs may require system audio libraries depending on your OS. If you hit issues, use Docker or Colab instead — both include all dependencies.

4.1 Requirements

OS — macOS or Linux. Windows: use Docker Desktop with the WSL2 backend for the demo. Native Windows pip is unsupported, and WSL2 pip is not part of the supported SDK path.
Python 3.11 or 3.12 - local SDK installs require this range via package metadata. For other Python versions, use Docker or Colab.

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

Note

Linux: smaller CPU-only install. PyTorch's default Linux wheel bundles ~5 GB of CUDA libraries. LatentScore is CPU-only, so you can skip them with PyTorch's CPU index:

pip install latentscore --extra-index-url https://download.pytorch.org/whl/cpu

macOS is CPU-only already, so plain pip install is fine there.

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.