dgm20-linux/README.md

# dgm20-linux

Control the **Maono DGM20** USB microphone on Linux. Maono Link only runs on Windows and macOS;
this covers the same settings with a local web page and a command-line tool.

![The control page](docs/screenshot.png)

- Noise cancellation on/off and strength
- Vocal enhancement
- Hear yourself (headphone monitoring)
- Mute, kept in sync with the mic's touch pad
- Factory reset

Pure Python, no dependencies. Nothing leaves your machine: the page is served from your own
computer and loads no external fonts or scripts.

> Unofficial. Not affiliated with or endorsed by Maono.

## Supported hardware

| Model | USB ID | Status |
|-------|--------|--------|
| DGM20 | `352f:0105` | Supported, tested on firmware 2.1.2 |
| DGM20 (newer revision) | `352f:0112` | Not yet |
| DGM20G, DGM20W | `352f:0113`, `352f:041a`-`041d` | Not yet |

Find your mic's ID with `lsusb | grep -i maono`. If you have one of the unsupported models and want
to help, open an issue with that output.

## Install

You need Python 3.9 or newer with `venv` (Debian and Ubuntu: `sudo apt install python3-venv`).

```sh
git clone https://git.reiners.io/justin/dgm20-linux.git
cd dgm20-linux
./install.sh
```

Then unplug the mic and plug it back in once.

The installer:

1. puts the program in its own virtualenv under `~/.local/share/dgm20-linux`, with the commands
   `dgm20ctl` and `dgm20-web` linked into `~/.local/bin`, and
2. asks for sudo once to add a udev rule (`/etc/udev/rules.d/70-maono-dgm20.rules`) that lets you
   use the mic's control channel without root.

Run it as your normal user, not with sudo.

### Options

| Option | What it does |
|--------|--------------|
| `--service` | Runs the control page in the background now and every time you log in (systemd user service). |
| `--lan` | Lets other devices on your network open the page too. Opens the port in firewalld or ufw for your local subnet only. Implies `--service`. |
| `--port N` | Uses a different port (default 8720). |
| `--group NAME` | Group allowed to use the mic from ssh sessions. Default: the first of `plugdev`, `wheel`, `sudo` that you belong to. Desktop logins always have access. |
| `--no-udev` | Skips the udev rule. |
| `--dry-run` | Prints every change instead of making it. |

`--lan` has no login. Anyone on your network can change your mic settings, so only use it on a
network you trust. If you run a firewall other than firewalld or ufw, the installer tells you what
to allow.

### Uninstall

```sh
./uninstall.sh
```

This removes everything the installer added: the service, firewall rule, udev rule and program
files. The installer keeps a record of what it changed, so only those changes are undone. Your mic
keeps its current settings.

## Use

```sh
dgm20-web --open             # open the control page (http://localhost:8720)
dgm20ctl                     # show current settings
dgm20ctl set nc on nc-level 80
dgm20ctl set monitor off enhance on
dgm20ctl watch               # print changes made on the mic itself
dgm20ctl info                # model and firmware
dgm20ctl factory-reset --yes
```

| Setting | Values |
|---------|--------|
| `mute` | on, off |
| `nc` | on, off: noise cancellation |
| `nc-level` | 0-100: noise cancellation strength |
| `enhance` | on, off: vocal enhancement |
| `monitor` | on, off: hear yourself in headphones plugged into the mic |

Settings are stored on the mic, so they stay the same after a replug and on other computers.

Input gain and headphone volume are standard USB audio controls. Set them in your desktop's sound
settings, `pavucontrol` or `alsamixer`.

### Using the page from another computer without opening a port

If the mic is plugged into a machine you reach over ssh, forward the port instead of using `--lan`:

```sh
ssh -L 8720:localhost:8720 that-machine
```

Then open http://localhost:8720 on your own computer.

## Troubleshooting

**"no permission to open /dev/hidrawN"**: the udev rule isn't applied yet. Unplug and replug the
mic. Over ssh, make sure you're in the group the installer printed (`id -nG`). If you were just
added to that group, log in again.

**"DGM20 (352f:0105) not found"**: check `lsusb | grep -i maono`. A different USB ID means a
model that isn't supported yet (see above).

**The page says "Mic not found"**: plug the mic in. The page reconnects by itself.

**`dgm20-web: cannot listen on 127.0.0.1:8720`**: it's already running, for example as the
service. Open http://localhost:8720, or pick another port with `--port`.

**"the mic is connected but has stopped answering"**: the mic's settings channel froze. This can
happen if you hold or tap the mic's buttons while settings are being changed from the computer.
Unplug the mic and plug it back in; its settings are kept. A software USB reset is not enough,
the mic needs to lose power.

**Commands not found after installing**: `~/.local/bin` isn't on your `PATH`. Add
`export PATH="$HOME/.local/bin:$PATH"` to your shell profile.

**Service stops when you log out**: run `sudo loginctl enable-linger $USER`.

## How it works

The mic has a vendor HID channel next to its audio interfaces. The settings were found by reading
Maono Link's DGM20 plugin and then checked against a real mic. [PROTOCOL.md](PROTOCOL.md) documents
the packet format and register map. `dgm20ctl raw get|set|dump` gives direct register access for
exploring.

## Development

```sh
PYTHONPATH=src python3 -m unittest discover -s tests
PYTHONPATH=src python3 -m dgm20.web
```

## License

MIT