# Tally灯Web播报-PC

**Repository Path**: cdrbs/tally-light--web-broadcast--pc

## Basic Information

- **Project Name**: Tally灯Web播报-PC
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> ⚠ **【本仓库已冻结 · Frozen】** 自 2026-09-22 起，老桌面端（GDI+ 绘制）进入**冻结状态**：
> 除非项目所有者**特别说明**，不再主动进行代码修正、功能升级或能力扩展。现有功能与已发布产物保持原样、仍可正常使用；
> 后续维护重心已转向薄容器端 **`tally-desktop-webview`**（桌面 WebView 版）。如有紧急修复或明确需求，请单独指示。
>

# TallyDesk —— 桌面无感 Tally 浮层

> 与现有 `vMix Tally 灯系统` 共用同一套协议与状态契约（`app/lib/store.js` 全量快照、`docs/灯侧技术对接指南.md`），但载体从浏览器换成了 Windows 桌面浮层：**置顶透明、鼠标穿透、不抢焦点、不进任务栏/Alt-Tab**，常驻工作时几乎无感，Cue 脉冲与导播消息时整屏升级为强提示。

## 设计要点

| 维度 | 做法 |
| --- | --- |
| 窗口样式 | `WS_EX_LAYERED|WS_EX_TRANSPARENT|WS_EX_TOPMOST|WS_EX_TOOLWINDOW|WS_EX_NOACTIVATE` —— 每像素 alpha、鼠标穿透、置顶、不在 Alt-Tab、不抢焦点 |
| 状态判定 | 严格按对接指南 §3 算法（`tallyByCh` 优先 / `sender.online` / 集合语义 `onAir` / `previews`） |
| 形态切换 | 配置文件 `LAYOUT=glow,capsule,bar,veil` 可同时启用多个，运行时叠加 |
| Cue 强提示 | 跟随服务端 `config.cue.displayMode`：`banner`=顶部横幅 / `bigtext`=全屏大字（与网页灯页完全一致） |
| 提示音 | PC 端不受浏览器自动播放策略限制：切态"叮"、Cue"嘀"（按 `cue.hz` 循环）、消息"叮-咚"，均为运行时合成 PCM WAV |
| 通讯 | SSE `/events?type=tally` 主通道（自报灯页客户端，计入在线数）+ `/api/state` 8s 超时轮询兜底（与 `app/web/tally.html` 同一契约） |
| 协议 | 只读消费（指南 §2.4 明确边界），不写服务端、不持有任何凭据 |

## 形态

| 形态 | 效果 | 适用 |
| --- | --- | --- |
| `glow`（默认） | 屏幕四边柔光描边，色随通道状态，中心完全透明 | 几乎所有工作场景（看视频、剪片、码字都不影响） |
| `capsule` | 屏幕某角半透明圆角胶囊：通道号 + 状态词 + 源名 | 需要文字状态时 |
| `bar` | 屏幕顶部一条细色条（可带状态词） | 最简洁 |
| `veil` | 整屏铺一层极淡色罩 | 最接近网页灯页观感（对画面有轻微影响） |

Cue / 消息到来时**所有形态自动升级**（banner/bigtext 由服务端 `config.cue.displayMode` 控制；`glow` 在 Cue 期间加宽并切到 tint 色并按节拍闪动）。

## 构建

需要本机 Go 1.21+（已验证 Go 1.27.1）+ MinGW-w64（cgo）。**主链路（SSE/渲染/托盘/网络）仅用
Go 标准库，零第三方包**；语音通话模块经 cgo 链接 libopus（MSYS2 预编译静态库，已随仓库存放于

> **Go 工具链选择（build.bat 已自动处理）**：`build.bat` 优先使用仓库自带的
> `..\.workbuddy\tools\go\bin\go.exe`（并显式设置其 GOROOT/GOPATH/GOCACHE）。这是**必需**的：
> ① cgo 对 UCRT 版 MinGW（GCC 13+）的链接要求 Go ≥ 1.20，系统 Go 1.19 必报
> `undefined reference to __imp___iob_func`（`-lmsvcrt` 无效）；② 若系统环境设了全局
> `GOROOT` 指向旧 Go，即使调用了新 go.exe 也会混用旧标准库（报
> `compile: version "go1.19.x" does not match go tool version`）。手动 `go build` 时请自行
> 设置同样的 GOROOT/GOPATH/GOCACHE。
`thirdparty/mingw64/`，无需单独安装——构建脚本只要求 MinGW 提供 gcc）。

```bat
cd tally-desktop
build.bat
```

> `build.bat` 刻意写成 **纯 ASCII + CRLF**：`cmd.exe` 用控制台 OEM 代码页（中文环境 936）解码 bat，
> 中文会乱码、UTF-8 BOM 还会让首行 `@echo off` 失效。所以脚本提示一律英文，中文说明看本文档。
> 配套 `.gitattributes` 已强制 `*.bat text eol=crlf`，避免 git 把行尾改回 LF。

产物：

| 文件 | 架构 | 适用 |
| --- | --- | --- |
| `build/TallyDesk.exe` | x64（PE32+，7.3 MB） | 64 位 Windows（Vista 以来所有主流机器） |

> 曾提供过 win32/x86 版本（`TallyDesk-x86.exe`），2026-09 起废弃，仅保留 x64 —— 老机器 32 位系统请改用网页灯页。
>
> - `build/preview/` —— 离屏自检生成的样图（29 张形态图 + 16 张托盘图，仅供验证）

如需手动构建（不重做图标资源时）：

```bash
set GOOS=windows
set GOARCH=amd64 && go build -ldflags="-s -w -H=windowsgui" -o build/TallyDesk.exe .
go run ./tools/pesetver build/TallyDesk.exe 6 1   # Win7 兼容（见 handoff §6.14）
```

> 资源文件 `resource_windows_amd64.syso` 由 `windres -F pe-x86-64` 生成，`.syso` 带 COFF 机器类型，
> 必须与 GOARCH 匹配（历史坑：32 位 `.syso` 链 64 位目标会报链接错误，反之亦然）。

## 多显示器

`MONITOR` 配置项支持一块或多块屏，**每块屏各铺一层浮层，状态完全同步**：

| 写法 | 效果 |
| --- | --- |
| `MONITOR=primary` | 仅主屏（默认，向后兼容） |
| `MONITOR=all` | 全部显示器 |
| `MONITOR=1,2` | 按编号指定多块 |
| `MONITOR=primary,2` | 可混合 |

编号按屏幕**物理排布「先左后右、再上下」**排序，跨重启稳定（与系统设置里的任意编号无关）。
重载配置时窗口数量自动对齐：多插/拔掉显示器后改配置即可，缺的补建、多的销毁，无需重启程序。

## 个性化（图标 & 版权）

三件事分别在不同位置改，**互不干扰**：

| 想改什么 | 改哪里 | 要重新构建吗 |
| --- | --- | --- |
| **换托盘图标**（临时/本机生效） | `tally-desk.txt` 里写 `TRAY_ICON=C:\path\logo.ico` | 不用，右键托盘 →「重载配置」 |
| **换随 exe 分发的默认图标** | 用任意 `.ico` 覆盖 `res/app.ico` | 需要，`build.bat` |
| **改产品名 / 公司 / 版权 / 版本号** | `res/app.rc` 顶部「可定制字段」区的 6 个宏 | 需要，`build.bat` |

> exe 的**文件图标**（资源管理器、任务栏、Alt-Tab 里看到的那张图）来自 `res/app.ico`，
> 走 `build.bat` 自动重建资源；仅改 `TRAY_ICON` 只会影响托盘，不会改变 exe 文件图标。

### 1. 版权与版本（res/app.rc）

```c
#define APP_NAME        "Tally 桌面浮层"               /* 产品名称 */
#define APP_DESC        "vMix Tally 桌面无感提示浮层"  /* 文件说明 */
#define APP_COMPANY     "Tallydesk"                    /* 公司/组织 */
#define APP_COPYRIGHT   "Copyright (c) 2026 Tallydesk" /* 版权声明 */
#define APP_VERSION_STR "1.0.0.0"                      /* 版本字符串 */
#define APP_VERSION_NUM 1,0,0,0                        /* 版本数字（4 段） */
```

改完 `build.bat` 之后，右键 `TallyDesk.exe` → **属性 → 详细信息** 即可看到。
`APP_VERSION_STR` 与 `APP_VERSION_NUM` 要保持一致（前者给人看，后者给系统看）。

### 2. 图标（res/app.ico）

- 直接用现成 `.ico` 覆盖即可，**建议 256×256 且内含多个尺寸**（16/32/48/256），这样资源管理器在「大图标/小图标」下都清晰
- 仓库自带的 `res/app.ico` 是示例图标（红底白 T），由 `tools/mkicon` 生成，可重新生成：

```bash
go run ./tools/mkicon res/app.ico        # 改色/改字形请编辑 tools/mkicon/main.go 顶部的品牌色与字形比例
go run ./tools/mkiconres res/app.ico res/icon_rt.bin res/icon_grp.bin
windres -F pe-x86-64 -c 65001 -i res/app.rc -o resource_windows_amd64.syso
windres -F pe-i386   -c 65001 -i res/app.rc -o resource_windows_386.syso
```
  以上三步 `build.bat` 已自动串好，正常只需双击它。
  手动执行时 `-c 65001` 不能省，否则中文名称/说明会变成乱码（`-F pe-x86-64` 同理，否则链接失败）。

### 3. 托盘状态表达方式（TRAY_ICON_STYLE）

有了基底图标后，通道状态怎么表达，由 `TRAY_ICON_STYLE` 决定：

| 值 | 效果 | 适合 |
| --- | --- | --- |
| `dot`（默认） | 右下角叠一个状态色圆点 + 白描边，logo 本体不动 | 彩色 logo，想保留原样 |
| `tint` | 用状态色整体染色，保留明暗层次 | 单色/剪影 logo |
| `static` | 永远显示原始图标，不表达状态 | 只想显示品牌、状态看浮层 |
| `none` | 不用基底图标，退回纯状态色点 | 未个性化时的兜底 |

排查：`TallyDesk.exe --selftest <目录>` 会导出 16 张 `tray-<style>-<state>.png` 预览
（4 风格 × 4 状态，6 倍放大）与 `tray-debug.txt` 载入诊断。

## 运行

1. 把 `TallyDesk.exe` 复制到任意目录
2. 双击运行：首次会生成 `tally-desk.txt` 模板（消息框提示）
3. 填写 `SERVER_URL` 与 `CHANNEL`，保存后**自动重载**（2s 轮询 + 500ms 防抖），也可右键托盘 →「重载配置」手动触发
4. 浮层即时出现在配置指定显示器，状态实时同步服务端

> 连接中断时托盘图标变灰并弹出气泡提示，恢复后自动通知；无需人工干预。

## 托盘菜单

- **隐藏/显示浮层**：暂时让位
- **切换通道 → N 号机**：服务端开放的通道快速切换（无需改配置）
- **加入/退出语音通话**：文案实时反映当前两维度状态（如「退出语音通话（闭麦·听导播）」）；服务端未开启语音时置灰
- **语音模式（两组独立）**：通话中可用的子菜单——**麦克风**（开麦 / 闭麦）与**收听范围**（听所有 / 听导播）是两组独立勾选项，可任意叠加（如「开麦 + 只听导播」）；播出（PGM）联动期间开麦意图会标注「上行已闭」，切出播出自动恢复
- **重载配置**：编辑保存后无需重启
- **打开配置文件**：一键打开 `tally-desk.txt` 关联的编辑器
- **开机自启**：写入 `HKCU\...\Run`
- **退出**

托盘图标本身按状态实时变色（PGM 红 / PVW 绿 / Cue tint / 离线灰），无需打开浮层也能扫一眼。

## 与现有 web 灯页的关系

- **不修改任何现有文件** —— 本目录（`desktop/`）完全独立
- **协议层严格对齐** `app/lib/store.js` snapshot 字段与 `docs/灯侧技术对接指南.md`（指南 §3、§4、§5、§6 是契约）
- **任何灯侧改动**（新增快照字段、Cue 话术调整、音/震参数）需同步指南、网页 `tally.html` 与本项目 `state.go` / `sound.go` / `render.go`

## 已知边界

- 仅 Windows（依赖 GDI+/user32 分层窗口，跨平台需另寻方案如 Qt/GTK/Tauri）
- **支持 Windows 7 SP1 及以上**（通过 `tools/pesetver` 把 PE 子系统最低版本降到 6.1，详见 `handoff.md` §6.14）；不是"只支持 Win8/10/11"
- 多显示器：`MONITOR` 支持 `all` 与多编号（见「多显示器」章节）；缩放/旋转屏幕需在主屏（DPI 100%）
- 启动后托盘已激活，重复启动会被单实例 mutex 拦截并提示
- 配置可热重载（保存后自动检测，也可手动点托盘）；显示器插拔/分辨率变化时自动对齐窗口数量与位置（`WM_DISPLAYCHANGE`），无需重启
- 光敏用户可设 `REDUCE_MOTION=1`：禁用所有闪动/脉冲，Cue 改用稳态表达（覆盖 `CUE_FLASH`）
- **语音对讲请佩戴耳机**：桌面端用 waveIn 裸采集，无回声消除（Web/Android 有系统级 AEC）；用外放音箱开麦会产生回声/啸叫，且会被导播在控制台强制静音
- 被导播从「语音控制台」踢出时以 4000 终态断开，本端提示"已被导播移出"且不自动重连