vMix GT 字幕 API 实战指南
面向赛事直播字幕工作流 · 覆盖 vMix Title 分类全部 24 个函数（v24+，SetColor 需 v25+） · 数据依据 vmixapi.com 与 vMix 官方文档
本指南约定：函数名、参数名、元素名一律保留英文原样（API 调用时必须逐字一致），中文只做讲解。示例中的输入名
Scorebug、NameBar 等请替换为你自己 vMix 工程里的实际输入名。〇、先搞懂三件事
1. SelectedName：GT 模板里的“字段名”是什么？
SetText、SetImage 这类函数不是“往屏幕某个位置写字”，而是修改某个 GT 字幕输入里某个具名字段的内容。字段名在 GT Designer 设计模板时定义：
- 文本字段：SelectedName 通常写成
名称.Text，例如Headline.Text、ScoreHome.Text（官方示例也允许只写Headline，建议统一带.Text后缀，最稳）。 - 图片字段：写成
名称.Source，例如Image01.Source、LogoA.Source。 - 也可以用 SelectedIndex（从 0 开始的序号）代替字段名，但模板调整字段顺序后序号会变，赛事工程强烈建议用 SelectedName。
三种查字段名的方法：
- GT Designer：打开 .gtzip 模板，在右侧/图层面板选中文本或图像对象，看它的 Name 属性——这就是字段名主体。
- vMix 界面：双击输入打开 Title Editor，鼠标悬停或点击各文本框，界面会显示对应字段名。
- 查 API 的 XML：浏览器访问
http://127.0.0.1:8088/api/，找到该 Title 输入，里面直接列出<text index="0" name="Headline">当前文字</text>，name 就是字段名。
2. Input：怎么指定要改哪条字幕？
用输入的编号（如 Input=5，从 1 开始；0=Preview，-1=Output）、名称（如 Input=Scorebug）或 GUID。名称可以包含空格和中文，无需加引号。强烈建议在 vMix 里给字幕输入改成简短英文名（如 Scorebug、NameBar、Ticker），脚本长期稳定不被编号变动影响。
3. 三种调用方式选哪个？
| 方式 | 形态 | 典型用途 |
|---|---|---|
| HTTP GET | 浏览器地址栏 / Stream Deck / Bitfocus Companion 直接请求 URL | 按钮触发、联调测试、外部系统集成 |
| Web 脚本 | vMix 内置（Settings → Scripting），每行一条 Function=...，可用 Sleep 2000 串联等待 | “改字→上字幕→等4秒→下字幕”这类自动化序列 |
| VB.NET 脚本 | API.Function("SetText", Input:="Scorebug", SelectedName:="ScoreHome.Text", Value:="21") | 需要循环、条件判断、读文件/接口的复杂逻辑 |
24 个函数分组总览
| 分组 | 函数 | 用途一句话 |
|---|---|---|
| 文字 | SetText | 改文本内容（最常用，支持 %0A 换行） |
| 文字 | SetTextColour | 改文字颜色，#RRGGBB 六位 |
| 文字 | SetColor v25+ | 改任意标题元素颜色，#AARRGGBB 八位（含透明度） |
| 文字 | SetTextVisible / On / Off | 切换 / 显示 / 隐藏文本 |
| 图片 | SetImage | 按文件路径换图片，留空清除 |
| 图片 | SetImageVisible / On / Off | 切换 / 显示 / 隐藏图片 |
| 倒计时 | SetCountdown | 设置倒计时时长 hh:mm:ss |
| 倒计时 | ChangeCountdown | 直接修改当前显示的时间值 |
| 倒计时 | AdjustCountdown | 在当前时间上加 / 减秒数（Value 可负） |
| 倒计时 | StartCountdown · SuspendCountdown · PauseCountdown · StopCountdown | 开始 / 仅暂停 / 暂停↔继续切换 / 停止并归零 |
| 动画预设 | TitleBeginAnimation | 播放 GT 故事板动画（TransitionIn / TransitionOut / 自定义名） |
| 动画预设 | NextTitlePreset · PreviousTitlePreset · SelectTitlePreset | 切换 GT 标题预设 / 多页面（下一个 / 上一个 / 指定序号） |
| 跑马灯 | SetTickerSpeed | 跑马灯滚动速度 1-1000 |
| 批量 | PauseRender · ResumeRender | 批量更新前冻结渲染、更新后恢复，防闪烁/防动画逐个触发 |
一、实战：比分条一次性更新多个字段
需求：进球后，比分条上的主队分、客队分、节次、当前进球球员要同时更新。不要连发 4 个 SetText——观众会看到字段逐个跳变，而且每个字段的 DataChange 动画可能分别播一遍。正确做法是 PauseRender → 批量 SetText → ResumeRender。
HTTP GET（4 条依次请求，可粘进浏览器地址栏测试）
http://127.0.0.1:8088/api/?Function=PauseRender&Input=Scorebug http://127.0.0.1:8088/api/?Function=SetText&Input=Scorebug&SelectedName=ScoreHome.Text&Value=21 http://127.0.0.1:8088/api/?Function=SetText&Input=Scorebug&SelectedName=ScoreAway.Text&Value=18 http://127.0.0.1:8088/api/?Function=SetText&Input=Scorebug&SelectedName=Quarter.Text&Value=Q4 http://127.0.0.1:8088/api/?Function=ResumeRender&Input=Scorebug
Web 脚本（推荐，一次执行，可在 vMix Scripting 里存成“比分更新”脚本）
' 先冻结渲染，再批量更新，最后恢复
Function=PauseRender&Input=Scorebug
Function=SetText&Input=Scorebug&SelectedName=ScoreHome.Text&Value=21
Function=SetText&Input=Scorebug&SelectedName=ScoreAway.Text&Value=18
Function=SetText&Input=Scorebug&SelectedName=Quarter.Text&Value=Q4
Function=SetText&Input=Scorebug&SelectedName=Scorer.Text&Value=7 张三
Function=ResumeRender&Input=Scorebug
VB.NET（循环/数据表驱动时用）
API.Function("PauseRender", Input:="Scorebug")
API.Function("SetText", Input:="Scorebug", SelectedName:="ScoreHome.Text", Value:="21")
API.Function("SetText", Input:="Scorebug", SelectedName:="ScoreAway.Text", Value:="18")
API.Function("ResumeRender", Input:="Scorebug")
原理：PauseRender 期间标题输入暂停渲染，所有修改缓存起来，ResumeRender 时一次性呈现——GT 模板里配置的 DataChangeIn 动画也只会整体播放一次。
二、实战：选手头像 / 队徽换图
SetImage 的 Value 是本机图片的完整路径（vMix 本机执行时），常见格式 JPG/PNG（含透明通道）。图片字段名带 .Source。
' 换上选手头像 http://127.0.0.1:8088/api/?Function=SetImage&Input=NameBar&SelectedName=Photo.Source&Value=C%3A%5Cgraphics%5Cplayers%5C07_zhangsan.png ' 清除图片（Value 留空） http://127.0.0.1:8088/api/?Function=SetImage&Input=NameBar&SelectedName=Photo.Source&Value=
- HTTP URL 中路径的
:写成%3A、\写成%5C（浏览器地址栏手敲时会自动编码；程序里调用请用 encodeURIComponent / UrlEncode）。 - 团队做法：把头像/队徽按选手编号统一命名放一个文件夹，触发脚本时只拼路径，避免手滑选错图。
- 远程控台（Web Controller / 另一台电脑的 Companion）场景下，图片文件必须在运行 vMix 的那台主机路径上。
三、实战：选手入场名单的进 / 出场动画
GT 模板里每个对象都可以在故事板（Storyboard）上编排入场、出场动画。API 用 TitleBeginAnimation 按故事板名称触发，内置常用 TransitionIn（入场）和 TransitionOut（出场）；GT Designer 里自定义的故事板名也可以直接作为 Value。
' ① 先把名字、头像都更新好（冻结→批量→恢复，见场景一） Function=PauseRender&Input=NameBar Function=SetText&Input=NameBar&SelectedName=PlayerName.Text&Value=7 张三 Function=SetImage&Input=NameBar&SelectedName=Photo.Source&Value=C:\graphics\players\07.png Function=ResumeRender&Input=NameBar ' ② 播放入场动画 Function=TitleBeginAnimation&Input=NameBar&Value=TransitionIn ' ③ 停留 5 秒（Web 脚本里的等待，单位毫秒） Sleep 5000 ' ④ 播放出场动画（如果模板里配了 TransitionOut） Function=TitleBeginAnimation&Input=NameBar&Value=TransitionOut
和 Overlay（叠加层）的分工：TitleBeginAnimation 只管“字幕输入内部”对象的故事板动画；把整条字幕搬上/搬下屏幕用的是 Overlay 分类的函数，例如
OverlayInput1In（带转场进叠加层 1）、OverlayInput1Out（转场退出）、OverlayInput1Off（立即硬切关闭）。两者常配合：先 OverlayInput1In 整条上屏，再 TitleBeginAnimation 播内部元素的入场编排。四、实战：比赛倒计时（节间倒计时 / 24 秒进攻时间）
GT 模板里放一个 Countdown（倒计时）对象，下面 7 个函数就是完整的遥控器。先分清四个容易混的动作：
| 需求 | 函数 | 说明 |
|---|---|---|
| 设定时长并准备 | SetCountdown | Value=00:01:30，设成 1 分 30 |
| 开始走时 | StartCountdown | 从当前设定值开始倒数 |
| 裁判哨响暂停 | SuspendCountdown | 只暂停，再按 Start 继续 |
| 一个键暂停/继续 | PauseCountdown | 切换键：暂停↔继续；若已走到底会从头开始 |
| 复位到设定值 | StopCountdown | 停止并重置（不是暂停！） |
| 中途改时间 | ChangeCountdown | 直接把当前值改成 00:00:24 |
| 临时加减几秒 | AdjustCountdown | Value=-5 减 5 秒，50 加 50 秒 |
篮球 24 秒进攻时间的快捷复位
' 一次进攻重新开始：直接改成 24 秒（比 Stop→Set 少一步，且不影响走时状态） http://127.0.0.1:8088/api/?Function=ChangeCountdown&Input=ShotClock&Value=00:00:24 ' 裁判回表 14 秒 http://127.0.0.1:8088/api/?Function=ChangeCountdown&Input=ShotClock&Value=00:00:14
节间 90 秒倒计时标准流程（Web 脚本 / 快捷键序列）
Function=SetCountdown&Input=BreakClock&Value=00:01:30
Function=StartCountdown&Input=BreakClock
Sleep 95000
' 最后 5 秒可配合 SetTextColour 把数字变红（见场景六思路）
易踩坑：StopCountdown 是“停止并归零/复位”，想暂停别用它；想做“单键暂停/继续”用 PauseCountdown，想明确只暂停（由另一个键继续）用 SuspendCountdown。
五、实战：底部跑马灯（Ticker）
GT 模板中的 Ticker 文本对象会自动横向滚动。内容仍用 SetText 更新，速度用 SetTickerSpeed（1-1000，越大越快，典型值 300-700）：
' 更新跑马灯内容（多条信息之间可自行加分隔符） http://127.0.0.1:8088/api/?Function=SetText&Input=Ticker&SelectedName=Ticker.Text&Value=欢迎收看今晚的赛事直播 · 中场休息比分 21:18 · 第三节即将开始 ' 调整滚动速度 http://127.0.0.1:8088/api/?Function=SetTickerSpeed&Input=Ticker&Value=666
建议：比赛中跑马灯更新频繁，把它接到数据源（Excel/CSV / Data Sources）或 VB 脚本定时拼内容，比手动发 API 稳定；更新时同样可以套 PauseRender/ResumeRender 防止跳变。
六、实战：比分 / 文字颜色随队伍切换
| 函数 | 颜色格式 | 能改什么 | 版本 |
|---|---|---|---|
| SetTextColour | #RRGGBB 六位十六进制 | 文本字段的文字颜色 | v24+ |
| SetColor | #AARRGGBB 八位（前两位是透明度 Alpha） | 标题中任意元素的颜色（形状/底条等） | v25+ |
' 主队分数变红（六位 RGB） http://127.0.0.1:8088/api/?Function=SetTextColour&Input=Scorebug&SelectedName=ScoreHome.Text&Value=%23FF0000 ' 把比分底条改成半透明队伍蓝（八位 ARGB：#00=全透明 #FF=不透明，示例约 13% 透明度） http://127.0.0.1:8088/api/?Function=SetColor&Input=Scorebug&SelectedName=Bar.Fill&Value=%2322AA3300
注意：HTTP 中
# 必须编码成 %23，否则会被浏览器当成页面锚点，颜色参数根本发不出去——这是颜色函数最常见的失败原因。七、实战：局点 / 加时 / 发球权标识的显隐
模板里预先放好“局点 SET POINT”“加时 OT”“发球三角”等小标识，比赛中只控制显隐，比临时换文字干净：
' 亮起主队局点标识（图片），灭掉客队的 http://127.0.0.1:8088/api/?Function=SetImageVisibleOn&Input=Scorebug&SelectedName=SetPointHome.Source http://127.0.0.1:8088/api/?Function=SetImageVisibleOff&Input=Scorebug&SelectedName=SetPointAway.Source ' 文本类标识同理 http://127.0.0.1:8088/api/?Function=SetTextVisibleOn&Input=Scorebug&SelectedName=OTBadge.Text ' 一个键开关就用 Toggle 版 http://127.0.0.1:8088/api/?Function=SetTextVisible&Input=Scorebug&SelectedName=OTBadge.Text
八、实战：多页面 GT 字幕预设切换
一个 GT 字幕输入可以保存多个预设（Title Preset）/ 多页面布局（例如同一记分牌的“完整版/精简版/全屏数据版”）。
' 切到第 2 个预设（序号从 1 开始） http://127.0.0.1:8088/api/?Function=SelectTitlePreset&Input=Scorebug&Value=2 ' 下一个 / 上一个预设（可绑到台面两个按键做翻页） http://127.0.0.1:8088/api/?Function=NextTitlePreset&Input=Scorebug http://127.0.0.1:8088/api/?Function=PreviousTitlePreset&Input=Scorebug
函数逐个速查（24 个）
每个函数给出：必填参数、典型 HTTP 调用、使用要点。完整参数表（含 Mix/多通道等边界情况）可回手册查对应函数页。
文字SetText
参数：Input（必填）· SelectedName 或 SelectedIndex（指定文本框，必填）· Value（新文本）
http://127.0.0.1:8088/api/?Function=SetText&Input=Scorebug&SelectedName=ScoreHome.Text&Value=21
' 两行文本：用 %0A 表示换行
...&Value=第一行%0A第二行要点：最高频函数；多字段更新务必套 PauseRender/ResumeRender；Value 里的 & 编码为 %26、# 为 %23、空格为 %20（浏览器地址栏里直接敲空格也能用，程序调用请规范编码）。
文字SetTextColour
参数：Input · SelectedName/Index · Value=#RRGGBB
http://127.0.0.1:8088/api/?Function=SetTextColour&Input=Scorebug&SelectedName=ScoreHome.Text&Value=%23FF0000
要点：只改文字颜色；要改形状/背景条颜色且需要透明度，用 v25+ 的 SetColor。
文字SetColor v25+
参数：Input · SelectedName/SelectedIndex（标题元素）· Value=#AARRGGBB（前两位 Alpha 透明度）
http://127.0.0.1:8088/api/?Function=SetColor&Input=Scorebug&SelectedName=Bar.Fill&Value=%230033AA22
要点：Alpha 段 00=全透明、FF=完全不透明；低版本 vMix 调用会无效。
显隐SetTextVisibleOn / SetTextVisibleOff / SetTextVisible
参数：Input · SelectedName/Index（无 Value）
...Function=SetTextVisibleOn&Input=Scorebug&SelectedName=OTBadge.Text
...Function=SetTextVisibleOff&Input=Scorebug&SelectedName=OTBadge.Text
...Function=SetTextVisible&Input=Scorebug&SelectedName=OTBadge.Text ' 开↔关 切换图片SetImage
参数：Input · SelectedName（图片字段 名.Source）· Value=图片完整路径，留空清除
...Function=SetImage&Input=NameBar&SelectedName=Photo.Source&Value=C%3A%5Cgraphics%5C07.png
要点：路径指向 vMix 主机本地文件；PNG 透明通道可直接用。
显隐SetImageVisibleOn / SetImageVisibleOff / SetImageVisible
参数：Input · SelectedName（名.Source，无 Value）
...Function=SetImageVisibleOn&Input=Scorebug&SelectedName=SetPointHome.Source
倒计时SetCountdown / ChangeCountdown / AdjustCountdown
| 函数 | Value 格式 | 作用 |
|---|---|---|
| SetCountdown | hh:mm:ss，如 00:01:30 | 设定倒计时时长（复位基准） |
| ChangeCountdown | hh:mm:ss | 直接改当前时间显示 |
| AdjustCountdown | 秒数，可负数，如 -5 / 50 | 在当前时间上加减 |
三者都需要 Input 指向含 Countdown 对象的字幕输入。
倒计时StartCountdown / SuspendCountdown / PauseCountdown / StopCountdown
| 函数 | 行为 | 再按一次 |
|---|---|---|
| StartCountdown | 开始（或暂停后继续）倒数 | — |
| SuspendCountdown | 仅暂停 | 仍暂停（用 Start 继续） |
| PauseCountdown | 暂停/继续 切换键 | 继续；若已到点则从头开始 |
| StopCountdown | 停止并重置到设定值 | — |
动画TitleBeginAnimation
参数：Input · Value=故事板名称（内置 TransitionIn / TransitionOut；GT Designer 中的自定义故事板名也可）
...Function=TitleBeginAnimation&Input=NameBar&Value=TransitionIn
要点：改字段内容时自动触发的是 DataChange 类故事板；整条字幕上屏/下屏的转场归 OverlayInput* 函数管，两者不冲突。
预设SelectTitlePreset / NextTitlePreset / PreviousTitlePreset
参数：Input；SelectTitlePreset 另需 Value=预设序号（从 1 开始，示例 1）。Next/Previous 无 Value。
...Function=SelectTitlePreset&Input=Scorebug&Value=2
跑马灯SetTickerSpeed
参数：Input · Value=速度 1-1000（如 666）。内容更新仍用 SetText。
批量PauseRender / ResumeRender
参数：仅 Input，无 Value。必须成对使用：PauseRender 后执行若干 SetText/SetImage/SetColor，最后 ResumeRender 一次性呈现。
切记：PauseRender 之后一定要有 ResumeRender（包括脚本中途出错的情况），否则字幕会一直冻结不更新。VB.NET 里可用 try/finally 保证恢复。
避坑清单（按出错频率排序）
- 特殊字符不编码：HTTP GET 里
#→%23（颜色值最常见）、&→%26（球队名 "A&B"）、空格→%20、换行→%0A、中文→按 UTF-8 百分号编码（编程用 encodeURIComponent；浏览器地址栏直接输中文一般也能用）。 - StopCountdown 当暂停用：它会停止并复位；暂停用 SuspendCountdown / PauseCountdown。
- 颜色位数搞混：SetTextColour 用 6 位
#RRGGBB；SetColor（v25+）用 8 位#AARRGGBB。 - SelectedName 后缀错：文本是
.Text，图片是.Source；字段名来自 GT Designer 的对象 Name，不是图层序号。 - 批量改字闪烁：连续多个字段更新不加 PauseRender/ResumeRender，会逐个跳变并多次触发 DataChange 动画。
- PauseRender 忘了恢复：字幕会“卡死”不更新，手动补一个 ResumeRender 即可救回。
- 用输入编号做正式脚本：增删输入后编号会变，正式工程用输入名称或 GUID。
- 路径写在控台电脑上：SetImage 读的是 vMix 主机的文件系统，远程控制时图片要放在主机上或用主机能访问的网络路径。
调试与外部联动
- 最快联调：把 HTTP URL 直接粘进浏览器地址栏回车，成功返回 vMix XML 页面；出错返回 500。
- 查字段名和当前值：访问
http://127.0.0.1:8088/api/看 XML，Title 输入下列出全部 text 元素的 index/name/内容。 - 自动化序列：用 Web 脚本的
Sleep 毫秒数把“改字 → 上叠加层 → 停留 → 下叠加层”写成一段；需要条件/循环用 VB.NET。 - 硬件面板：Bitfocus Companion / Stream Deck / MIDI 快捷键里，Key/Action 填函数名（如 SetText），参数栏分别填 Input、SelectedName、Value，与 HTTP 参数一一对应。
- 动态数据：配合 Data Sources（Excel/CSV、Google Sheets）或 VB 脚本定时 SetText，可做实时榜单、对阵表；动态输入/值还能用 SetDynamicInput1-4、SetDynamicValue1-4 复用。