Metadata-Version: 2.4
Name: big-ddcgui
Version: 0.1.0
Summary: GTK4/Adwaita front-end for ddcutil monitor control over DDC/CI
Author: BigLinux Team
Author-email: BigLinux Team <biglinux@biglinux.com.br>
License-Expression: GPL-2.0-or-later
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Hardware
Requires-Dist: pygobject
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/biglinux/big-ddcgui
Description-Content-Type: text/markdown

![External Monitor Settings — DDC/CI monitor control](docs/banner.png)

# External Monitor Settings

> Adjust an external monitor's brightness, color and inputs over DDC/CI —
> a GTK4/Adwaita front-end for [`ddcutil`](https://www.ddcutil.com/).

![License: GPL v2](https://img.shields.io/badge/License-GPLv2-blue.svg?style=flat-square)
![Platform: Linux](https://img.shields.io/badge/Platform-Linux-informational?style=flat-square)
![GTK4](https://img.shields.io/badge/GTK-4-green?logo=gnome&style=flat-square)

![Main window](docs/screenshots/main.png)

Package: `big-ddcgui`. Works on any external monitor that supports DDC/CI;
laptop panels (eDP) do not, and aren't shown.

## ✨ Features

- **Brightness and contrast up front** — the controls you actually use, loaded
  fast in a first pass; everything else stays behind a guarded toggle.
- **Auto-detects every supported control** from `ddcutil capabilities`: sliders
  for ranges, dropdowns for inputs and presets, read-only rows for info.
- **Export / import a profile** as JSON — a superset of `ddcutil dumpvcp`,
  covering every read-write feature, not just color.
- **Translated UI** (gettext) — ships in 29 languages.

## 📦 Installation

### BigLinux

```bash
sudo pacman -S big-ddcgui      # or: yay -S big-ddcgui
```

### From source ( Manjaro / ArchLinux)

```bash
cd pkgbuild && makepkg -si     # builds from the local checkout
```

Runtime needs `ddcutil`, `gtk4`, `libadwaita`, `python`, `python-gobject`
(all native packages — no PyPI runtime dependencies).

## 🛠️ Usage

Launch **External Monitor Settings** from the app grid, or run `big-ddcgui`.
Enable **DDC/CI** in the monitor's own OSD menu first; some docks, MST hubs and
KVM switches block the channel.

The menu's **Export** writes a JSON profile of every read-write value;
**Import** replays it with `setvcp`, warning if the saved monitor differs from
the selected one and validating ranges before applying anything.

### i2c permissions

`ddcutil` needs read/write on `/dev/i2c-*`. A normal desktop session grants this
via logind `uaccess`. If detection fails:

```bash
sudo modprobe i2c-dev
sudo cp /usr/share/ddcutil/data/60-ddcutil-i2c.rules /etc/udev/rules.d/
sudo udevadm control --reload && sudo udevadm trigger
# or join the i2c group, then re-login:
sudo usermod -aG i2c "$USER"
```

Verify with `ddcutil detect`.

## 🧑‍💻 Development

```bash
python -m venv .venv && . .venv/bin/activate
pip install ruff black mypy pytest pygobject-stubs   # dev/audit tools only
PYTHONPATH=src python -m big_ddcgui
pytest && ruff check . && mypy src/big_ddcgui
```

Layout: `src/big_ddcgui/` — `ddc.py` (subprocess + pure parsers, unit-tested) ·
`models.py` · `worker.py` (serial thread; i2c is not concurrency-safe) ·
`categories.py` · `widgets.py` (per-feature rows) · `window.py` · `app.py`.
Also `po/` (catalogs) · `pkgbuild/` (wheel build via `uv_build`) · `tests/`
(parser + profile tests, no monitor required).

## 🌐 Translation

User-facing strings go through gettext (`from .i18n import _`). Refresh the
template and merge catalogs after changing strings:

```bash
./update_translations.sh        # xgettext -> po/big-ddcgui.pot, msgmerge po/*.po
msgfmt -c -v po/pt_BR.po        # validate a catalog
```

`.mo` files are compiled from `po/*.po` at package build time. New languages are
filled by the GitHub auto-translate workflow; `pt_BR` is hand-maintained.

## 🤝 Contributing

Issues and pull requests welcome. Keep patches minimal and run the floor
(`pytest`, `ruff`, `mypy`) before opening one.

## 📄 License

[GPL-2.0-or-later](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html).

## 🙏 Credits

By the [BigLinux Team](https://www.biglinux.com.br/). Built on
[`ddcutil`](https://www.ddcutil.com/), [GTK4](https://www.gtk.org/) and
[libadwaita](https://gnome.pages.gitlab.gnome.org/libadwaita/).
[Report an issue](https://github.com/biglinux/big-ddcgui/issues).
