commit 3a2524c149061f2dc70c39c29842f95bfbcb5759
Author: pyrshctjag <pyrshctjag@gmail.com>
Date:   Mon May 4 02:43:00 2026 +0400

    docs: added readme

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..86a0c99
--- /dev/null
+++ b/README.md
@@ -0,0 +1,187 @@
+# Headless OBS Studio on Proxmox LXC
+
+Данный репозиторий содержит конфигурационные файлы для развертывания `obs-studio` в *headless*-режиме внутри контейнера **proxmox** (**lxc**) с пробросом **gpu** и **usb**-устройств захвата.
+
+## Сравнение дистрибутивов
+
+В процессе разработки были протестированы два окружения. Ниже приведен критический анализ возникших проблем:
+
+| Характеристика | Alpine Linux | Debian 13 |
+|:---:|:---|:---|
+| **Графический стек**	| `wayland` + `cage` + `wayvnc`	| `x11` + `xvfb` + `x11vnc` |
+| **Работа с железом**	| Успешно: Стабильный захват `v4l2`	| Критическая ошибка: Segfault в `linux-v4l2.so` |
+| **Управление** |	Проблема: Отсутствие плагина `obs-websocket` в репозиториях | Успешно: Полная поддержка `obs-websocket` |
+| **Итог** | Идеально для картинки, невозможно управлять удаленно | Отличное управление, невозможно использовать родной `v4l2` |
+
+### Почему **alpine** не подошел:
+
+Основной блокирующий фактор — отсутствие нативной сборки `obs-websocket` в `apk` репозиториях. Поскольку проект требует удаленного управления через *api*, **alpine** без сложной ручной компиляции плагина оказался нежизнеспособен.
+
+### Почему **debian** не подошел:
+
+На ядре **proxmox** (`7.0.0-3-pve`) стандартный плагин `linux-v4l2.so` в **debian 13** вызывает ошибку обращения к памяти (`segmentation fault`) при инициализации устройств захвата.
+
+## Текущий стек (arch + wayland)
+
+После тестирования **alpine** и **debian**, финальным и наиболее стабильным решением стал **arch** в контейнере **lxc**. Это позволило получить доступ к свежим версиям `obs-studio` и плагина `obs-websocket` без проблем с сегфолтами ядра **proxmox**.
+
+### Архитектурная схема
+
+| Компонент | Технология | Описание |
+| :---: | :--- | :--- |
+| ОС | **arch linux** | Свежие репозитории и ядро, обеспечивающие совместимость с современными плагинами. |
+| Графический стек | `wayland` + `cage` |Использование киоска для запуска `obs-studio` без тяжелого DE. |
+| Удаленный доступ | `wayvnc` + `novnc` | Доступ к *gui* через браузер по вэбсокету. |
+| Управление | `obs-websocket`| Нативная поддержка управления через *api* из коробки. |
+| Работа с видео | `v4l2-input` | Стабильная работа вэбки и карты захвата без ошибок памяти. |
+
+### Почему Arch Linux оказался идеальным решением:
+
+Наличие `obs-websocket`: В отличие от **alpine**, пакет `obs-studio` в **arch** включает в себя актуальные плагины управления.
+
+Исправленный `v4l2`: Плагин `linux-v4l2.so` в сборке **arch** не вызывает `segmentation fault` при инициализации устройств захвата на ядре **proxmox**.
+
+Минимализм: Использование композитора `cage` позволяет держать потребление ресурсов на уровне **alpine**.
+
+### Нюансы настройки (Troubleshooting)
+
+* **Runtime Directory**: Для работы `wayland` необходимо вручную создавать и прокидывать `XDG_RUNTIME_DIR`, иначе композитор `cage` не сможет создать сокет.
+
+* **WLR_BACKENDS**: При запуске в **lxc** без монитора необходимо явно указывать `WLR_BACKENDS=headless` для корректной инициализации виртуального экрана.
+
+## Установка зависимостей
+
+Включаем песочницу:
+```bash
+sed -i 's/#DisableSandbox/DisableSandbox/' /etc/pacman.conf
+```
+
+Инициализируем ключи для `pacman`:
+```bash
+pacman-key --init
+pacman-key --populate archlinux
+```
+
+Устанавливаем программы:
+```bash
+# обновляем
+pacman -Syu
+# база
+pacman -S obs-studio luajit cage wayvnc
+# зависимости для yay
+pacman -S base-devel linux-headers git nano
+# видеодрайвера (в данном случае для амд)
+pacman -S mesa vulkan-radeon
+```
+
+Далее пробрасываем устройства в контейнер с гипервизора, с **guid**'ами сверяемся в гостевой системе.
+
+Пример:
+```bash
+dev0: /dev/dri/card0,gid=983,mode=0660,uid=0
+dev1: /dev/dri/renderD128,gid=987,mode=0660,uid=0
+dev2: /dev/video%N%,gid=983,mode=0660,uid=0
+dev3: /dev/snd/controlC%N%,gid=995,mode=0660,uid=0
+dev4: /dev/snd/pcmC%N%D0c,gid=995,mode=0660,uid=0
+```
+
+Перезапускаем контейнер и создаём юзера `obs`:
+```bash
+useradd -m -d /var/lib/obs -s /bin/bash obs
+chown -R obs:obs /var/lib/obs
+# wheel для yay
+usermod -aG wheel,video,render,audio obs
+```
+
+Заходив в юзера и ставим `yay`:
+```bash
+# клонируем и ставим yay
+cd /tmp
+git clone https://aur.archlinux.org/yay.git
+cd yay
+makepkg -si
+# устанавливаем novnc из aur
+yay -S novnc
+```
+
+## systemd-units
+
+### /etc/systemd/system/obs.service
+```bash
+[Unit]
+Description=obs
+After=network.target
+
+[Service]
+Type=simple
+User=obs
+Group=obs
+RuntimeDirectory=obs-runtime
+Environment=XDG_RUNTIME_DIR=/run/obs-runtime
+Environment=WAYLAND_DISPLAY=wayland-0
+Environment=WLR_BACKENDS=headless
+Environment=WLR_LIBSEAT_BACKEND=noop
+ExecStart=/usr/bin/cage -s -- /usr/bin/obs
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+```
+### /etc/systemd/system/wayvnc.service
+```bash
+[Unit]
+Description=wayvnc
+After=obs.service
+Requires=obs.service
+
+[Service]
+Type=simple
+User=obs
+Environment=XDG_RUNTIME_DIR=/run/obs-runtime
+Environment=WAYLAND_DISPLAY=wayland-0
+ExecStart=/usr/bin/wayvnc 127.0.0.1 5900
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+```
+### /etc/systemd/system/novnc.service
+```bash
+[Unit]
+Description=novnc
+After=wayvnc.service
+Requires=wayvnc.service
+
+[Service]
+Type=simple
+User=obs
+ExecStart=/usr/bin/novnc --listen 6080 --vnc localhost:5900
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Тестирование
+
+### Схема аппаратного подключения
+
+Для тестирования захвата видео и стабильности плагинов используется цепочка преобразования сигнала из аналогового в цифровой с последующим пробросом в виртуальную среду.
+
+#### Цепочка передачи сигнала
+
+1. **Источник:** **ps2**/**ps3** (+ **hdmi splitter** для расшифровки **hdcp**).
+2. **Аналоговый вывод:** Проприетарный кабель **av multi out** → **component** (**YPbPr**).
+3. **Конвертация:** Преобразователь **YPbPr** + → **HDMI**.
+4. **Захват**: Карта видеозахвата **Fifine V3 RGB**.
+5. **Хост**: Сервер под управлением **proxmox**.
+
+## Скриншоты
+
+![noVNC](assets/novnc.png)  
+*`novnc` — `obs-studio` запущен внутри **lxc** через `wayland` (`cage`)*
+
+![Twitch](assets/twitch.png)  
+*лайв-стрим на твиче*
\ No newline at end of file