101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# Lumi Companion
|
|
|
|
Lumi Companion is the Windows streaming-computer client for Lumi. It provides a
|
|
single paired-device shell for Companion plugins, including server-hosted
|
|
transcription and Song Overlay capture. The app is single-instance, installs per
|
|
Windows user, closes to the notification area, and preserves pairing and settings
|
|
across updates.
|
|
|
|
## Install and pair
|
|
|
|
From Lumi, open **Admin > Companion** and choose **Download Companion**. The
|
|
private ZIP contains:
|
|
|
|
- the checksum-pinned per-user Windows installer;
|
|
- a one-time `.lumi-pairing.json` package;
|
|
- a Host Operator notice and start instructions.
|
|
|
|
Extract the ZIP and run `Lumi.Companion-Setup.exe`. Setup installs to
|
|
`%LocalAppData%\Programs\Lumi Companion`, displays the licence and privacy
|
|
notices, identifies the paired Lumi host, imports the adjacent pairing package,
|
|
and opens the installed copy. The extracted download can then be deleted.
|
|
|
|
Existing portable or installed builds retain the current Windows user's
|
|
DPAPI-protected device identity, so reinstalling does not create a duplicate
|
|
paired device. Pairing packages expire after 15 minutes, work once, and must not
|
|
be shared or committed.
|
|
|
|
## Security boundaries
|
|
|
|
- Companion plugins inherit the shell's paired-device authentication. Plugins do
|
|
not store or request separate Lumi credentials.
|
|
- Production Companion traffic requires HTTPS. Plain HTTP/WebSocket traffic is
|
|
accepted only when the device was paired from the exact matching loopback Lumi
|
|
origin and the request remains on loopback.
|
|
- The OBS integration communicates with Companion through a same-user named pipe.
|
|
- Transcription audio is normalized to 16 kHz mono signed 16-bit PCM, kept in
|
|
bounded memory, and sent to the paired Lumi host. Companion does not perform
|
|
local speech recognition.
|
|
- Installing or repairing the OBS integration requests elevation only while OBS
|
|
is closed and only to copy the verified managed component into OBS's shared
|
|
ProgramData plugin directory.
|
|
|
|
## Updates
|
|
|
|
Companion checks after connecting and every six hours. Updates are
|
|
user-approved, size- and checksum-verified, and refused while OBS is streaming or
|
|
recording. Applying an update replaces the installed executable, bundled
|
|
components, and legal bundle, then restarts Companion. Pairing credentials,
|
|
settings, and plugin state remain in the per-user data directory.
|
|
|
|
Localhost development builds can also receive checksum-addressed same-version
|
|
updates without publishing a release. See
|
|
[Localhost development updates](../docs/local-development-updates.md).
|
|
|
|
## Build and verify
|
|
|
|
Requirements:
|
|
|
|
- Windows x64;
|
|
- a current .NET SDK with the .NET 8 targeting pack;
|
|
- CMake and Visual Studio C++ tools for the native OBS bridge;
|
|
- Inno Setup 6 for the installer.
|
|
|
|
Build the managed solution:
|
|
|
|
```powershell
|
|
dotnet build companion/Lumi.Companion.sln -c Release -p:EnableWindowsTargeting=true
|
|
```
|
|
|
|
Build the pinned OBS bridge, self-contained archive, legal bundle, and installer:
|
|
|
|
```powershell
|
|
companion/scripts/publish-companion.ps1
|
|
```
|
|
|
|
The publish script generates the shared application/tray icon, verifies the OBS
|
|
payload inside the published executable, collects NuGet notices, and packages the
|
|
corresponding source for the GPL-licensed OBS bridge.
|
|
|
|
Run Song Overlay's focused verification with:
|
|
|
|
```powershell
|
|
companion/scripts/verify-song-overlay.ps1
|
|
```
|
|
|
|
Generated installers, pairing packages, credentials, build output, and logs must
|
|
not be committed.
|
|
|
|
## Distribution and legal notices
|
|
|
|
The release is currently unsigned, so Windows may show an unknown-publisher
|
|
warning. The installer and installed `legal` directory include the Companion
|
|
licence, default privacy notice, third-party notices, exact licence texts, and
|
|
the corresponding OBS bridge source bundle.
|
|
|
|
Self-hosters should set `LUMI_OPERATOR_NAME`, `LUMI_OPERATOR_CONTACT`, and
|
|
`LUMI_OPERATOR_PRIVACY_URL`. Those values identify the Host Operator responsible
|
|
for its hosted service and server-side processing; OokamiKunTV is the software
|
|
developer and is not automatically the operator of an independently hosted Lumi
|
|
installation.
|