artnet2usb-cli 0.2.0

package/README.ja.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+<img src="src/public/logo.svg" alt="Relackout ArtNet 2 USB" width="96" height="96">
+
+# Relackout ArtNet 2 USB
+
+**無料でシンプルな Art-Net → USB DMX ブリッジ。デスクトップ GUI とヘッドレス CLI を備えています。**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational)](#download)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+[ダウンロード](https://relackout.com/usb-dmx) · [CLI の使い方](#cli-usage) · [ソースからのビルド](#building-from-source) · [アーキテクチャ](#architecture)
+
+[English](README.md) · [Türkçe](README.tr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt-BR.md) · [Русский](README.ru.md) · [简体中文](README.zh-Hans.md) · **日本語**
+
+</div>
+
+---
+
+## これは何ですか？
+
+多くの照明制御ソフトウェアはネットワーク経由で **Art-Net** を使用しますが、Enttec の DMX USB Pro（および互換機）や汎用の Open DMX / FTDI ドングルなど、多くの USB DMX インターフェースは、そのネットワーク信号を受信して USB 経由で出力するための何かを、依然として手元に必要としています。
+
+**Relackout ArtNet 2 USB** はまさにそのためのツールです。バックグラウンドで動かし続ける、小さく用途を絞ったブリッジです。無料で、アカウント登録も不要。[Relackout](https://relackout.com) 以外のコンソールやソフトウェアも含め、Art-Net エコシステム全体を扱いやすくすることを目的として作られています。
+
+提供形態は2つあります。
+- **デスクトップ GUI** — 自動検出、512 チャンネルのライブプレビュー、視覚的なルーティングテーブルを備えています。
+- **ヘッドレス CLI**（`artnet2usb-cli`） — GUI とまったく同じルーティングエンジンを、UI なしで提供します。トラスの裏に隠れた Raspberry Pi、モニターのないバックステージサーバー、あるいは本番前に照明システム全体をスクリプトで組み上げる用途を想定しています。GUI と CLI はどちらも**同じ設定ファイル**を読み書きするため、GUI でルートを作成してヘッドレスで実行することも、その逆も可能です。
+
+## 機能
+
+- **自動検出** — UDP 6454 をパッシブに監視し、ネットワーク上でブロードキャストされているすべての Art-Net ユニバースを、送信元 IP とリアルタイムのフレームレート表示とともにリストアップします。`ArtPoll`/`ArtPollReply` によるノードスキャンにより、まだ DMX をブロードキャストしていないデバイスも検出できます。
+- **ライブチャンネルプレビュー** — ルーティングを設定する前に、検出したユニバースの 512 チャンネルすべてがリアルタイムに更新される様子を確認できます。
+- **視覚的なルーティングテーブル** — 各行が1つのルールです：Art-Net ユニバース → USB デバイス + プロトコル + リフレッシュレート（1〜44 Hz）。
+- **2つのプロトコル** — Enttec DMX USB Pro（およびファームウェア互換のクローン）と、生の Open DMX / FTDI 出力に対応しています。
+- **永続的なデバイス識別** — USB インターフェースは OS 上のポートパスではなく、ハードウェア識別情報（ベンダー ID、プロダクト ID、シリアル番号）で記憶されます。一度デバイスに名前を付ければ、抜き差しして別のポートに接続しても、その名前とルートはそのまま保持されます。
+- **チャンネルパッチオフセット** — 機材固有の DMX 開始アドレスや、コンソール側と異なるチャンネル番号付けを、ルートごとに補正できます（`-511..511`）。ユニバースは 512 チャンネル内で**循環的に**シフトされるため、チャンネルデータが失われることはなく、端まで来ると折り返します。
+- **信号ロス時の挙動** — Art-Net の送信元が失われた際に、出力が最後のフレームを保持し続けるか、ブラックアウトするかを選択できます。
+- **ポータブル設定** — インストール不要で USB スティックから起動できます。詳しくは下記の[ポータブル設定](#portable-config)を参照してください。
+- **GUI は5言語対応** — English、Deutsch、Français、Italiano、Türkçe。
+
+## ダウンロード
+
+Windows、macOS、Linux（CLI については Raspberry Pi を含む）向けの、ビルド済みでインストーラー不要な単一ファイルのバイナリを、**[relackout.com/usb-dmx](https://relackout.com/usb-dmx)** および [GitHub Releases](../../releases) ページで配布しています。
+
+| | ファイル | 備考 |
+|---|---|---|
+| GUI · Windows | `Relackout-ArtNet2USB-<ver>-portable.exe` | ポータブル — インストーラー不要、実行するだけです。 |
+| GUI · macOS | `Relackout-ArtNet2USB-<ver>-<arch>.dmg` | ドラッグ＆ドロップ、インストーラー不要。 |
+| GUI · Linux | `Relackout-ArtNet2USB-<ver>-<arch>.AppImage` | `chmod +x` を実行してから起動してください。 |
+| CLI · 全プラットフォーム | `artnet2usb-cli-<ver>-<platform>[.exe]` | Node.js 不要の、正真正銘のスタンドアロンバイナリです。macOS（arm64/x64）、Linux（x64/arm64/armv7l — Raspberry Pi を含む）、Windows（x64）に対応しています。 |
+
+> **署名されていないビルド。** リリースはコード署名されていません。初回起動時、macOS では*右クリック → 開く*、Windows の SmartScreen では*詳細情報 → 実行*が必要です。
+
+## CLI の使い方
+
+```bash
+npx artnet2usb-cli                 # no args → interactive terminal wizard
+artnet2usb-cli --help              # full command reference
+```
+
+| コマンド | 動作 |
+|---|---|
+| `configure` | ルートの追加・削除を行うインタラクティブウィザード。必要に応じてブリッジを起動することもできます。 |
+| `auto` | 単一の Art-Net ユニバースと USB デバイスを自動検出し、ルートを保存して起動します（起動をスキップするには `--no-start`）。 |
+| `run` | 保存済みのルートを使ってブリッジを起動し、停止（`Ctrl+C`）するまで実行し続けます。 |
+| `route add` / `route list` / `route remove <id>` | 対話なしでルートを管理します — シェルスクリプトや Ansible Playbook からスクリプト実行可能です。 |
+| `list-ports` | 接続中の USB シリアルデバイスを一覧表示します。 |
+| `list-nodes` | ネットワーク上の Art-Net ノードを（約3秒間）待ち受けて一覧表示します。 |
+| `doctor` | 保存済み設定内の、切断されたデバイス、競合するルート、範囲外の設定値を検出して警告します。 |
+| `install-service` / `uninstall-service` | systemd ユニット（Linux）または launchd エージェント（macOS）を生成して表示します（黙って適用されることはありません）。これにより、再起動やクラッシュの後にブリッジが自動的に再起動するようになります。 |
+
+Art-Net ユニバースと USB DMX インターフェースがそれぞれ1つだけのマシンでは、1コマンドでヘッドレスセットアップが完了します。
+
+```bash
+artnet2usb-cli auto --protocol enttec-pro --hz 40
+```
+
+すべてのコマンドは、特定の設定ディレクトリを指定するための `--config <dir>` を受け付けます。また `run`/`auto` は、人間が読めるテキストの代わりに改行区切りの JSON ステータスを出力する `--json` を受け付けます（別のスクリプトからプロセスを監視する際に便利です）。
+
+## ポータブル設定
+
+アプリはまず実行ファイルと同じ場所にある `config.json` を探すため、USB スティックに入れてマシン間を持ち運ぶことができます。そのディレクトリに書き込めない場合（例えば、署名されていない macOS アプリに対する Gatekeeper の「app translocation」など）は、OS 標準のユーザーごとの設定ディレクトリにフォールバックします。同じフォルダーから実行すれば、GUI と CLI はまったく同じ `config.json` を共有します — GUI で視覚的にルートを組み立ててからヘッドレスで実行することも、その逆も可能です。
+
+## ソースからのビルド
+
+```bash
+npm install
+npm run dev             # GUI, electron-vite dev server
+npm test                # unit tests (parser, framing, device uid, config)
+npm run typecheck       # tsc --noEmit
+npm run dist             # package the GUI for the host platform (electron-builder)
+npm run dev:cli          # run the CLI from source (tsx)
+npm run build:cli        # compile the CLI to dist-cli/
+```
+
+### スタンドアロンの単一ファイルビルド
+
+スタンドアロン出力はすべて `dist-standalone/` に生成されます。各成果物はインストール不要の単一ファイルです。
+
+```bash
+npm run dist:standalone                                   # host platform: GUI + CLI
+node scripts/build-standalone.mjs --cli --all-targets     # CLI: every platform in one pass
+node scripts/build-standalone.mjs --gui --mac --win       # GUI: selected platforms only
+```
+
+CLI は `esbuild` でバンドルされ、[`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) によって実行可能な本物のバイナリにパッケージ化されます（実行に Node.js は不要です）。GUI は `electron-builder` でパッケージ化されます。
+
+## アーキテクチャ
+
+```
+app/                      Electron main process
+  artnet.ts                Art-Net listener/parser — no external protocol library, hand-rolled to spec
+  dmxOutput.ts              output engine + protocol drivers (Enttec Pro, Open DMX), via `serialport`
+  store.ts                  device names / routes / settings, portable-config-first
+  main.ts, preload.ts       Electron app lifecycle + the IPC bridge exposed to the renderer
+
+cli/                       Headless CLI (compiles separately, see tsconfig.cli.json)
+  index.ts                  command definitions (commander) + the interactive wizard (@clack/prompts)
+  bridge.ts, autoRoute.ts    shared bridge start-up and single-universe/device auto-pick logic
+  routeCommands.ts           `route add/list/remove` — scriptable route management
+  serviceInstall.ts          systemd/launchd unit generation
+  doctor.ts, configDir.ts    config health checks + config-directory resolution
+
+shared/                    Code shared between the GUI and the CLI
+  types.ts                  RouteConfig, UsbDevice, and the rest of the shared type surface
+  store.ts, portableConfig.ts   the config file itself + the portable-vs-per-user directory rule
+
+scripts/build-standalone.mjs   the single-file distribution pipeline (esbuild + @yao-pkg/pkg + electron-builder)
+scripts/embed-win-resources.mjs   embeds an icon + version metadata into the Windows CLI .exe (via resedit)
+src/                       React + Tailwind renderer (GUI), including src/locales/ for the 5 supported languages
+```
+
+## コントリビューション
+
+Issue や Pull Request を歓迎します。PR を開く前に、`npm test` と `npm run typecheck` の両方が通ることを確認してください。
+
+## ライセンス
+
+[MIT](LICENSE) © Remana
+
+---
+
+<div align="center">
+
+[Relackout](https://relackout.com) 照明制御エコシステムの一部です。
+
+</div>

package/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+<img src="src/public/logo.svg" alt="Relackout ArtNet 2 USB" width="96" height="96">
+
+# Relackout ArtNet 2 USB
+
+**A free, focused Art-Net → USB DMX bridge, with a desktop GUI and a headless CLI.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational)](#download)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+[Download](https://relackout.com/usb-dmx) · [CLI usage](#cli-usage) · [Building from source](#building-from-source) · [Architecture](#architecture)
+
+**English** · [Türkçe](README.tr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt-BR.md) · [Русский](README.ru.md) · [简体中文](README.zh-Hans.md) · [日本語](README.ja.md)
+
+</div>
+
+---
+
+## What is this?
+
+Most lighting software speaks **Art-Net** over the network, but a lot of USB DMX interfaces — Enttec's DMX USB Pro (and compatibles), generic Open DMX / FTDI dongles — still need something on the desk to receive that network signal and push it out over USB.
+
+**Relackout ArtNet 2 USB** is exactly that: a small, focused bridge you keep running in the background. It costs nothing, requires no account, and is built to make the whole Art-Net ecosystem easier to work with — including consoles and software that aren't [Relackout](https://relackout.com).
+
+It ships two ways:
+- **A desktop GUI** — auto-discovery, a live 512-channel preview, and a visual routing table.
+- **A headless CLI** (`artnet2usb-cli`) — the exact same routing engine, zero UI, built for a Raspberry Pi behind a truss, a backstage server with no monitor, or scripting an entire rig ahead of a show. Both read and write the **same config file**, so you can build routes in the GUI and run them headless, or the other way around.
+
+## Features
+
+- **Auto-discovery** — passively listens on UDP 6454 and lists every Art-Net universe broadcasting on the network, with source IP and a live frame-rate readout; `ArtPoll`/`ArtPollReply` node scanning finds devices that don't broadcast DMX yet.
+- **Live channel preview** — watch all 512 channels of any discovered universe update in real time, before you route anything.
+- **Visual routing table** — each row is one rule: Art-Net universe → USB device + protocol + refresh rate (1–44 Hz).
+- **Two protocols** — Enttec DMX USB Pro (and firmware-compatible clones) and raw Open DMX / FTDI output.
+- **Persistent device identity** — USB interfaces are remembered by their hardware identity (vendor ID, product ID, serial number), not their OS port path. Rename a device once, and the name and its routes survive being unplugged and moved to a different port.
+- **Channel patch offset** — compensate for a fixture's own DMX start address or a console's differing channel numbering, per route (`-511..511`). The universe is shifted **circularly** within its 512 channels — no channel data is ever dropped, it wraps around instead.
+- **Signal-loss behavior** — choose whether output holds the last frame or blacks out when the Art-Net source disappears.
+- **Portable config** — runs from a USB stick with zero installation; see [Portable config](#portable-config) below.
+- **5 languages in the GUI** — English, Deutsch, Français, Italiano, Türkçe.
+
+## Download
+
+Prebuilt, single-file, no-installer binaries for Windows, macOS, and Linux (including Raspberry Pi for the CLI) are available at **[relackout.com/usb-dmx](https://relackout.com/usb-dmx)** and on the [GitHub Releases](../../releases) page.
+
+| | File | Notes |
+|---|---|---|
+| GUI · Windows | `Relackout-ArtNet2USB-<ver>-portable.exe` | Portable — no installer, just run it. |
+| GUI · macOS | `Relackout-ArtNet2USB-<ver>-<arch>.dmg` | Drag & drop, no installer. |
+| GUI · Linux | `Relackout-ArtNet2USB-<ver>-<arch>.AppImage` | `chmod +x` and run. |
+| CLI · all platforms | `artnet2usb-cli-<ver>-<platform>[.exe]` | A real standalone binary — no Node.js required. Covers macOS (arm64/x64), Linux (x64/arm64/armv7l — including Raspberry Pi), and Windows (x64). |
+
+> **Unsigned builds.** Releases aren't code-signed. On first launch, macOS requires *right-click → Open*, and Windows SmartScreen requires *More info → Run anyway*.
+
+## CLI usage
+
+```bash
+npx artnet2usb-cli                 # no args → interactive terminal wizard
+artnet2usb-cli --help              # full command reference
+```
+
+| Command | What it does |
+|---|---|
+| `configure` | Interactive wizard to add/remove routes and optionally start the bridge. |
+| `auto` | Auto-detect a single Art-Net universe and USB device, save the route, and start it (`--no-start` to skip starting). |
+| `run` | Start the bridge using saved routes and run until stopped (`Ctrl+C`). |
+| `route add` / `route list` / `route remove <id>` | Manage routes non-interactively — scriptable from a shell script or an Ansible playbook. |
+| `list-ports` | List connected USB serial devices. |
+| `list-nodes` | Listen for Art-Net nodes on the network (~3s) and list them. |
+| `doctor` | Flag disconnected devices, conflicting routes, and out-of-range settings in the saved config. |
+| `install-service` / `uninstall-service` | Generate (and print, never silently apply) a systemd unit (Linux) or a launchd agent (macOS) so the bridge restarts automatically after a reboot or a crash. |
+
+One-command headless setup on a machine with exactly one Art-Net universe and one USB DMX interface:
+
+```bash
+artnet2usb-cli auto --protocol enttec-pro --hz 40
+```
+
+Every command accepts `--config <dir>` to point at a specific config directory, and `run`/`auto` accept `--json` to emit newline-delimited JSON status instead of human-readable text (handy for supervising the process from another script).
+
+## Portable config
+
+The app looks for `config.json` next to the executable first, so it can travel on a USB stick between machines. If that directory isn't writable (e.g. Gatekeeper's "app translocation" for an unsigned macOS app), it falls back to the OS-standard per-user config directory. The GUI and the CLI share the exact same `config.json` when run from the same folder — build routes visually, then run them headless, or vice versa.
+
+## Building from source
+
+```bash
+npm install
+npm run dev             # GUI, electron-vite dev server
+npm test                # unit tests (parser, framing, device uid, config)
+npm run typecheck       # tsc --noEmit
+npm run dist             # package the GUI for the host platform (electron-builder)
+npm run dev:cli          # run the CLI from source (tsx)
+npm run build:cli        # compile the CLI to dist-cli/
+```
+
+### Standalone, single-file builds
+
+All standalone output lands in `dist-standalone/`; every artifact is a single file with nothing to install:
+
+```bash
+npm run dist:standalone                                   # host platform: GUI + CLI
+node scripts/build-standalone.mjs --cli --all-targets     # CLI: every platform in one pass
+node scripts/build-standalone.mjs --gui --mac --win       # GUI: selected platforms only
+```
+
+The CLI is bundled with `esbuild` and packaged into real binaries with [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) (no Node.js needed to run them); the GUI is packaged with `electron-builder`.
+
+## Architecture
+
+```
+app/                      Electron main process
+  artnet.ts                Art-Net listener/parser — no external protocol library, hand-rolled to spec
+  dmxOutput.ts              output engine + protocol drivers (Enttec Pro, Open DMX), via `serialport`
+  store.ts                  device names / routes / settings, portable-config-first
+  main.ts, preload.ts       Electron app lifecycle + the IPC bridge exposed to the renderer
+
+cli/                       Headless CLI (compiles separately, see tsconfig.cli.json)
+  index.ts                  command definitions (commander) + the interactive wizard (@clack/prompts)
+  bridge.ts, autoRoute.ts    shared bridge start-up and single-universe/device auto-pick logic
+  routeCommands.ts           `route add/list/remove` — scriptable route management
+  serviceInstall.ts          systemd/launchd unit generation
+  doctor.ts, configDir.ts    config health checks + config-directory resolution
+
+shared/                    Code shared between the GUI and the CLI
+  types.ts                  RouteConfig, UsbDevice, and the rest of the shared type surface
+  store.ts, portableConfig.ts   the config file itself + the portable-vs-per-user directory rule
+
+scripts/build-standalone.mjs   the single-file distribution pipeline (esbuild + @yao-pkg/pkg + electron-builder)
+scripts/embed-win-resources.mjs   embeds an icon + version metadata into the Windows CLI .exe (via resedit)
+src/                       React + Tailwind renderer (GUI), including src/locales/ for the 5 supported languages
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR, please make sure `npm test` and `npm run typecheck` both pass.
+
+## License
+
+[MIT](LICENSE) © Remana
+
+---
+
+<div align="center">
+
+Part of the [Relackout](https://relackout.com) lighting-control ecosystem.
+
+</div>

package/README.pt-BR.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+<img src="src/public/logo.svg" alt="Relackout ArtNet 2 USB" width="96" height="96">
+
+# Relackout ArtNet 2 USB
+
+**Uma ponte Art-Net → USB DMX gratuita e focada, com uma GUI para desktop e uma CLI headless.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational)](#download)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+[Download](https://relackout.com/usb-dmx) · [Uso da CLI](#cli-usage) · [Compilando a partir do código-fonte](#building-from-source) · [Arquitetura](#architecture)
+
+[English](README.md) · [Türkçe](README.tr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · **Português** · [Русский](README.ru.md) · [简体中文](README.zh-Hans.md) · [日本語](README.ja.md)
+
+</div>
+
+---
+
+## O que é isto?
+
+A maioria dos softwares de iluminação fala **Art-Net** pela rede, mas muitas interfaces USB DMX — a DMX USB Pro da Enttec (e compatíveis), dongles genéricos Open DMX / FTDI — ainda precisam de algo na mesa para receber esse sinal de rede e enviá-lo via USB.
+
+**Relackout ArtNet 2 USB** é exatamente isso: uma ponte pequena e focada que fica rodando em segundo plano. Não custa nada, não exige conta e foi criada para tornar todo o ecossistema Art-Net mais fácil de usar — inclusive com mesas e softwares que não são [Relackout](https://relackout.com).
+
+O produto é distribuído de duas formas:
+- **Uma GUI para desktop** — descoberta automática, pré-visualização ao vivo de 512 canais e uma tabela de roteamento visual.
+- **Uma CLI headless** (`artnet2usb-cli`) — exatamente o mesmo motor de roteamento, sem interface, feita para um Raspberry Pi atrás de uma treliça, um servidor de bastidores sem monitor, ou para automatizar toda a configuração de um rig antes de um show. Ambas leem e escrevem o **mesmo arquivo de configuração**, então você pode montar rotas na GUI e executá-las em modo headless, ou o contrário.
+
+## Funcionalidades
+
+- **Descoberta automática** — escuta passivamente na porta UDP 6454 e lista todo universo Art-Net que estiver transmitindo na rede, com IP de origem e uma leitura de taxa de quadros em tempo real; a varredura de nós via `ArtPoll`/`ArtPollReply` encontra dispositivos que ainda não transmitem DMX.
+- **Pré-visualização de canais ao vivo** — acompanhe a atualização em tempo real de todos os 512 canais de qualquer universo descoberto, antes de rotear qualquer coisa.
+- **Tabela de roteamento visual** — cada linha é uma regra: universo Art-Net → dispositivo USB + protocolo + taxa de atualização (1–44 Hz).
+- **Dois protocolos** — Enttec DMX USB Pro (e clones compatíveis a nível de firmware) e saída bruta Open DMX / FTDI.
+- **Identidade persistente do dispositivo** — as interfaces USB são reconhecidas pela sua identidade de hardware (vendor ID, product ID, número de série), não pelo caminho da porta do sistema operacional. Renomeie um dispositivo uma vez, e o nome e suas rotas sobrevivem a ser desconectado e movido para outra porta.
+- **Offset de patch de canal** — compense o endereço DMX inicial de um fixture ou uma numeração de canais diferente em uma mesa, por rota (`-511..511`). O universo é deslocado **circularmente** dentro de seus 512 canais — nenhum dado de canal é perdido, ele simplesmente dá a volta.
+- **Comportamento em caso de perda de sinal** — escolha se a saída mantém o último quadro ou apaga (blackout) quando a fonte Art-Net desaparece.
+- **Configuração portátil** — roda a partir de um pendrive USB sem qualquer instalação; veja [Configuração portátil](#portable-config) abaixo.
+- **5 idiomas na GUI** — English, Deutsch, Français, Italiano, Türkçe.
+
+## Download
+
+Binários pré-compilados, de arquivo único e sem instalador para Windows, macOS e Linux (incluindo Raspberry Pi para a CLI) estão disponíveis em **[relackout.com/usb-dmx](https://relackout.com/usb-dmx)** e na página de [GitHub Releases](../../releases).
+
+| | Arquivo | Notas |
+|---|---|---|
+| GUI · Windows | `Relackout-ArtNet2USB-<ver>-portable.exe` | Portátil — sem instalador, apenas execute. |
+| GUI · macOS | `Relackout-ArtNet2USB-<ver>-<arch>.dmg` | Arraste e solte, sem instalador. |
+| GUI · Linux | `Relackout-ArtNet2USB-<ver>-<arch>.AppImage` | `chmod +x` e execute. |
+| CLI · todas as plataformas | `artnet2usb-cli-<ver>-<platform>[.exe]` | Um binário standalone de verdade — não requer Node.js. Cobre macOS (arm64/x64), Linux (x64/arm64/armv7l — incluindo Raspberry Pi) e Windows (x64). |
+
+> **Builds não assinados.** As releases não são assinadas digitalmente (code-signed). Na primeira execução, o macOS exige *clique com o botão direito → Abrir*, e o SmartScreen do Windows exige *Mais informações → Executar assim mesmo*.
+
+## Uso da CLI
+
+```bash
+npx artnet2usb-cli                 # sem argumentos → assistente interativo de terminal
+artnet2usb-cli --help              # referência completa de comandos
+```
+
+| Comando | O que faz |
+|---|---|
+| `configure` | Assistente interativo para adicionar/remover rotas e, opcionalmente, iniciar a ponte. |
+| `auto` | Detecta automaticamente um único universo Art-Net e dispositivo USB, salva a rota e a inicia (`--no-start` para pular a inicialização). |
+| `run` | Inicia a ponte usando as rotas salvas e continua rodando até ser interrompida (`Ctrl+C`). |
+| `route add` / `route list` / `route remove <id>` | Gerencia rotas de forma não interativa — automatizável a partir de um script de shell ou de um playbook do Ansible. |
+| `list-ports` | Lista os dispositivos seriais USB conectados. |
+| `list-nodes` | Escuta a rede em busca de nós Art-Net (~3s) e os lista. |
+| `doctor` | Sinaliza dispositivos desconectados, rotas conflitantes e configurações fora do intervalo permitido no arquivo de configuração salvo. |
+| `install-service` / `uninstall-service` | Gera (e exibe, nunca aplica silenciosamente) uma unit do systemd (Linux) ou um agente launchd (macOS) para que a ponte reinicie automaticamente após uma reinicialização do sistema ou uma falha. |
+
+Configuração headless com um único comando em uma máquina com exatamente um universo Art-Net e uma interface USB DMX:
+
+```bash
+artnet2usb-cli auto --protocol enttec-pro --hz 40
+```
+
+Todo comando aceita `--config <dir>` para apontar para um diretório de configuração específico, e `run`/`auto` aceitam `--json` para emitir status em JSON delimitado por novas linhas em vez de texto legível para humanos (útil para supervisionar o processo a partir de outro script).
+
+## Configuração portátil
+
+O aplicativo procura primeiro por `config.json` ao lado do executável, para que possa viajar em um pendrive USB entre máquinas. Se esse diretório não for gravável (por exemplo, devido à "translocação de app" do Gatekeeper para um app macOS não assinado), ele recorre ao diretório de configuração padrão do sistema operacional por usuário. A GUI e a CLI compartilham exatamente o mesmo `config.json` quando executadas a partir da mesma pasta — monte rotas visualmente e depois as execute em modo headless, ou vice-versa.
+
+## Compilando a partir do código-fonte
+
+```bash
+npm install
+npm run dev             # GUI, servidor de desenvolvimento electron-vite
+npm test                # testes unitários (parser, framing, device uid, config)
+npm run typecheck       # tsc --noEmit
+npm run dist             # empacota a GUI para a plataforma hospedeira (electron-builder)
+npm run dev:cli          # executa a CLI a partir do código-fonte (tsx)
+npm run build:cli        # compila a CLI para dist-cli/
+```
+
+### Builds standalone de arquivo único
+
+Toda a saída standalone fica em `dist-standalone/`; cada artefato é um arquivo único, sem nada para instalar:
+
+```bash
+npm run dist:standalone                                   # plataforma hospedeira: GUI + CLI
+node scripts/build-standalone.mjs --cli --all-targets     # CLI: todas as plataformas em uma única execução
+node scripts/build-standalone.mjs --gui --mac --win       # GUI: apenas as plataformas selecionadas
+```
+
+A CLI é empacotada com `esbuild` e transformada em binários reais com [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) (não é necessário Node.js para executá-los); a GUI é empacotada com `electron-builder`.
+
+## Arquitetura
+
+```
+app/                      Processo principal do Electron
+  artnet.ts                Listener/parser Art-Net — sem biblioteca de protocolo externa, implementado à mão seguindo a spec
+  dmxOutput.ts              motor de saída + drivers de protocolo (Enttec Pro, Open DMX), via `serialport`
+  store.ts                  nomes de dispositivos / rotas / configurações, com prioridade à configuração portátil
+  main.ts, preload.ts       ciclo de vida do app Electron + a ponte IPC exposta ao renderer
+
+cli/                       CLI headless (compilada separadamente, veja tsconfig.cli.json)
+  index.ts                  definições de comandos (commander) + o assistente interativo (@clack/prompts)
+  bridge.ts, autoRoute.ts    lógica compartilhada de inicialização da ponte e seleção automática de universo/dispositivo único
+  routeCommands.ts           `route add/list/remove` — gerenciamento de rotas automatizável por script
+  serviceInstall.ts          geração de unit systemd/launchd
+  doctor.ts, configDir.ts    verificações de saúde da configuração + resolução do diretório de configuração
+
+shared/                    Código compartilhado entre a GUI e a CLI
+  types.ts                  RouteConfig, UsbDevice, e o restante da superfície de tipos compartilhada
+  store.ts, portableConfig.ts   o próprio arquivo de configuração + a regra de diretório portátil-vs-por-usuário
+
+scripts/build-standalone.mjs   o pipeline de distribuição de arquivo único (esbuild + @yao-pkg/pkg + electron-builder)
+scripts/embed-win-resources.mjs   incorpora um ícone + metadados de versão no .exe da CLI do Windows (via resedit)
+src/                       Renderer da GUI em React + Tailwind, incluindo src/locales/ para os 5 idiomas suportados
+```
+
+## Contribuindo
+
+Issues e pull requests são bem-vindos. Antes de abrir um PR, certifique-se de que `npm test` e `npm run typecheck` passem sem erros.
+
+## Licença
+
+[MIT](LICENSE) © Remana
+
+---
+
+<div align="center">
+
+Parte do ecossistema de controle de iluminação [Relackout](https://relackout.com).
+
+</div>

package/README.ru.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+<img src="src/public/logo.svg" alt="Relackout ArtNet 2 USB" width="96" height="96">
+
+# Relackout ArtNet 2 USB
+
+**Бесплатный, узкоспециализированный мост Art-Net → USB DMX с настольным GUI и headless CLI.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational)](#download)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+[Скачать](https://relackout.com/usb-dmx) · [Использование CLI](#cli-usage) · [Сборка из исходного кода](#building-from-source) · [Архитектура](#architecture)
+
+[English](README.md) · [Türkçe](README.tr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt-BR.md) · **Русский** · [简体中文](README.zh-Hans.md) · [日本語](README.ja.md)
+
+</div>
+
+---
+
+## Что это такое?
+
+Большинство программ управления освещением работают по сети через протокол **Art-Net**, но многим USB DMX-интерфейсам — таким как Enttec DMX USB Pro (и совместимые устройства), а также обычным адаптерам Open DMX / FTDI — по-прежнему нужно что-то на рабочем столе, что принимало бы этот сетевой сигнал и передавало его дальше через USB.
+
+**Relackout ArtNet 2 USB** — именно такой инструмент: небольшой узкоспециализированный мост, который просто работает в фоне. Он абсолютно бесплатен, не требует регистрации и создан для того, чтобы упростить работу со всей экосистемой Art-Net в целом — включая пульты и программы, не относящиеся к [Relackout](https://relackout.com).
+
+Поставляется в двух вариантах:
+- **Настольный GUI** — автоматическое обнаружение, живой предпросмотр 512 каналов и визуальная таблица маршрутизации.
+- **Headless CLI** (`artnet2usb-cli`) — тот же самый движок маршрутизации, но без интерфейса, созданный для Raspberry Pi за фермой, серверов без монитора за кулисами или для написания скриптов, настраивающих всю установку перед шоу. Оба варианта читают и записывают **один и тот же файл конфигурации**, поэтому можно настроить маршруты в GUI и запускать их в headless-режиме — или наоборот.
+
+## Возможности
+
+- **Автоматическое обнаружение** — пассивно прослушивает UDP-порт 6454 и отображает список всех вселенных (universe) Art-Net, транслируемых в сети, с указанием IP-адреса источника и текущей частоты кадров в реальном времени; сканирование узлов через `ArtPoll`/`ArtPollReply` находит устройства, которые ещё не транслируют DMX.
+- **Живой предпросмотр каналов** — наблюдайте за обновлением всех 512 каналов любой обнаруженной вселенной в реальном времени, ещё до настройки маршрутизации.
+- **Визуальная таблица маршрутизации** — каждая строка представляет собой одно правило: вселенная Art-Net → USB-устройство + протокол + частота обновления (1–44 Гц).
+- **Два протокола** — Enttec DMX USB Pro (и совместимые по прошивке клоны), а также прямой вывод Open DMX / FTDI.
+- **Постоянная идентификация устройств** — USB-интерфейсы запоминаются по их аппаратному идентификатору (ID производителя, ID продукта, серийный номер), а не по пути порта в ОС. Один раз переименуйте устройство — и его имя, а также связанные с ним маршруты, сохранятся даже после отключения и подключения к другому порту.
+- **Смещение патча каналов** — компенсируйте собственный стартовый DMX-адрес прибора или отличающуюся нумерацию каналов пульта, отдельно для каждого маршрута (`-511..511`). Вселенная сдвигается **циклически** в пределах своих 512 каналов — данные каналов никогда не теряются, а переносятся в начало/конец.
+- **Поведение при потере сигнала** — выберите, должен ли вывод удерживать последний кадр или уходить в блэкаут при исчезновении источника Art-Net.
+- **Портативная конфигурация** — запускается с USB-флешки без какой-либо установки; см. раздел [Портативная конфигурация](#portable-config) ниже.
+- **5 языков интерфейса в GUI** — English, Deutsch, Français, Italiano, Türkçe.
+
+## Скачать
+
+Готовые однофайловые сборки, не требующие установки, для Windows, macOS и Linux (включая Raspberry Pi для CLI) доступны на **[relackout.com/usb-dmx](https://relackout.com/usb-dmx)** и на странице [GitHub Releases](../../releases).
+
+| | Файл | Примечания |
+|---|---|---|
+| GUI · Windows | `Relackout-ArtNet2USB-<ver>-portable.exe` | Портативная версия — без установщика, просто запустите. |
+| GUI · macOS | `Relackout-ArtNet2USB-<ver>-<arch>.dmg` | Перетащите и запустите, без установщика. |
+| GUI · Linux | `Relackout-ArtNet2USB-<ver>-<arch>.AppImage` | Выполните `chmod +x` и запустите. |
+| CLI · все платформы | `artnet2usb-cli-<ver>-<platform>[.exe]` | Полноценный автономный бинарный файл — Node.js не требуется. Поддерживаются macOS (arm64/x64), Linux (x64/arm64/armv7l — включая Raspberry Pi) и Windows (x64). |
+
+> **Неподписанные сборки.** Релизы не подписаны цифровой подписью. При первом запуске в macOS потребуется *правый клик → Открыть*, а Windows SmartScreen потребует *Дополнительно → Выполнить в любом случае*.
+
+## Использование CLI
+
+```bash
+npx artnet2usb-cli                 # no args → interactive terminal wizard
+artnet2usb-cli --help              # full command reference
+```
+
+| Команда | Что она делает |
+|---|---|
+| `configure` | Интерактивный мастер для добавления/удаления маршрутов и, при желании, запуска моста. |
+| `auto` | Автоматически определяет единственную вселенную Art-Net и USB-устройство, сохраняет маршрут и запускает его (`--no-start`, чтобы пропустить запуск). |
+| `run` | Запускает мост, используя сохранённые маршруты, и работает до остановки (`Ctrl+C`). |
+| `route add` / `route list` / `route remove <id>` | Управление маршрутами без интерактивного режима — можно использовать в shell-скриптах или Ansible-плейбуках. |
+| `list-ports` | Выводит список подключённых USB serial-устройств. |
+| `list-nodes` | Прослушивает сеть на предмет узлов Art-Net (~3 с) и выводит их список. |
+| `doctor` | Отмечает отключённые устройства, конфликтующие маршруты и настройки вне допустимого диапазона в сохранённой конфигурации. |
+| `install-service` / `uninstall-service` | Генерирует (и выводит на экран, никогда не применяя молча) unit-файл systemd (Linux) или агент launchd (macOS), чтобы мост автоматически перезапускался после перезагрузки или сбоя. |
+
+Настройка headless-режима одной командой на машине ровно с одной вселенной Art-Net и одним USB DMX-интерфейсом:
+
+```bash
+artnet2usb-cli auto --protocol enttec-pro --hz 40
+```
+
+Любая команда принимает флаг `--config <dir>` для указания конкретного каталога конфигурации, а `run`/`auto` также принимают флаг `--json`, чтобы выводить статус построчно в формате JSON вместо текста, читаемого человеком (удобно для наблюдения за процессом из другого скрипта).
+
+## Портативная конфигурация
+
+Приложение сначала ищет `config.json` рядом с исполняемым файлом, чтобы конфигурацию можно было переносить между машинами на USB-флешке. Если этот каталог недоступен для записи (например, из-за механизма «app translocation» Gatekeeper для неподписанных приложений macOS), приложение переключается на стандартный для ОС каталог конфигурации пользователя. GUI и CLI используют один и тот же файл `config.json`, если запускаются из одной и той же папки — можно визуально настроить маршруты, а затем запускать их в headless-режиме, или наоборот.
+
+## Сборка из исходного кода
+
+```bash
+npm install
+npm run dev             # GUI, electron-vite dev server
+npm test                # unit tests (parser, framing, device uid, config)
+npm run typecheck       # tsc --noEmit
+npm run dist             # package the GUI for the host platform (electron-builder)
+npm run dev:cli          # run the CLI from source (tsx)
+npm run build:cli        # compile the CLI to dist-cli/
+```
+
+### Автономные однофайловые сборки
+
+Все автономные сборки попадают в `dist-standalone/`; каждый артефакт представляет собой единый файл, не требующий установки:
+
+```bash
+npm run dist:standalone                                   # host platform: GUI + CLI
+node scripts/build-standalone.mjs --cli --all-targets     # CLI: every platform in one pass
+node scripts/build-standalone.mjs --gui --mac --win       # GUI: selected platforms only
+```
+
+CLI собирается с помощью `esbuild` и упаковывается в реальные бинарные файлы с помощью [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) (для их запуска Node.js не требуется); GUI упаковывается с помощью `electron-builder`.
+
+## Архитектура
+
+```
+app/                      Electron main process
+  artnet.ts                Art-Net listener/parser — no external protocol library, hand-rolled to spec
+  dmxOutput.ts              output engine + protocol drivers (Enttec Pro, Open DMX), via `serialport`
+  store.ts                  device names / routes / settings, portable-config-first
+  main.ts, preload.ts       Electron app lifecycle + the IPC bridge exposed to the renderer
+
+cli/                       Headless CLI (compiles separately, see tsconfig.cli.json)
+  index.ts                  command definitions (commander) + the interactive wizard (@clack/prompts)
+  bridge.ts, autoRoute.ts    shared bridge start-up and single-universe/device auto-pick logic
+  routeCommands.ts           `route add/list/remove` — scriptable route management
+  serviceInstall.ts          systemd/launchd unit generation
+  doctor.ts, configDir.ts    config health checks + config-directory resolution
+
+shared/                    Code shared between the GUI and the CLI
+  types.ts                  RouteConfig, UsbDevice, and the rest of the shared type surface
+  store.ts, portableConfig.ts   the config file itself + the portable-vs-per-user directory rule
+
+scripts/build-standalone.mjs   the single-file distribution pipeline (esbuild + @yao-pkg/pkg + electron-builder)
+scripts/embed-win-resources.mjs   embeds an icon + version metadata into the Windows CLI .exe (via resedit)
+src/                       React + Tailwind renderer (GUI), including src/locales/ for the 5 supported languages
+```
+
+## Участие в разработке
+
+Issues и pull request'ы приветствуются. Перед открытием PR, пожалуйста, убедитесь, что команды `npm test` и `npm run typecheck` выполняются без ошибок.
+
+## Лицензия
+
+[MIT](LICENSE) © Remana
+
+---
+
+<div align="center">
+
+Часть экосистемы управления освещением [Relackout](https://relackout.com).
+
+</div>