From 0dbcc771f5890b5b281beabd81d2353fb7a4acf6 Mon Sep 17 00:00:00 2001
From: Tarasov Aleksandr <55220741+arabianq@users.noreply.github.com>
Date: Sun, 5 Jul 2026 19:33:20 +0300
Subject: [PATCH] docs: new readme (#152)

---
 README.md    | 171 ++++++++++++++++++++++++++++-----------------------
 README.ru.md | 149 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 244 insertions(+), 76 deletions(-)
 create mode 100644 README.ru.md

diff --git a/README.md b/README.md
index 7fb61fc..ad9f681 100644
--- a/README.md
+++ b/README.md
@@ -1,130 +1,149 @@
-<div align="center">
-  <h1>🎵 PipeWire Soundpad (PWSP)</h1>
-  <p><b>A simple, modern, and powerful soundboard for Linux, written in Rust.</b></p>
-  <img src="pwsp-gui/assets/screenshot.png" alt="PWSP Screenshot" width="700"/>
-</div>
+# PipeWire Soundpad (PWSP) 🎵
 
-## 🌟 Overview
-**PipeWire Soundpad (PWSP)** is a graphical soundboard application that routes audio directly to your virtual microphone using **PipeWire**. It provides an intuitive interface for managing your audio collection, making it an ideal tool for gamers, streamers, and anyone looking to inject sound effects into voice chats on platforms like Discord, Zoom, or TeamSpeak.
+![PWSP Screenshot](https://raw.githubusercontent.com/arabianq/pipewire-soundpad/master/assets/screenshot.png)
 
-## ✨ Key Features
-* **🎙️ Virtual Microphone Output:** Seamlessly mixes your microphone input with sound effects by automatically managing PipeWire virtual devices.
-* **🎵 Multi-Format Support:** Plays popular audio formats including `mp3`, `wav`, `ogg`, `flac`, `mp4`, and `aac`.
-* **⚡ Global Hotkeys:** Trigger sounds instantly from anywhere, even when the app is running in the background.
-* **📂 Smart Collection Management:** Drag-and-drop folders, quick search, and collapsible tracks to keep your library organized.
-* **🎛️ Advanced Playback Controls:** Individual volume sliders, play/pause, position scrubbing, and concurrent multi-track playback.
-* **🔌 Plug & Play:** Automatically detects when an input device is connected or disconnected and handles linking/unlinking on the fly.
-* **🖥️ Modern GUI:** Clean, responsive, and lightweight interface powered by [egui](https://egui.rs/).
+[🇷🇺 Читать на русском](README.ru.md) | [🇺🇸 Read in English](README.md)
 
-## ⚙️ Architecture
-PWSP is built with a client-server model to ensure stability and separation of concerns:
-* **`pwsp-daemon`**: The background engine. It runs silently, managing PipeWire virtual devices, audio routing, and playback.
-* **`pwsp-gui`**: The graphical interface. Communicates with the daemon via a Unix socket to control playback and settings.
-* **`pwsp-cli`**: The command-line tool. Perfect for scripting, hotkey binding, or quick terminal-based control.
+[![GitHub Actions Build Status](https://img.shields.io/github/actions/workflow/status/arabianq/pipewire-soundpad/build.yml?branch=main&style=flat-square)](https://github.com/arabianq/pipewire-soundpad/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub Release](https://img.shields.io/github/v/release/arabianq/pipewire-soundpad?style=flat-square)](https://github.com/arabianq/pipewire-soundpad/releases/latest)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20PipeWire-blue?style=flat-square)](https://pipewire.org/)
+
+**PipeWire Soundpad (PWSP)** is a modern, low-latency application that lets you play audio files directly through your microphone. Designed specifically for Linux, it leverages the power of PipeWire to achieve native integration without the need for Pulseaudio bridges or complex virtual sinks.
+
+---
+
+## ✨ Features
+
+- **Native PipeWire Integration:** Direct communication with the PipeWire API for the lowest possible latency.
+- **Modular Architecture:** Consists of a background `daemon`, a command-line interface (`cli`), and a graphical user interface (`gui`).
+- **Modern GUI:** Built with `egui`, supporting both Wayland and X11 seamlessly.
+- **Global Hotkeys:** Powered by `evdev`, allowing you to play sounds from anywhere.
+- **Broad Audio Support:** Powered by `rodio` and `symphonia` to support a wide range of audio formats.
 
 ---
 
 ## 🚀 Installation
 
+We provide multiple ways to install PWSP, including stable releases and rolling "nightly" builds directly from the `main` branch.
+
 ### 📦 Flatpak (Recommended)
-Install PWSP via Flatpak from our custom repository:
+
+Add our official OSTree repository and install the application:
+
 ```bash
-flatpak remote-add --user --if-not-exists pwsp-repo https://arabianq.github.io/pipewire-soundpad/index.flatpakrepo
+# Add the repository
+flatpak remote-add --if-not-exists arabianq-repo https://arabianq.github.io/pipewire-soundpad/
 
-# Install stable version
-flatpak install --user arabianq-repo ru.arabianq.pwsp//stable
+# Install the Stable version
+flatpak install arabianq-repo ru.arabianq.pwsp//stable
 
-# Or install the nightly version (latest commit)
-flatpak install --user arabianq-repo ru.arabianq.pwsp//nightly
+# OR Install the Nightly version (rolling updates)
+flatpak install arabianq-repo ru.arabianq.pwsp//nightly
 ```
 
-### 🐧 Linux Packages
-**Fedora (and derivatives):**
-```bash
-sudo dnf copr enable arabianq/pwsp
-sudo dnf install pwsp
-```
+### 🟠 Debian / Ubuntu (APT Repository)
 
-**Arch Linux (AUR):**
-```bash
-paru -S pwsp-bin # or 'pwsp' to build from source
-```
+We maintain an official APT repository for seamless updates via `apt`:
 
-**Debian / Ubuntu:** 
-We provide an official APT repository for automatic updates:
 ```bash
-# 1. Download the public key
+# 1. Download the public GPG key
 wget -O- https://arabianq.github.io/pipewire-soundpad/apt/pubkey.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/pwsp.gpg
 
-# 2. Add the repository to your sources
+# 2. Add the repository (Choose STABLE or NIGHTLY)
+# For Stable:
 echo "deb [signed-by=/etc/apt/keyrings/pwsp.gpg] https://arabianq.github.io/pipewire-soundpad/apt/ stable main" | sudo tee /etc/apt/sources.list.d/pwsp.list
 
+# For Nightly:
+# echo "deb [signed-by=/etc/apt/keyrings/pwsp.gpg] https://arabianq.github.io/pipewire-soundpad/apt/ nightly main" | sudo tee /etc/apt/sources.list.d/pwsp.list
+
 # 3. Update and install
 sudo apt update
 sudo apt install pwsp-gui
 ```
-*(Alternatively, you can manually download `.deb` packages from the [Releases page](https://github.com/arabianq/pipewire-soundpad/releases)).*
 
-### 🦀 Cargo / Source Build
+### 🐧 Fedora / RHEL (COPR)
+
+Available via the Fedora COPR repository:
+
 ```bash
-cargo install pwsp
+sudo dnf copr enable arabianq/pwsp
+sudo dnf install pwsp
+```
 
-# OR clone and build manually:
+### ⚙️ Manual / Standalone
+
+You can manually download `.deb` packages or standalone `.zip` binaries from the [Releases page](https://github.com/arabianq/pipewire-soundpad/releases).
+
+### 🦀 Build from Source
+
+Make sure you have Rust, Cargo, and the required dependencies (`libpipewire-0.3-dev`, `libclang-dev`, `libasound2-dev`, `libdbus-1-dev`) installed.
+
+```bash
 git clone https://github.com/arabianq/pipewire-soundpad.git
 cd pipewire-soundpad
-cargo build --release
+cargo build --release --locked
 ```
-*(Note: Requires Rust toolchain and PipeWire running on your system).*
+
+The binaries will be located in `target/release/`.
 
 ---
 
 ## 🎮 Usage
 
 ### 1. Start the Daemon
-Before using the GUI or CLI, the daemon must be running in the background.
+
+PWSP operates via a background daemon that handles the audio routing.
 
 ```bash
-# Recommended: Start and enable via systemd (starts on login)
-systemctl --user enable --now pwsp-daemon
-
-# Manual start (if not using systemd):
-pwsp-daemon &
+# Run the daemon
+pwsp-daemon
 ```
 
-### 2. Using the GUI
-1. **Add Sounds:** Click the **"+"** button to add a directory containing your audio files.
-2. **Select Mic:** Choose your physical microphone from the dropdown. PWSP will instantly create a virtual microphone combining your voice and the soundboard.
-3. **Play:** Click any sound to play it, adjust its volume, or assign a hotkey for quick access.
+_(Tip: If installed via package managers, a systemd user service is provided. You can enable it with `systemctl --user enable --now pwsp-daemon.service`)_
+
+### 2. Launch the GUI
+
+Simply run the graphical interface to manage and play your sounds:
 
-### 3. Using the CLI
-Control the daemon directly from your terminal:
 ```bash
-pwsp-cli action play /path/to/sound.mp3
-pwsp-cli get volume
-pwsp-cli set position 20
-pwsp-cli --help # View all commands
+pwsp-gui
+```
+
+### 3. Use the CLI
+
+You can also interact with the daemon directly via the command line:
+
+```bash
+pwsp-cli play /path/to/sound.mp3
+pwsp-cli stop
+pwsp-cli status
 ```
 
 ---
 
-## ⌨️ Shortcuts & Controls
+## 📚 Documentation & DeepWiki
 
-| Action                               | Keyboard               | Mouse                |
-| :----------------------------------- | :--------------------- | :------------------- |
-| **Play Track** (Stops others)        |                        | `Left Click`         |
-| **Add Track** (Plays simultaneously) |                        | `Ctrl + Left Click`  |
-| **Replace Last Track**               |                        | `Shift + Left Click` |
-| **Pause / Resume**                   | `Space`                |                      |
-| **Stop All Tracks**                  | `Backspace`            |                      |
-| **Open / Close Settings**            | `I`                    |                      |
-| **Search**                           | `/`                    |                      |
+For advanced configuration, troubleshooting, architecture details, and custom setups, please visit our official Wiki:
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arabianq/pipewire-soundpad)
 
 ---
 
 ## 🤝 Contributing
-Contributions, issues, and feature requests are welcome! Feel free to check out the [issues page](https://github.com/arabianq/pipewire-soundpad/issues).
 
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arabianq/pipewire-soundpad)
+Contributions, issues, and feature requests are welcome!
 
-## 📜 License
-This project is licensed under the [MIT License](LICENSE).
\ No newline at end of file
+1. Fork the project.
+2. Create your feature branch (`git checkout -b feat/amazing-feature`).
+3. Commit your changes (`git commit -m 'Add some amazing feature'`).
+4. Push to the branch (`git push origin feat/amazing-feature`).
+5. Open a Pull Request.
+
+---
+
+## 📝 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+_Built with ❤️ for the Linux community._
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 0000000..c44111a
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,149 @@
+# PipeWire Soundpad (PWSP) 🎵
+
+![PWSP Screenshot](https://raw.githubusercontent.com/arabianq/pipewire-soundpad/master/assets/screenshot.png)
+
+[🇷🇺 Читать на русском](README.ru.md) | [🇺🇸 Read in English](README.md)
+
+[![GitHub Actions Build Status](https://img.shields.io/github/actions/workflow/status/arabianq/pipewire-soundpad/build.yml?branch=main&style=flat-square)](https://github.com/arabianq/pipewire-soundpad/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub Release](https://img.shields.io/github/v/release/arabianq/pipewire-soundpad?style=flat-square)](https://github.com/arabianq/pipewire-soundpad/releases/latest)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20PipeWire-blue?style=flat-square)](https://pipewire.org/)
+
+**PipeWire Soundpad (PWSP)** — это современное приложение с низкой задержкой, которое позволяет воспроизводить аудиофайлы прямо в ваш микрофон. Разработано специально для Linux с использованием мощи PipeWire для достижения нативной интеграции без использования мостов Pulseaudio или сложных виртуальных устройств.
+
+---
+
+## ✨ Возможности
+
+- **Нативная интеграция с PipeWire:** Прямое взаимодействие с PipeWire API для минимальной задержки.
+- **Модульная архитектура:** Состоит из фонового демона (`daemon`), интерфейса командной строки (`cli`) и графического интерфейса (`gui`).
+- **Современный GUI:** Построен на `egui`, плавно работает как на Wayland, так и на X11.
+- **Глобальные горячие клавиши:** Работают через `evdev`, позволяя воспроизводить звуки из любого окна.
+- **Широкая поддержка форматов:** Использует `rodio` и `symphonia` для поддержки большинства аудиоформатов.
+
+---
+
+## 🚀 Установка
+
+Мы предоставляем несколько способов установки PWSP, включая стабильные релизы и постоянно обновляемые "nightly" сборки напрямую из ветки `main`.
+
+### 📦 Flatpak (Рекомендуется)
+
+Добавьте наш официальный OSTree репозиторий и установите приложение:
+
+```bash
+# Добавьте репозиторий
+flatpak remote-add --if-not-exists arabianq-repo https://arabianq.github.io/pipewire-soundpad/
+
+# Установите стабильную (Stable) версию
+flatpak install arabianq-repo ru.arabianq.pwsp//stable
+
+# ИЛИ установите Nightly версию (самые свежие обновления)
+flatpak install arabianq-repo ru.arabianq.pwsp//nightly
+```
+
+### 🟠 Debian / Ubuntu (APT Репозиторий)
+
+Мы поддерживаем официальный APT-репозиторий для бесшовных обновлений через `apt`:
+
+```bash
+# 1. Скачайте публичный GPG ключ
+wget -O- https://arabianq.github.io/pipewire-soundpad/apt/pubkey.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/pwsp.gpg
+
+# 2. Добавьте репозиторий (Выберите STABLE или NIGHTLY)
+# Для Stable:
+echo "deb [signed-by=/etc/apt/keyrings/pwsp.gpg] https://arabianq.github.io/pipewire-soundpad/apt/ stable main" | sudo tee /etc/apt/sources.list.d/pwsp.list
+
+# Для Nightly:
+# echo "deb [signed-by=/etc/apt/keyrings/pwsp.gpg] https://arabianq.github.io/pipewire-soundpad/apt/ nightly main" | sudo tee /etc/apt/sources.list.d/pwsp.list
+
+# 3. Обновите индексы и установите
+sudo apt update
+sudo apt install pwsp-gui
+```
+
+### 🐧 Fedora / RHEL (COPR)
+
+Доступно через репозиторий Fedora COPR:
+
+```bash
+sudo dnf copr enable arabianq/pwsp
+sudo dnf install pwsp
+```
+
+### ⚙️ Ручная установка
+
+Вы можете вручную скачать пакеты `.deb` или готовые бинарники `.zip` на [странице релизов](https://github.com/arabianq/pipewire-soundpad/releases).
+
+### 🦀 Сборка из исходников
+
+Убедитесь, что у вас установлены Rust, Cargo и необходимые зависимости (`libpipewire-0.3-dev`, `libclang-dev`, `libasound2-dev`, `libdbus-1-dev`).
+
+```bash
+git clone https://github.com/arabianq/pipewire-soundpad.git
+cd pipewire-soundpad
+cargo build --release --locked
+```
+
+Собранные бинарники будут находиться в папке `target/release/`.
+
+---
+
+## 🎮 Использование
+
+### 1. Запуск демона
+
+PWSP работает через фоновый демон, который маршрутизирует аудио.
+
+```bash
+# Запуск демона
+pwsp-daemon
+```
+
+_(Подсказка: Если вы установили программу через пакетный менеджер, она включает пользовательский systemd-сервис. Вы можете включить его командой: `systemctl --user enable --now pwsp-daemon.service`)_
+
+### 2. Запуск GUI
+
+Просто запустите графический интерфейс для управления и воспроизведения звуков:
+
+```bash
+pwsp-gui
+```
+
+### 3. Использование CLI
+
+Вы также можете взаимодействовать с демоном напрямую через командную строку:
+
+```bash
+pwsp-cli play /path/to/sound.mp3
+pwsp-cli stop
+pwsp-cli status
+```
+
+---
+
+## 📚 Документация и DeepWiki
+
+Для детальной настройки, решения проблем, описания архитектуры и кастомных конфигураций, пожалуйста, посетите нашу официальную Wiki:
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arabianq/pipewire-soundpad)
+
+---
+
+## 🤝 Вклад в проект (Contributing)
+
+Будем рады вашей помощи, баг-репортам и идеям!
+
+1. Сделайте Fork проекта.
+2. Создайте свою ветку (`git checkout -b feat/amazing-feature`).
+3. Закоммитьте изменения (`git commit -m 'Add some amazing feature'`).
+4. Запушьте ветку (`git push origin feat/amazing-feature`).
+5. Откройте Pull Request.
+
+---
+
+## 📝 Лицензия
+
+Распространяется под лицензией MIT. Подробнее см. в файле `LICENSE`.
+
+_Сделано с ❤️ для сообщества Linux._