From 3a99d9f8f4adf22f24129bb671dba387a88509a7 Mon Sep 17 00:00:00 2001 From: Peng Cheng Date: Sat, 10 Oct 2026 19:32:00 -0700 Subject: [PATCH 1/2] docs: rewrite the YouTube intro video script for the current macOS app The old script described a frosted-glass main window, SFSpeechRecognizer, filler-word removal, a ten-odd-MB footprint and double-click-to-run installs, none of which match the app today. The new script follows the shipped features shot by shot (in-app permissions, hardware-based model recommendation, dual-lane capture, live language switching, session export, overlay and global hotkeys), lists what must land before the video is published, ties every narration claim to the code or a measurement, and adds a recording checklist and YouTube metadata. Co-Authored-By: Claude Opus 5.5 --- docs/VIDEO_SCRIPT.md | 234 +++++++++++++++++++++++++++++++++---------- 1 file changed, 183 insertions(+), 51 deletions(-) diff --git a/docs/VIDEO_SCRIPT.md b/docs/VIDEO_SCRIPT.md index 933e81a..7298766 100644 --- a/docs/VIDEO_SCRIPT.md +++ b/docs/VIDEO_SCRIPT.md @@ -1,78 +1,210 @@ -# 🎬 LiveCaptions Translator (LCTMac) 项目介绍视频脚本 +# LCT for macOS 介绍视频脚本 -**视频时长**：约 3 分钟 -**视频风格**：极客风、快节奏、B-Roll展示与屏幕录制结合 -**背景音乐**：节奏轻快、科技感的电子节拍器（Synthwave 或 Lofi Chill） +- **时长**：约 3 分钟（9 个镜头） +- **平台 / 观众**：YouTube；对 Mac 有兴趣、经常看外语视频或开跨语言会议的人 +- **旁白**：中文（可以用 LCT 自己生成英文字幕后人工校对，作为 YouTube 字幕上传） +- **风格**：屏幕录制为主，少量文字卡。画面和 app 一致，用深色、等宽字体、emerald 绿色强调的"终端 HUD"风格，不要用炫光特效。 +- **一句话定位**：给 Mac 上的任何声音，包括视频、会议和你自己说的话，加上实时字幕和翻译，识别和翻译都在本机完成。 --- -### [00:00 - 00:30] 第一部分：痛点引入与破局 +## 1. 发布前置条件 -**【画面】** -- （B-Roll）一个用户戴着耳机，正在看一段无字幕的外语技术讲座视频，或者在开跨国 Zoom 视频会议。眉头紧锁，显然听得有些吃力。 -- 突然，镜头推近屏幕边缘。一个拥有高级“毛玻璃”质感的窄边框透明悬浮窗优雅地滑入画面。 -- 视频里的英文原声一出，悬浮窗上立刻以肉眼可见的极快速度，流式吐出了“经过精美排版和口语去噪”的中文翻译。 +下面几项没满足之前，视频可以先录，但**不要发布**。 -**【旁白（Voiceover）】** -> “跨国会议、无字幕外网生肉、外语连麦……语言障碍总是打破信息获取的流畅感。传统的语音翻译软件，要么网络延迟让人抓狂，要么把‘嗯、啊、那个’全翻出来，词不达意，并且那巨大厚重的窗口总是遮挡你的屏幕。” -> -> “今天，为你介绍专为 macOS 打造的原生实时翻译神器：**LiveCaptions Translator (LCTMac)**。极致轻量、零延迟感知、而且——完全本地化。” +| 条件 | 现状（2026-10-11） | 影响的镜头 | +|------|------------------|-----------| +| 公证过的 DMG 发布到 GitHub Releases | 等 Apple Developer 账号审批，见 `macos/RELEASE.md` | 镜头 9 的下载链接。没公证的话，用户双击会被 Gatekeeper 拦住 | +| 关窗后快捷键可用（PR #15）合入 master | 已 GUI 验证，等 CI 通过后合并 | 镜头 7 | +| 离线可用已实测 | **未验证** | 镜头 8。验证不通过就删掉这个镜头 | +| 录音中切到一个需要下载端侧模型的语言 | **未在 GUI 里测过** | 镜头 5 的可选旁白 | + +## 2. 分镜 + +时长按中文旁白每秒约 4 个字估算。 + +### 镜头 1　[00:00–00:12] 先看效果 + +**画面**：全屏播放一段英文演讲（本地视频文件）。屏幕下方是 LCT 的悬浮字幕窗：上行英文原文边说边出，下行中文译文流式出现。中途不暂停、不剪辑。 + +**旁白** +> 这是一段英文演讲。下面的中文字幕不是视频自带的，是我 Mac 上的一个小 app 边听边实时生成的。 + +**屏幕文字**：LCT · 实时字幕 + 翻译 + +**录制要点**：只用自己拍的、CC 授权或已获许可的视频。悬浮窗字号调大（设置里的 Overlay Font Size），Overlay Opacity 调到能看清视频。 --- -### [00:30 - 01:20] 第二部分：核心卖点展示 (UI与原生性能) +### 镜头 2　[00:12–00:32] 它是什么 + +**画面**：切到 LCT 主窗口。SYS 通道的字幕卡片一条条出现，上面原文、下面译文；顶栏显示 `rec 00:xx`、语言标签 `EN → ZH`、模型名和这一句的翻译耗时（ms）。 -**【画面】** -- （屏幕录制）展示 LCTMac 的“渐进式毛玻璃 HUD”。鼠标不在窗口时，它就像融化在桌面壁纸里，只有滚动的翻译字幕浮现在空中。 -- 鼠标移入（Hover），顶部的设置栏和底部的音频跳动条顺滑地淡入展现。 -- 开启 Activity Monitor (活动监视器)，特写 LCTMac 极低的内存（十几 MB）与 CPU 占用。 +**旁白** +> 它叫 LCT。Mac 上正在播放的声音，比如视频、直播、线上会议，还有你的麦克风，它都能实时转成字幕，再翻译成你要的语言。识别和翻译，全都在这台 Mac 上完成。 -**【旁白】** -> “LCTMac 摒弃了臃肿的跨平台框架。纯净的 Swift 与 SwiftUI 铸就了它无以伦比的性能与与生俱来的 macOS 基因。它引入了极简的毛玻璃悬浮交互设计。当你专注工作时，它是一条透明的滚动画框，绝不喧宾夺主；当鼠标悬停，控制面板如魔法般浮现，掌控一切。” -> -> “它不仅长得好看，更轻得不可思议。基于苹果原生的 SFSpeechRecognizer 框架捕获系统级音频与语音识别，几乎零负担。” +**屏幕文字**：苹果端侧语音识别 + 本机运行的开源大模型（Ollama） --- -### [01:20 - 02:10] 第三部分：真正的“魔法”——单路流式翻译管道与大模型 +### 镜头 3　[00:32–00:57] 第一次打开 -**【画面】** -- （架构演示动画 / 示意图）麦克风图标 -> 生成了一段杂乱带有“uh, you know”的英文草稿。 -- 草稿进入一个发光的方块（Ollama 图标）。 -- 输出分为两层文本：原句被浓缩成了小字注脚，而精炼的完美中文用大字加粗流式打在屏幕上。 -- （屏幕录制）打开设置面板，展示填写了 `qwen3.5:4b-mlx` 模型的过程。 +**画面** +1. 引导页 "Permissions Required" 有三行：Microphone、Speech Recognition、System Audio。逐个点 Allow，系统弹框直接点"允许"，每一行变成 ✓。全程没有打开系统设置。 +2. 模型页："Recommended for your Mac (Apple M2 Pro, 16 GB)"，推荐 `qwen3.5:4b-mlx`。点下载，进度条和 `x GB / y GB` 走动（可以快进剪辑）。 +3. "LCT is ready to use"，点 Get Started。 -**【旁白】** -> “但 LCTMac 最迷人的魔法，在它的‘大脑’里。我们重构了字幕的流式管道处理引擎（Caption Segmenter）。对于随口而出的破碎语音，它并非死板地直翻。” -> -> “我们无缝对接了 Ollama 本地大语言模型。只需要部署一个像 Qwen 4B 这样的甜点级本地模型，LCTMac 就能在后台执行高难度的‘单次提问双向输出’指令：它会一秒去除你听到的口头禅、纠正语病，再流式输出最高质量的本土化翻译。” -> -> “而且别忘了，这一切都在你的 Mac 本地沙盒里进行。**你的会议机密，一个字节都不会传到云端。**” +**旁白** +> 第一次打开，麦克风、语音识别、系统声音三个权限，都在 app 里点一下就好，不用去系统设置里翻找。录系统声音也不需要屏幕录制权限。然后它会根据你的芯片和内存推荐一个合适的翻译模型，一键下载。 + +**录制要点**：首次启动的画面需要干净的权限记录和空的模型目录。**新建一个 macOS 用户账户来录**：权限和 Ollama 模型（`~/.ollama`）都是按用户分开的，这样不会影响日常使用的账户。新账户里要先装好 Ollama，否则会停在 "Ollama Required" 页。 --- -### [02:10 - 02:40] 第四部分：极客最爱的开源工作流 +### 镜头 4　[00:57–01:27] 开会：两路同时听 + +**画面**：左边是会议画面（用预录的英文视频模拟对方发言），右边是 LCT 主窗口。对方说话时出现 `SYS` 卡片，你对着麦克风说英文时出现橙色的 `MIC` 卡片，两路交替出现、互不打断。底部两条电平条分别跳动。 -**【画面】** -- （屏幕录制）打开 GitHub 页面，展示 LCTMac 的代码仓库。 -- 切换到 Actions 页面，展示一个绿色的 ✅ “macOS Build and Release” 正在打出一个 `LCTMac-macOS.zip` 的下载包。 +**旁白** +> 开会的时候，它同时听两路：对方的声音来自系统音频，标成 SYS；你说的话来自麦克风，标成 MIC。两路各自识别，可以用不同的语言，互不打断。每一句都有原文和译文，右上角是这一句的翻译耗时。 -**【旁白】** -> “作为一个开源项目，我们为你铺平了所有道路。LCT 内部集成了完整的自动化 CI/CD GitHub Actions 工作流，只要提交代码，立刻在云端打包生成 Mac 应用程序分发包。” -> -> “下载、解压、双击即用。” +**录制要点** +- **戴耳机录**。否则麦克风会收到扬声器的声音，MIC 通道会重复识别对方的话，还会弹出 "Hearing audio on MIC but recognizing nothing" 提示。 +- 两路都设成英文，翻译目标设成中文。**不要让某一路的识别语言和翻译目标相同**（比如 MIC 中文、翻译成中文）：现在不会跳过翻译，画面上会出现"中文翻成中文"。 +- 双通道需要 macOS 26 或更新的系统。 --- -### [02:40 - 03:00] 第五部分：Outro 与 Call to Action +### 镜头 5　[01:27–01:45] 录着音换语言 -**【画面】** -- 快速蒙太奇（Montage）：在看 YouTube 视频时使用 LCTMac、在开 Zoom 会议时使用、在看无字日漫时使用。 -- 屏幕中央出现 GitHub 项目链接地址与项目 Logo。 +**画面**：点顶栏的语言标签，菜单展开，分为 System audio、Microphone、Translate to 三组。录音不停，把 Translate to 从 Chinese 改成 Japanese。下一句字幕直接变成日文，标签变成 `EN → JA`。 -**【旁白】** -> “打破语言的高墙，把隐私留在本地，用最优雅的姿态体验跨语言的魅力。” -> -> “这就是 LiveCaptions Translator。即刻前往 GitHub 下载体验，如果你觉得好用，别忘了给我们的项目点一个 Star 🌟。让我们一起，重新定义本地 AI 翻译！” +**旁白** +> 换语言不用停。点一下顶栏，系统声音、麦克风、翻译目标，录着音就能改，下一句马上生效。 + +**可选旁白**（前置条件验证后才用） +> 第一次用某种语言时，它会自动下载苹果的端侧识别模型。 + +--- + +### 镜头 6　[01:45–02:02] 导出 + +**画面**：停止录音，按 ⌘E，保存面板里默认文件名是 `LCT Session 2026-10-11 14.03.md`。保存后在编辑器里打开，能看到标题、时长、语言，以及每句的 `[00:01:23] SYS` 原文和 `>` 引用的译文。再展示一下 File 菜单里的另外两项：Text、Subtitles (SRT)。 + +**旁白** +> 结束之后，整场的字幕可以一键导出：Markdown 笔记、纯文本，或者 SRT 字幕文件。每一句都带时间、来源和译文，会议纪要直接就有了。 + +**录制要点**：SRT 的时间是按"定稿时刻 + 字数"估算出来的，不是逐字对齐。**不要拍"把 SRT 拖进播放器和原视频对齐"的镜头**。 + +--- + +### 镜头 7　[02:02–02:18] 悬浮字幕和全局快捷键 + +**画面** +1. 在全屏视频里按 ⌃⌥⌘O，悬浮字幕窗淡入（毛玻璃圆角卡片），鼠标移上去会出现控制栏。 +2. 切到别的 app（比如浏览器），按 ⌃⌥⌘S 开始、再按一次停止。 +3. 关掉 LCT 主窗口，菜单栏图标还在。从菜单栏图标选 Start Capture，主窗口自动回来并开始录音。 + +**旁白** +> 不想一直开着窗口？按快捷键呼出悬浮字幕，叠在全屏视频上；在任何 app 里都能用快捷键开始和停止。关掉主窗口，它也会在菜单栏里继续工作。 + +**屏幕文字**：⌃⌥⌘S 开始/停止 · ⌃⌥⌘P 暂停 · ⌃⌥⌘O 悬浮字幕 + +--- + +### 镜头 8　[02:18–02:32] 断网也能用（需先验证） + +**画面**：在菜单栏关掉 Wi-Fi，图标变灰。播放本地视频，字幕和翻译照常出现。 + +**旁白** +> 因为识别和翻译都在本机，断开网络它照样工作。你的会议内容不会上传到任何服务器。 + +**录制要点**：先完整实测一遍：要用的识别语言的端侧模型和翻译模型都已下载，Ollama 用默认的本机地址。只要有一项不满足，就删掉这个镜头和对应旁白。 + +--- + +### 镜头 9　[02:32–02:55] 要求和下载 + +**画面**：文字卡依次出现，最后是 GitHub 仓库地址和 Releases 页面。 + +**旁白** +> LCT 是开源的。需要 macOS 15 或更新的系统，双通道需要 macOS 26，推荐用 Apple 芯片的 Mac，再装一个免费的 Ollama。下载链接在简介里。觉得有用的话，欢迎去 GitHub 点个 Star。 + +**屏幕文字** +- macOS 15+（双通道：macOS 26+） +- 推荐 Apple 芯片；翻译模型由 Ollama 在本机运行（免费） +- github.com/PCcoding666/LCT + +--- -*(视频渐暗，淡出，音乐结尾)* +## 3. 旁白依据 + +每个说法都要能在 app 里复现。改旁白时同步改这张表。 + +| 旁白里的说法 | 依据 | +|-------------|------| +| 系统声音不需要屏幕录制权限 | 系统音频用 Core Audio 进程截取（`SystemAudioTap`），第一次使用由系统弹出"允许"框 | +| 权限在 app 里点一下就好 | 引导页的三行 Allow 按钮（`WelcomeView`）。拒绝过的权限仍然要去系统设置里打开，系统音频这一行会给出 "Open Settings" 按钮 | +| 识别在本机完成 | macOS 26+ 用 SpeechAnalyzer + SpeechTranscriber，macOS 15–25 用 SFSpeechRecognizer 端侧模式。某种语言第一次使用时，需要从 Apple 下载端侧模型 | +| 翻译在本机完成 | 默认连 `localhost:11434` 的 Ollama。设置里可以改成远程地址，那时就不是本机了 | +| 两路同时听、可以用不同语言 | 仅 macOS 26+：每路一个独立的 analyzer。macOS 15–25 只有系统音频一路 | +| 翻译目标 | 一个，两路共用。识别语言 14 种（能否使用取决于系统的端侧支持），翻译目标 10 种 | +| 根据芯片和内存推荐模型 | `ModelRecommender`：Apple 芯片推荐 MLX 版 qwen3.5（4B / 2B / 0.8B），Intel 推荐普通版本 | +| 右上角是翻译耗时 | 实测 393–984 ms/句（M2 Pro、16 GB、qwen3.5:4b-mlx、模型已预热，2026-10-10） | +| 录着音就能改语言 | 只重启受影响的那一路识别，另一路不受影响；改翻译目标不重启任何东西 | +| 导出三种格式 | File 菜单和顶栏导出按钮。内容是从上次点"开始"起的整场记录，不受界面只显示最近 5 张卡片的限制 | +| 关掉主窗口也能工作 | 菜单栏图标、Window 菜单、全局快捷键在主窗口关闭时都能开始和停止（PR #15） | + +## 4. 不要说的话 + +旧版脚本里的这些说法不准确，不要再用： + +- "零延迟"：每句的翻译耗时是几百毫秒，镜头 2、4 里画面会直接显示出来。 +- "内存只有十几 MB"：app 本身实测空闲约 49 MB、峰值约 66 MB（physical footprint）。翻译模型在 Ollama 里另算：`qwen3.5:4b-mlx` 现在常驻约 **10 GB**，因为 Ollama 默认按 32K 上下文加载；改成 4K 上下文实测约 4 GB，这个改动还没做。**改之前不要拍内存镜头。** +- "基于 SFSpeechRecognizer"：macOS 26+ 已经换成 SpeechAnalyzer。 +- "去掉口头禅、纠正语病"：翻译提示词没有这项功能，只要求把不完整的句子译得自然。 +- "毛玻璃 HUD 主窗口"：主窗口是终端 HUD 风格，只有悬浮字幕窗是毛玻璃。 +- "下载、解压、双击即用"：还需要装 Ollama 并下载翻译模型；公证之前还会被 Gatekeeper 拦住。 +- "一个字节都不会传到云端"：改成"识别和翻译都在本机完成"。下载语言模型和翻译模型时需要联网。 + +## 5. 录制准备清单 + +- [ ] 用公证过的 Release 版录，不要用 `dev-run.sh` 的开发版：终端输出里有开发证书和邮箱，不能出镜。 +- [ ] 打开勿扰模式；隐藏桌面图标；检查菜单栏和 Dock 里没有个人信息。 +- [ ] 开始前点一次 Start 再 Stop，让翻译模型预热，避免第一句等好几秒。 +- [ ] 每个镜头开始前用垃圾桶按钮清空字幕卡片。 +- [ ] 主窗口和悬浮窗字号调大，按 1080p 观看也能看清。 +- [ ] 历史记录保持默认关闭。录完删掉测试导出的文件，特别是录到环境声音的那些。 +- [ ] 镜头 4 戴耳机。 +- [ ] 镜头 3 在新建的 macOS 用户账户里录。 +- [ ] 所有视频素材都有使用权。 + +## 6. YouTube 信息草稿 + +**标题候选** +1. 我的 Mac 现在能给任何声音实时加中文字幕（本地运行，开源） +2. LCT：Mac 上的实时字幕 + 翻译，识别和翻译都在本机完成 +3. 看外语视频、开跨语言会议，我用这个开源小工具 + +**简介** +``` +LCT 给 Mac 上的任何声音加上实时字幕和翻译，包括视频、直播、线上会议和你的麦克风。 +语音识别用苹果的端侧模型，翻译用 Ollama 在本机运行的开源大模型。 + +下载： +源码：https://github.com/PCcoding666/LCT + +系统要求：macOS 15+（双通道需要 macOS 26+）；推荐 Apple 芯片；需要安装 Ollama（免费） + +00:00 效果演示 +00:12 LCT 是什么 +00:32 第一次打开：权限和模型 +00:57 开会：两路同时听 +01:27 录着音换语言 +01:45 导出 Markdown / TXT / SRT +02:02 悬浮字幕和全局快捷键 +02:18 断网也能用 +02:32 下载 +``` + +**标签**：macOS, 实时字幕, 实时翻译, Ollama, 本地大模型, 开源, live captions, translation From e6781381bf27bfe123048e9065aa0922e2361bf7 Mon Sep 17 00:00:00 2001 From: Peng Cheng Date: Sat, 10 Oct 2026 19:32:05 -0700 Subject: [PATCH 2/2] docs: describe the macOS speech stack accurately in the README Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f29f0eb..81ecdb9 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ meetings, videos, or calls across a language barrier. | Platform | Stack | Status | Docs | |----------|-------|--------|------| | [Windows](windows/) | C# / .NET 8 (WPF) + LiveCaptions | Stable | [windows/README.md](windows/README.md) | -| [macOS](macos/) | SwiftUI + `SFSpeechRecognizer` + local LLM (Ollama) | Active development | [macos/README.md](macos/README.md) | +| [macOS](macos/) | SwiftUI + on-device speech (`SpeechAnalyzer` on macOS 26+, `SFSpeechRecognizer` on 15–25) + local LLM (Ollama) | Active development | [macos/README.md](macos/README.md) | The two apps are independent codebases tuned to each platform's native speech and UI frameworks. They share this repository for common documentation, translation