Hermes Music + DAW

Python MIDI composition with executable arrangement checks, plus a headless MCP server for offline mixing and mastering. CPU only; no DAW window, audio interface, GPU, model download or cloud account required.

Español: README.es.md

Start here: agent protocol · architecture · documentation index · contributing.

This is an early open source toolkit. The composition checks have regression coverage; the DAW is a hardened prototype, with tests for all ten tools and a real stdio MCP session. Neither component decides whether music sounds good.

The guard exists because written corrections failed to prevent the same defects in the next composition. It checks a defined structural contract before delivery; it cannot certify timbre, genre fidelity or listening quality.

Quick start: install, test, try

From a downloaded or cloned checkout, on Linux with Python 3.12:

cd hermes-music-daw
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
sudo apt install fluidsynth fluid-soundfont-gm ffmpeg
python scripts/check_install.py
python -m pytest tests/ -q
python examples/01_compose.py --work output/demo
python examples/02_audit.py --work output/demo
python examples/03_mix_and_master.py --work output/demo

The example produces an audited MIDI, six WAV stems, a mix, a master, an OGG and JSON measurements. Use a fresh output directory for each run. FluidSynth, FFmpeg and a SoundFont are needed for audio and the full integration tests; the MIDI gates do not require an audio device. See below for configuration and limits.

Related MCP server: AI Sound MCP Server

Why the guard exists

The same bad arrangement happened twice: mechanical drums, overlapping attacks, flat dynamics, crowded instruments and GM guitars that sounded like an 8-bit mockup. The correction was already written in Markdown. It did not change the next composition.

The response was executable: read → decide → compose → audit → publish. Eight arrangement gates abort a defective delivery with exit code 1. An external audit then found faults in the author's own v2; those were corrected too. The lesson is the reason for this repository: documentation needs enforcement at the point where an artifact is delivered.

The guard records the exact MIDI's SHA-256, the plan, required readings and guard code. Editing the MIDI invalidates its receipt. This is an integrity record, not a digital signature, aesthetic certificate or security sandbox. Arbitrary code can bypass it; an agent must use the prescribed entry point.

Install

Tested with Python 3.12.3 on Linux. The main dependency versions are pinned in requirements.txt: Mido 1.3.3, NumPy 2.5.3, Pedalboard 0.9.26, FastMCP 4.1.1. The list does not lock transitive dependencies.

pip install -e . installs the runtime package without the pytest extra. The import namespace is hermes_music.scripts; console commands include hermes-music, hermes-daw, hermes-mix, hermes-music-audit, hermes-music-guard and hermes-music-check. Direct script execution also works.

SoundFont discovery checks MIDI_SOUNDFONT first, then common system locations, including FluidR3_GM and TimGM6mb. An explicitly invalid override is an error. Executables are discovered on PATH; FLUIDSYNTH, FFMPEG and FFPROBE can override them. No user-specific paths are required.

export MIDI_SOUNDFONT=/path/to/your/font.sf2  # optional when auto-detected

Offline FluidSynth subprocesses default SDL_AUDIODRIVER to dummy to avoid audio-device enumeration hangs in containers. This does not affect file synthesis. Other platforms and dependency combinations have not been verified here.

Run the small example

These scripts use the actual guard and audio engines, not placeholder media. Run them in order from the checkout, using a fresh output directory on each run:

python examples/01_compose.py --work output/demo
python examples/02_audit.py --work output/demo
python examples/03_mix_and_master.py --work output/demo

The result is a 12-bar, 18-second MIDI with three contrasting sections, six stems, a mix, a master, an OGG export and JSON measurements. The audio retains FluidSynth's release tail. The full required readings and guard output are in output/demo/composition.log. Existing guard deliveries are never overwritten.

Listen to sample.ogg, inspect sample.mid, and see sample provenance. These are GM structural demos; listening quality has not been certified. Actual run output and verification details are recorded in docs/.

For your own dense arrangement, write and review a decision plan first, then run your composer through the guard. The reference is a full 120-bar example:

python scripts/example_dense_arrangement.py --plan plan.json
# Review/adapt the plan AND composer before creating a new piece.
python scripts/composition_guard.py plan.json --out piece.mid -- \
  scripts/example_dense_arrangement.py --out '{draft}'
python scripts/audit_arrangement.py piece.mid --json review.json
python scripts/composition_guard.py --verify piece.mid

Follow PROTOCOL.md for rendering, mixing, mastering and publication. Low-level hermes-music recipes, compose, gen, validate, render and rebuild remain available. validate alone does not approve an arrangement. Genre plans from genre_engine.py are harmonic guides, not finished songs.

Architecture and file map

readings + decision plan + composer
                  ↓ composition_guard (subprocess, temporary MIDI)
               audit_arrangement: 8 gates
                  ↓ exact MIDI + SHA-256 receipt
           FluidSynth / SoundFont → instrument WAV stems
                  ↓ mix_engine: role chains + stereo balance + bus
              daw_mcp.master: bus chain + FFmpeg loudnorm
                  ↓ WAV → OGG → release_check → human listening

The legacy dembow, harmonic-circle and MIDI-effect scripts remain in scripts/ as experimental standalone utilities with known implementation defects; see the MIDI-effect reference. They do not issue guard receipts and are outside the tested composition/audio workflow. build_index.py is a Hermes-specific adapter requiring a separate skills-index plugin.

MCP tools and clients

Start with list_profiles, then follow the protocol. Audio paths are local to the machine running the server. WAV is the processing format; analyze_audio and release_check can also inspect an OGG supported by the installed decoder.

The MCP exposes the audio stage. Composition and guard verification run through the CLI. MCP render tools can process arbitrary MIDI; they do not implicitly certify it. Bad paths, corrupt/empty/silent audio and unknown profiles return clear tool errors. All processing occurs in memory; long stems use more RAM.

After installation, this configuration launches the package from any working directory. Replace the interpreter path with the absolute path of your venv's Python. Optional env settings must be valid on the server host.

{
  "mcpServers": {
    "hermes-daw": {
      "command": "/absolute/path/to/hermes-music-daw/.venv/bin/python",
      "args": ["-m", "hermes_music.scripts.daw_mcp"],
      "env": {"MIDI_SOUNDFONT": "/usr/share/sounds/sf2/FluidR3_GM.sf2"}
    }
  }
}

• Claude Desktop: Settings → Developer → Edit Config; merge the entry into claude_desktop_config.json, then restart. See the official local-server guide.

• Cursor: merge the JSON into project .cursor/mcp.json or personal ~/.cursor/mcp.json, then restart. See Cursor's instructions.

• Hermes: add the following under mcp_servers in ~/.hermes/config.yaml and restart Hermes. See Hermes MCP documentation.

mcp_servers:
  hermes-daw:
    command: /absolute/path/to/hermes-music-daw/.venv/bin/python
    args: ["-m", "hermes_music.scripts.daw_mcp"]
    env:
      MIDI_SOUNDFONT: /usr/share/sounds/sf2/FluidR3_GM.sf2

Configuration formats were checked against those upstream guides. GUI client connections were not exercised; the automated test performs handshake, tools/list and calls all ten tools over real stdio MCP. The server needs no HTTP port or authentication setup. It runs with the host user's file permissions.

In a restricted Linux sandbox that denies socketpair.send(), set HERMES_DAW_STDIO_POLL=1 in the server's env. This enables a 50 ms event-loop timer so thread-based stdio can wake correctly. The local protocol test uses this compatibility mode for both server and client; normal desktop use does not require it.

Mix profiles

power_metal and balanced are engineering starting points. Stems must use exact role names; an unknown name aborts instead of silently losing an instrument. A subset of roles is allowed. Both profiles now include the reference's lead_guitar and synth_piano, alongside the original L/R lead roles.

HPFs reduce low-frequency competition, shelves shape tonal balance, compression controls dynamics and balance separates doubled parts. These choices require listening. Full parameters and interpretation.

Honest limits

• GM is a mockup renderer. It does not reproduce realistic distorted guitars, palm mute, playing technique, convincing vocals or studio production.

• The auditor checks a structural contract, not taste or genre fidelity. Its dense contract supports 4/4. It intentionally rejects some musically valid choices; other styles need separately designed and tested contracts.

• 73 genre profiles are provisional and unaudited by listening. The catalogue has 100 labels and 104 variants, with 22 direct-source and 5 family-source profiles. There are only 15 distinct legacy drum grids. The harmonic planner does not generate a genre's full instrumentation.

• Masking is heuristic. Correlated octave energies do not prove that a part is inaudible. RMS is not LUFS; sample peak is not true peak. True peak and LUFS are measured separately using FFmpeg.

• A release verdict is a limited technical screen. It cannot find every audible defect, certify dynamics from a single threshold or replace listening. Mastering targets may be constrained; inspect target_met and the final codec.

• Stem rendering expects one named instrument channel per note track. Split multichannel type-0 tracks first. Shared controllers/programs across tracks are not reconstructed; keep each instrument's controls in its own track.

• Receipts currently depend on absolute paths and exact code/readings. Re-run the guard after moving a checkout or changing its bound files. Hashes are integrity evidence, not protection against a malicious writer.

• No perceptual reference matching, automated aesthetic judgment, neural audio generation, real-time DAW session or validated performance benchmark is claimed.

Tests and license

python -m pytest tests/ -q

Tests generate audio and regression MIDI locally. Audio integration tests need the system dependencies above; CI installs them on Python 3.12. The original 33 composition tests and 100 catalogue subtests are retained; private desktop fixtures were replaced with reproducible defect-class fixtures.

Original source: MIT. Pedalboard is GPL-3.0 and FluidR3 has its own upstream license. Neither is relicensed by this project's MIT notice; see third-party notices. The SoundFont is not bundled.