被试屏只显示图片或视频；应用保持前台并用 Windows Gaze API 记录组合注视点。播放素材时会自动隐藏圆环、蓝点和状态栏。
本阶段不能：其它软件在前台时继续采集、可靠区分左右眼眨眼。4C 只跟踪安装并校准的那一块屏。
基于 Microsoft 官方示例二次开发：
- Windows 10（16299+）或 Windows 11，已连接并校准 Tobii Eye Tracker 4C
- Visual Studio 2019/2022，安装工作负载 「通用 Windows 平台开发」
- 解决方案配置：Debug | x64（发布用 Release | x64）
- Windows SDK：10.0.22621.0
Windows 11 请使用 Tobii Experience（Beta），并完成 Display Setup 与校准。
- 用 Visual Studio 打开
gazeinput.sln - 工具栏配置选 Debug，平台选 x64（不要用 Any CPU / x86）
- 连接 4C，确认 Tobii 软件里该屏幕已校准
- 按 F5（或点「启动」）。VS 会部署 UWP 包并启动
gazeinput.exe - 应用进入全屏。第一次应能看到顶部调试栏，
State:为 Ready 才表示眼动仪可用
若 F5 提示包已安装/版本冲突：开始菜单卸载旧的 gazeinput，再 F5。
任选一种即可：
| 操作 | 说明 |
|---|---|
| VS 里点 停止调试 或 Shift+F5 | 结束调试并关掉应用 |
| Alt+F4 / 关闭应用窗口 | 直接退出；若正在记录，挂起时会尝试收尾，但正式实验请先 gazeinput.exe end |
| 任务栏右键应用 → 关闭窗口 | 同上 |
调试时不要只把窗口最小化：UWP 可能被暂停，注视采集会停。
F5 成功部署后，系统会注册执行别名 gazeinput.exe。之后在 新开的 PowerShell / cmd 里才能找到它。如果提示不是内部或外部命令：
- 确认应用仍在运行（或至少已成功部署过一次）
- 关掉并重开终端
Get-Command gazeinput.exe
UWP 别名不会把程序内部日志打印到你敲命令的那个终端。命令是否成功请看应用调试栏，或看 command.log。
命令行读取图片/视频、以及把 CSV 写到你指定的文件夹，都需要文件系统权限。
Windows 11
- 打开 设置 → 隐私和安全性 → 文件系统 （英文：Settings → Privacy & security → File system）
- 打开「允许应用访问你的文件系统」
- 在下方应用列表里找到 gazeinput，打开开关
Windows 10
- 设置 → 隐私 → 文件系统
- 允许应用访问文件系统，并打开 gazeinput
改完权限后，如仍无法打开素材或写入 --out 目录，把应用关掉再 F5 一次。
另外请保持 4C 所在屏幕的校准有效。应用窗口必须在这块屏上并保持前台。
应用必须已用 F5 启动并保持前台。操作员命令请在 第二块屏 的终端发送；只有一块屏时用 run --list，避免 Alt-Tab 切走窗口。
使用示例：
gazeinput.exe start --session S001 --out "D:\gaze-data"
gazeinput.exe show --image "C:\stim\img01.jpg" --id img01 --ms 5000
gazeinput.exe show --video "C:\stim\clip01.mp4" --id clip01
gazeinput.exe mark --label question_1
gazeinput.exe hide
gazeinput.exe debug on
gazeinput.exe debug off
gazeinput.exe end --exit
gazeinput.exe run --list "C:\work\windows-topic-specific-samples-uwp-gazeinput-basic\gazeinput2\scripts\example-playlist.txt"| 命令 | 作用 |
|---|---|
start [--session ID] [--out 文件夹] |
开始记录，边采边写 CSV |
show --image PATH [--id ID] [--ms N] |
全屏显示图片；--ms 毫秒后自动结束该素材 |
show --video PATH [--id ID] [--ms N] |
全屏播放视频；播完或 --ms 到时结束 |
mark [--label TEXT] |
在记录中插入一行标记 |
hide |
黑屏并结束当前素材 |
debug on|off |
显示/隐藏状态栏、圆环、注视蓝点 |
end [--exit] |
结束记录并关闭 CSV；加 --exit 后自动退出全屏应用 |
run --list PATH |
在应用内顺序执行播放列表，不必中途切窗口 |
show 会自动关掉调试层。窗口内 Ctrl+D 也可切换调试层。
这就是一个普通 UTF-8 文本文件（.txt），一行一条命令，内容和你在 PowerShell 里敲的一样，只是前面不用写 gazeinput.exe。
#开头的行是注释，会被忽略- 空行也会忽略
- 图片行必须带
--ms，否则不会自动切下一张 - 视频行默认播完再执行下一条；也可以加
--ms提前结束 - 路径请改成你电脑上真实存在的文件和文件夹
完整示例（仓库里也有一份：scripts/example-playlist.txt）：
# 实验播放列表：先 start，再按顺序 show，最后 end
# 运行：gazeinput.exe run --list "C:\path\to\session.txt"
start --session S001 --out "C:\work\windows-topic-specific-samples-uwp-gazeinput-basic\output"
# 第一张图，显示 5 秒
show --image "C:\Users\wangyuyuan\Pictures\img01.jpg" --id img01 --ms 5000
# 可选：在时间轴上打一个标记
mark --label after_image
# 一段视频，播完自动进入下一条
show --video "C:\Users\wangyuyuan\Videos\clip01.mp4" --id clip01
# 第二张图，显示 3 秒
show --image "C:\Users\wangyuyuan\Pictures\img02.jpg" --id img02 --ms 3000
end
保存后：
gazeinput.exe run --list "C:\work\windows-topic-specific-samples-uwp-gazeinput-basic\gazeinput2\scripts\example-playlist.txt"相对路径相对于播放列表文件所在目录。建议图片/视频仍写绝对路径，少出错。
这些 ID 不会控制眼动仪硬件，只用来给数据打标签，方便事后用 Excel 筛选、对齐素材。
表示这一整场实验/被试/试次的名字。
- 会出现在输出文件名里，例如
GazeLog_S001_20260827_090803.csv - 也会写进 CSV 每一行的
session_id列 - 不写的话，程序会用当前 UTC 时间生成一个 ID
建议用能看懂的名字，例如 S001、subj03_pretest。同一天多场实验务必换不同 session，否则仍会生成不同文件（文件名带时间），但分析时不好按场次过滤。
gazeinput.exe start --session subj03_run1 --out "D:\gaze-data"表示当前正在看的那一张图或那一段视频的名字。
- 写入 CSV 的
stimulus_id列；该素材播放期间的每一行注视数据都带这个值 - 不写的话，默认用文件名去掉后缀，例如
C:\stim\img01.jpg→img01
分析「被试在图 A 上看了哪里」时，就是按 stimulus_id 筛选。请和素材清单里的编号保持一致，不要只靠文件名。
gazeinput.exe show --image "C:\stim\neutral_01.jpg" --id N01 --ms 5000
gazeinput.exe show --video "C:\stim\clip_a.mp4" --id V_Amark --label 是另外一种标签：在时间轴上插一个事件点（例如答题开始），不是素材编号。
格式为 CSV（逗号分隔）。Excel、WPS、记事本都可以直接打开。
gazeinput.exe start --session S001 --out "D:\gaze-data"--out / --output / -o 等价，必须是文件夹的绝对路径。父目录已经存在时，会自动创建最后一级子文件夹。不写 --out 时，仍写到 UWP 默认目录：
%LOCALAPPDATA%\Packages\5cb93004-0d8c-4655-884a-a144e484d785_8wekyb3d8bbwe\LocalState
UWP 不能在任意位置新建整条路径（例如从 C:\ 根目录一层层创建）。更稳妥的选择：
| 路径 | 是否建议 |
|---|---|
文档、桌面、下载、图片，例如 %USERPROFILE%\Documents\gaze-data |
推荐 |
已存在的工程目录或其子目录，例如 C:\work\...\output |
可以，父文件夹必须已存在 |
D:\gaze-data 等非系统盘 |
可以 |
C:\Windows、C:\Program Files、C:\ 根目录 |
不行 |
指定 --out 后，注视 CSV 会出现在该文件夹，例如：
D:\gaze-data\GazeLog_S001_20260827_090803.csv
command.log 和 session_status.txt 仍在上面的 LocalState 里，用来查命令是否成功、这次写到了哪个路径。
Get-Content "$env:LOCALAPPDATA\Packages\5cb93004-0d8c-4655-884a-a144e484d785_8wekyb3d8bbwe\LocalState\session_status.txt"
Get-Content "$env:LOCALAPPDATA\Packages\5cb93004-0d8c-4655-884a-a144e484d785_8wekyb3d8bbwe\LocalState\command.log" -Tail 20CSV 第一行是表头。valid=0 表示该采样没有注视点（丢跟踪），不要当成眨眼。坐标是相对本应用窗口的 DIP，不是系统全局像素。
Visual Studio 选 Release | x64，右键项目 → 发布 / Create App Packages（Sideload）。安装后同样用 gazeinput.exe。
msbuild .\gazeinput.sln /p:Configuration=Debug /p:Platform=x64 /p:AppxPackageSigningEnabled=false界面可以不干扰被试，但保存眼动数据用于行为分析属于 Tobii Analytical Use，且必须告知并取得同意。不要做隐蔽采集。