moondrop_control.py

Read and write flags compose, and are applied in a fixed order with --save-flash last — so one invocation can preview a change and then persist it. --json and -i are exclusive modes and ignore the rest.

$ python3 moondrop_control.py --set-peq 0 peaking 1000 -3 1 --no-flash --save-flash
#                            └─ written live to the DSP ─┘  └─ then committed ─┘

Writes go to flash by default. --no-flash applies them to the DSP only, so you can audition a change and walk away from it — unplug the DAC and it is gone.

Moondrop Hub carries about 59,700 user-made curves from 19,900 authors. Reading needs no account, no key and no token, so these two flags browse it — and only ever read. Publishing, liking and favouriting need a login and are deliberately not implemented.

$ python3 moondrop_control.py --presets --search "harman" | jq '.presets[0]'
{
  "uuid": "4ba6fbe4-6a97-48f1-b487-9d2a640ee30c",
  "title": "水月雨aria2 模拟入耳式耳机使用哈曼2019在HEAD acoustics第三代人工头曲线",
  "author": "rockyuan",
  "downloads": 31072,
  "likes": 604,
  "file": "peq-config-file/fQ0QdflTTrx27gduE14KQpeq.txt"
}

• You get your whole device family's presets, not just your model. The server pools by the app's sharedConfigGroupId, so a DAWN PRO2 sees ~6,900 curves (its own 1,270 plus every other FreeDSP-family device).
• The index is cached for a day under ~/.cache/hub_moon/. It has to be: the API has no pagination at all — productUuid is the only parameter it honours, and page, limit and sortBy return zero rows rather than being ignored. The smallest possible request is the entire ~3.6 MB index for your device, so --search runs locally over all of it.
• Neither flag opens the DAC — strace-verified, zero /dev/hidraw opens — so browsing cannot collide with a GUI that is mid-write.
• Published presets carry no pre-gain, unlike AutoEQ. A loud community curve will clip unless you set your own headroom.
• Bands with no filterType become peaking, which is what the official app does, and it is the common case: most published bands omit the field.
• The product-UUID table is hardcoded, because the API's own products/all reports pid: null for all 102 products — --registry reports the UUIDs it uses.

The CLI is designed to be driven. --json reports the full device state, and everything device-shaped comes from there rather than being reimplemented in the caller: band count, which slot custom PEQ lives on, whether the device supports pre-gain at all. This file stays the single source of truth for the device registry.

Identifying the DAC from the system side

PipeWire is not the source of truth for playback, so there are two paths:

• Normally the sink node carries alsa.components = USB35d8:011d — the USB pair, no name-matching needed — and it updates reactively on hotplug.
• A bit-perfect player (SONE, TIDAL) opens the card directly through exclusive ALSA. PipeWire never sees that stream, so defaultAudioSink will happily report "Speaker" while the music is physically going through the DAC — and PipeWire may hold no node at all for a card it cannot open. The fallback asks the kernel instead: whoever holds /proc/asound/card*/pcm*p/sub* outside pipewire, identified by that card's /proc/asound/cardN/usbid — the same 35d8:011d pair, available whether or not PipeWire has any idea the device exists.

What the desktop app does

It is the worked example: it imports moondrop_control and calls the hardware-tested engine rather than reimplementing the protocol, runs all HID I/O on one worker thread so a read never interleaves with a write, and gives the community library and the file dialogs threads of their own.

• The DSP runs at a fixed 96 kHz internal sample rate; biquad coefficients are computed against that regardless of the playback rate.
• Coefficients use the standard Bristow-Johnson formulas, packed as Q2.30 signed 32-bit integers in the layout [b0, b1, b2, -a1, -a2]. This matches the official web app's packing function exactly.
• --stream-status reads /proc/asound and is Linux-only. Everything else is cross-platform through hidapi.
• --import-rew reads REW's exported filter text: it maps PK/LS/HS/LP/HP, honours the Preamp line, and disables any bands the file does not define. Filters past the device's band count are skipped with a note.
• Read/write flags compose and are applied in a fixed order, with --save-flash last. --json and -i are exclusive modes and ignore the rest.

Q2.30 spans only [−2, 2), and some otherwise reasonable filters need coefficients outside it. This tool refuses those with an error naming the safe ceiling. Two cases.

Findings from reverse-engineering the official web app, verified against its JavaScript and — where marked — against real hardware. The full write-up, including hosts, endpoints and the product-UUID table, is in the repository.

• Coefficient packing is Q2.30, layout [b0, b1, b2, -a1, -a2], scaled by 2³⁰ and computed against a fixed 96 kHz DSP rate. Confirmed byte-for-byte against the web app's own packing function, and corroborated by an independent reimplementation.
• The device registry is transcribed from the app, correcting a scrambled name/ID mapping: 0x011D is DAWN PRO2 (confirmed against real hardware), 0x43DA is MOONRIVER 3, 0x011B is Rays. "Rays Pro" does not exist. E.S. combo uses custom-PEQ profile slot 4; every other supported device uses 7.
• Old Fashioned (0x0122) is detected but refused. It does not use biquad coefficients at all — it writes PEQ through device registers as int8 gain ×10, uint16 frequency and int16 Q ×1000, exposes 5 bands, and reports no pre-gain or global-gain support.
• HID replies must be matched to their request. A response echoes the command and sub-command it answers at bytes 1–2. Commands that never reply would otherwise leave the next read picking up the previous command's report, shifting every subsequent read by one and silently returning another register's data.
• The active EQ profile is not a PEQ-mode indicator — see below.

On a DAWN PRO2 the equaliser is toggled on the hardware: press both volume buttons to switch between the default (no EQ) mode and custom EQ. If your edits are inaudible, check that first — PEQ writes only affect the sound in custom-EQ mode.

That toggle is not reflected in any register we could find: sweeping every readable sub-command (0–254) returns byte-identical data in both modes, so this tool cannot tell you which mode you are in. --info reports the active EQ profile, but on firmware 1.5 that reads 9 in both modes while PEQ writes are audible in custom EQ regardless. Do not read anything into that number.

Unofficial and not affiliated with Moondrop. The USB HID protocol here was reverse engineered from the official web app with the assistance of AI. The coefficient packing and PEQ byte layout have since been checked against that app's own JavaScript and match it exactly, but the command set is still inferred from observed behaviour rather than any documented spec — treat it as a best-effort reconstruction that works on the hardware it was tested against, not as authoritative.

This script is tested with the Moondrop DAWN PRO2 only, which works as intended though further ironing is necessary. Other devices require testing by people who own them — see what has actually been exercised.