From 5c68a52abd6893d44b935cfd9923b08fd1b41a45 Mon Sep 17 00:00:00 2001
From: zarazaex69 <zarazaex@tuta.io>
Date: Wed, 6 May 2026 19:06:11 +0300
Subject: [PATCH] doc: add doc for client  URI format

---
 docs/uri.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 readme.md   |   2 +-
 2 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 docs/uri.md

diff --git a/docs/uri.md b/docs/uri.md
new file mode 100644
index 0000000..5550454
--- /dev/null
+++ b/docs/uri.md
@@ -0,0 +1,102 @@
+# Краткий URI-формат для клиентов
+
+Этот документ описывает **соглашение для разработчиков клиентских приложений**, которым нужен компактный способ передавать параметры подключения `olcrtc`.
+
+Текущий `olcrtc` не парсит такой URI автоматически. Если клиентское приложение хочет использовать эту запись, оно должно само разобрать строку и передать полученные поля в свои вызовы `olcrtc`.
+
+---
+
+## Формат
+
+```text
+olcrtc://<Carrier>?<Transport>@<RoomID>#<EncryptionKey>%<ClientID>$<MIMO>
+```
+
+Все поля после `olcrtc://` считаются частью клиентского соглашения.
+
+---
+
+## Поля
+
+| Поле | Значение |
+|------|----------|
+| `<Carrier>` | Имя carrier/provider, например `telemost`, `jazz`, `wbstream` |
+| `<Transport>` | Имя транспорта, например `datachannel`, `vp8channel`, `seichannel`, `videochannel` |
+| `<RoomID>` | Идентификатор комнаты или carrier-specific room URL/ID |
+| `<EncryptionKey>` | Ключ шифрования в hex, обычно 64 символа (`32` байта) |
+| `<ClientID>` | Идентификатор клиента. Должен совпадать с ожидаемым значением на сервере |
+| `<MIMO>` | Свободный комментарий для UI/метаданных, например `RU / olc free sub / IPv6` |
+
+---
+
+## Соответствие параметрам olcrtc
+
+URI-поля сопоставляются с обычными параметрами так:
+
+| URI поле | Параметр / значение |
+|----------|---------------------|
+| `<Carrier>` | `-carrier` |
+| `<Transport>` | `-transport` |
+| `<RoomID>` | `-id` |
+| `<EncryptionKey>` | `-key` |
+| `<ClientID>` | `-client-id` |
+| `<MIMO>` | В `olcrtc` не передаётся. Это только клиентский комментарий |
+
+`-link direct` и `-data data` в этом формате не кодируются, потому что для текущих сценариев они фиксированные.
+
+---
+
+## Разделители
+
+Строка использует фиксированные разделители:
+
+| Разделитель | После него идёт |
+|-------------|-----------------|
+| `://` | начало полезной нагрузки после схемы `olcrtc` |
+| `?` | `<Transport>` |
+| `@` | `<RoomID>` |
+| `#` | `<EncryptionKey>` |
+| `%` | `<ClientID>` |
+| `$` | `<MIMO>` |
+
+Рекомендуется не использовать эти символы внутри самих полей. Если клиенту это нужно, он должен ввести собственное escaping/percent-encoding правило и применять его симметрично при кодировании и декодировании.
+
+---
+
+## Примеры
+
+### Полный пример
+
+```text
+olcrtc://wbstream?seichannel@room-01#d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799%android-01$RU / olc free sub / IPv6
+```
+
+Разбор:
+
+| Поле | Значение |
+|------|----------|
+| `Carrier` | `wbstream` |
+| `Transport` | `seichannel` |
+| `RoomID` | `room-01` |
+| `EncryptionKey` | `d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799` |
+| `ClientID` | `android-01` |
+| `MIMO` | `RU / olc free sub / IPv6` |
+
+### Эквивалент CLI
+
+```sh
+./olcrtc -mode cnc \
+  -carrier wbstream \
+  -transport seichannel \
+  -id room-01 \
+  -client-id android-01 \
+  -key d823fa01cb3e0609b67322f7cf984c4ee2e4ce2e294936fc24ef38c9e59f4799 \
+  -link direct \
+  -data data
+```
+
+---
+
+## Короткие алиасы
+
+Как хотите но лично я был бы против.
diff --git a/readme.md b/readme.md
index 6423e5f..7355ddb 100644
--- a/readme.md
+++ b/readme.md
@@ -31,7 +31,7 @@ Or wait for the release or at least a release
 
 [Setting matrix](docs/settings.md)
 
-Во всех актуальных примерах запуска нужен `-client-id <id>`: значение должно совпадать на сервере и клиенте.
+[Client URI format](docs/uri.md)