onbgm

onbgm

English · 简体中文 · Website: onbgm.com

Instrumental background music, written note by note by AI agents. An agent writes a plain-text score (YAML): sections, chords, melodies, drum patterns. onbgm arranges, performs, mixes and renders it into a finished track.

Unlike prompt-to-audio models, the music is text you can read and diff:

• Exact timing. Tempo, section boundaries, "the climax lands at 0:42" and loop points are exact, not approximate.
• Local edits. Say "bring the climax in 4 bars earlier" in a chat; the agent edits those 4 bars, and everything else stays identical, note for note.
• Reproducible. The same score always renders to the same audio.
• No vocals, by design. onbgm is for BGM: videos, games, podcasts, apps.

Listen

Each track below was composed end to end by a Claude agent using onbgm:

• the agent read the docs, wrote the score, rendered drafts, read the loudness and balance reports, and revised;
• a second agent reviewed the score before it was accepted.

Click a piano roll to play the MP3, or open the score that produced it.

The comments at the top of each score are the agent's own composition notes, written in Chinese.

How it works

agent ──writes / edits──▶ score YAML ──▶ strict validation + timeline solving ──▶ textures + humanization ──▶ notes
              ▲                                                                                              │
              │                                stems (built-in sampler · SFZ libraries · synth · SF2 via FluidSynth)
              │                                                                                              │
              └── report: loudness vs. energy, part balance, warnings, piano roll ◀── mix (role levels, seating, hall) → master

The agent describes what the music should do. The engine handles how it is performed: velocity, pedaling, expression, micro-timing, voice leading, mixing and mastering.

A score at a glance

meta: {bpm: 84, key: "A minor", loop: true}
sections:
  - {name: intro, bars: 4, energy: 0.3}
  - {name: theme, bars: 8, energy: "0.5->0.8"}
harmony:
  intro: "Am | F | C | G"
  theme: "Am | F | C | G | Dm | F | Esus4 | E"
tracks:
  keys:  {sound: epiano, texture: comp, rhythm: "x--- ---- x-x- ----"}
  bass:  {sound: electric-bass, texture: bassline, rhythm: "1--- ---- 1-5- ----"}
  drums:
    sound: drums-jazz
    texture: groove
    in: [theme]
    pattern: {kick: "x... ...x ..x. ....", snare: ".... x..g .... x...", hat: "x.x. x.x. x.x. x.x."}
  lead:
    sound: vibraphone
    texture: melody
    in: [theme]
    notes:
      theme: "E5/4. D5/8 C5/4 A4/4 | C5/2 r/2 | G5/4. E5/8 D5/4 C5/4 | D5/2 r/2 |
              F5/4 E5/4 D5/4 C5/4 | A4/2 C5/4 D5/4 | B4/2 G#4/2 | A4/1"

Chords are written per bar. Accompaniment uses textures, such as arpeggio, pad, comp, strum, bassline and groove. Melodies are written note by note. The engine also supports:

• per-section tempo changes and ritardandos;
• 3/4, 6/8 and 12/8 meters;
• swing and lo-fi coloring;
• seamless loops;
• a sound-effect timeline (risers, impacts, whooshes) that stays in sync with the music.

The full format is in skills/onbgm/references/score-format.md, and the JSON Schema is in schema/score.schema.json.

Quick start

brew install fluid-synth                  # Debian/Ubuntu: sudo apt install fluidsynth
uv tool install onbgm                     # or: pip install onbgm
onbgm fetch                               # download sound libraries to ~/.onbgm/sounds (~1.7 GB; set ONBGM_SOUNDS to change)
onbgm doctor                              # check the environment

onbgm init my_bgm --example late_study    # start from an example
onbgm catalog -q "lazy lo-fi drums"       # search ready-made patterns
onbgm check my_bgm/score.yaml             # validate and print the timeline
onbgm fit 0:07.3=reveal 0:21.8=feature --length 0:45 --write video.yaml   # scoring a video: tempo + structure from cut points
onbgm render my_bgm/score.yaml -o my_bgm/out/v1               # render
onbgm render my_bgm/score.yaml -o my_bgm/out/v1 --soundset gm # GM sounds only (fast, light)
onbgm review my_bgm/out/v1 --compare my_bgm/out/v0            # listen in the browser, A/B, leave comments

Every command supports --json. Errors come with a location, a reason and a fix, so an agent can act on them directly.

Output files:

• loop.wav: a sample-accurate seamless loop. Non-looping tracks get song.wav, with the exact score length.
• preview.mp3, song.mid, stems/, pianoroll.png.
• player.html: a self-contained player with a piano roll, sections and chords.

For agents

The agent-facing docs are in skills/onbgm/, organized as a skill:

• SKILL.md: the workflow, how to read the render report, and the rules.
• references/cli.md: commands, --json output and error codes.
• references/score-format.md: the complete score format.
• references/arranging.md: how to write good BGM, with recipes per style.

The docs are currently in Chinese. Agents read them without trouble; an English translation is planned.

Reviewing in the browser

onbgm review out/v2 --compare out/v1 opens a local page where you can:

• see the piano roll, sections, chords and sound effects, and click anywhere to play from there;
• switch seamlessly between two versions at the same position;
• leave comments on the timeline.

Comments are saved to review.json. Each one includes the time, bar, beat, section and chord, so the agent can act on it directly.

Examples

cafe_jazz and vlog_intro were written by fresh agents that had only read the docs. experiments/ keeps the raw records of those usability tests.

Sounds

Samples are played by the built-in sampler (onbgm/sampler.py), which reads SFZ directly and uses soxr for high-quality pitch shifting. On top of what the libraries define, it calibrates a few things:

• Onsets. It compensates sample pre-roll so attacks land on the beat.
• Dynamics. It level-matches velocity layers and round robins.
• Tuning. It retunes hand-played samples.
• Extras. It can add vibrato or effect chains, such as the distorted guitar's amp and cab.

All downloads are pinned to a specific version, so library updates never change how an existing score sounds. If an hq library is missing, that instrument falls back to GM.

Design principles

• The agent describes intent; the engine performs. Velocity, pedaling, expression and timing nuance come from texture code, not from the agent.

• Local edits stay local.

  • Humanization is keyed by part, section, position and pitch.
  • Voice leading restarts every section.
  • Accompaniment levels come from each part's configuration, not its content.
  • Mastering uses a fixed gain.

  So editing one section leaves every other section bit-identical.

• The agent doesn't have to mix. Parts are leveled by role, the melody is balanced against each section's accompaniment, and a look-ahead limiter catches peaks.

• Errors are written for agents. Every error states its location, the reason and the fix. Typos get a "did you mean". Unknown fields are always errors, never silently ignored.

FAQ

On Linux, onbgm crashes with Illegal instruction, or reports pedalboard_illegal_instruction. This is a known issue in the audio library pedalboard (spotify/pedalboard#454). Its Linux x86 wheels up to 0.9.25 are compiled for the build machine's CPU, so they crash on some CPUs, such as certain AMD EPYC servers. Upstream has fixed it, and the fix is waiting for a release. Until then, onbgm detects the problem at startup and prints the commands to build the fixed version (about 4 minutes).

Development

uv venv && uv pip install -e ".[dev]"   # in a source checkout, sounds download to ./sounds
.venv/bin/python -m pytest              # audio tests skip themselves without fluidsynth or sounds

See CONTRIBUTING.md for conventions and for adding instruments or sample libraries, and ROADMAP.md for scope and plans.

License

The code is MIT-licensed.

The sound libraries are not part of this repository. onbgm fetch downloads them from their authors, and their licenses are listed in the table above. For music made with them:

• the CC0 libraries (VSCO, VCSL, jRhodes, the Karoryfer libraries, FreePats ukulele and accordion, the erhu) have no requirements;
• the authors of GeneralUser GS, the FSS guitar and the AVL kits state explicitly that music made with them is free to use, including commercially;
• Salamander Grand Piano is CC-BY 3.0, and its author says nothing specific about music made with it. To be safe, credit "Piano: Salamander Grand Piano by Alexander Holm (CC-BY 3.0)" when publishing work that uses the piano.

Contact

contact@onbgm.com