BFiVRC: 脑波流入VRChat

这是我的bci-workshop分支的BrainFlow实现，它可以发送你大脑的放松和专注指标，以及基于EEG测量中常用频带的功率值，包括头部左侧、右侧和两侧。当你的硬件支持时，还可以提供心率和呼吸的额外支持。

新功能：增加了使用机器学习从你的脑波中读取动作的逻辑。查看model/intent目录中的README.md以获取更多信息。

为什么选择BrainFlow？

BrainFlow库提供了一个与设备无关的统一API，使得我的工作坊分支的这个实现可以适用于所有支持的生物传感器（包括Muse头带）。无需额外软件！

演示

使用说明

将此项目下载到一个文件夹，并记住其路径
安装Python 3.11.5
在开始菜单搜索cmd打开命令提示符
在命令提示符中导航到项目路径
- 示例：cd "C:\Users\<你的用户名>\Documents\GitHub\BrainFlowsIntoVRChat"
执行此命令安装所需依赖：python -m pip install -r requirements.txt
查找你设备的名称或板卡ID：板卡ID页面
打开你的头带
使用你的设备名称或ID运行main.py脚本。例如，使用Muse 2头带运行的命令是：python .\main.py --board-id muse_2_board

OSC头像参数架构

以下是发送到VRChat的各种头像参数。神经反馈得分范围为-1到1（有符号浮点数），0到1（无符号浮点数），较高和较低的值分别对应较高和较低的放松/专注得分。根据你使用的板卡，可能会提供心率、呼吸和电池信息。每个位置的功率带数值也会发送，范围从0到1，平均值为0.2。

要在VRChat中使用这些参数，将参数名称写为路径。例如，要获取左侧Alpha值，参数名称应为：

BFI/PwrBands/Left/Alpha

BFI:
  Info:
    - VersionMajor [整数]
    - VersionMinor [整数]
    - SecondsSinceLastUpdate [浮点数]
    - DeviceConnected [布尔值]
    - BatterySupported [布尔值]
    - BatteryLevel [浮点数]
  NeuroFB:
    - FocusLeft [浮点数]
    - FocusLeftPos [浮点数]
    - FocusRight [浮点数]
    - FocusRightPos [浮点数]
    - FocusAvg [浮点数]
    - FocusAvgPos [浮点数]
    - RelaxLeft [浮点数]
    - RelaxLeftPos [浮点数]
    - RelaxRight [浮点数]
    - RelaxRightPos [浮点数]
    - RelaxAvg [浮点数]
    - RelaxAvgPos [浮点数]
  PwrBands:
    Left:
      - Gamma [浮点数]
      - Beta [浮点数]
      - Alpha [浮点数]
      - Theta [浮点数]
      - Delta [浮点数]
    Right:
      - Gamma [浮点数]
      - Beta [浮点数]
      - Alpha [浮点数]
      - Theta [浮点数]
      - Delta [浮点数]
    Avg:
      - Gamma [浮点数]
      - Beta [浮点数]
      - Alpha [浮点数]
      - Theta [浮点数]
      - Delta [浮点数]
  Addons:
    - Hueshift [浮点数 0-1]
  Biometrics:
    - Supported [布尔值]
    - HeartBeatsPerSecond [浮点数]
    - HeartBeatsPerMinute [整数]
    - OxygenPercent [浮点数]
    - BreathsPerSecond [浮点数]
    - BreathsPerMinute [整数]

弃用

我们建议更新到这个架构。但是，如果你的资产仍在使用旧的参数方案，你可以通过添加--use-old-reporter启动参数来切换到它们。请注意，这将在未来被弃用，并且将正式宣布其终止日期。

从旧参数架构迁移

需要迁移你现有的预制件吗？你可以使用这个表格将现有参数转换为新标准。

旧参数	新参数
osc_focus_left	BFI/NeuroFB/FocusLeft
osc_focus_right	BFI/NeuroFB/FocusRight
osc_focus_avg	BFI/NeuroFB/FocusAvg
osc_relax_left	BFI/NeuroFB/RelaxLeft
osc_relax_right	BFI/NeuroFB/RelaxRight
osc_relax_avg	BFI/NeuroFB/RelaxAvg
osc_heart_bpm	BFI/Biometrics/HeartBeatsPerMinute
osc_heart_bps	BFI/Biometrics/HeartBeatsPerSecond
osc_oxygen_percent	BFI/Biometrics/OxygenPercent
osc_respiration_bpm	BFI/Biometrics/BreathsPerMinute
osc_band_power_left_alpha	BFI/PwrBands/Left/Alpha
osc_band_power_left_beta	BFI/PwrBands/Left/Beta
osc_band_power_left_theta	BFI/PwrBands/Left/Theta
osc_band_power_left_delta	BFI/PwrBands/Left/Delta
osc_band_power_left_gamma	BFI/PwrBands/Left/Gamma
osc_band_power_right_alpha	BFI/PwrBands/Right/Alpha
osc_band_power_right_beta	BFI/PwrBands/Right/Beta
osc_band_power_right_theta	BFI/PwrBands/Right/Theta
osc_band_power_right_delta	BFI/PwrBands/Right/Delta
osc_band_power_right_gamma	BFI/PwrBands/Right/Gamma
osc_band_power_avg_alpha	BFI/PwrBands/Avg/Alpha
osc_band_power_avg_beta	BFI/PwrBands/Avg/Beta
osc_band_power_avg_theta	BFI/PwrBands/Avg/Theta
osc_band_power_avg_delta	BFI/PwrBands/Avg/Delta
osc_band_power_avg_gamma	BFI/PwrBands/Avg/Gamma
osc_battery_lvl	BFI/Info/BatteryLevel
osc_is_connected	BFI/Info/DeviceConnected
osc_time_diff	BFI/Info/SecondsSinceLastUpdate
HueShift	BFI/Addons/HueShift

参数描述

实用工具

这些实用工具参数提供有关您的设备和BFiVRC的基本信息

参数	描述	类型
BFI/Info/VersionMajor	当前参数模式的主版本号	整数
BFI/Info/VersionMinor	当前参数模式的次版本号	整数
BFI/Info/SecondsSinceLastUpdate	BFiVRC数据流的刷新率	浮点数
BFI/Info/DeviceConnected	您的设备与BFiVRC的连接状态	布尔值
BFI/Info/BatterySupported	您的设备是否支持向BFiVRC发送电池状态	布尔值
BFI/Info/BatteryLevel	您设备电池的当前充电状态	浮点数

神经反馈

这些参数是基于您当前的精神状态计算得出的，并使用完整的有符号正负浮点数范围。

参数	描述	类型	范围
BFI/NeuroFB/FocusLeft	左脑从不专注到专注	浮点数	[-1.0, 1.0]
BFI/NeuroFB/FocusRight	右脑从不专注到专注	浮点数	[-1.0, 1.0]
BFI/NeuroFB/FocusAvg	从不专注到专注	浮点数	[-1.0, 1.0]
BFI/NeuroFB/RelaxLeft	左脑从兴奋到放松	浮点数	[-1.0, 1.0]
BFI/NeuroFB/RelaxRight	右脑从兴奋到放松	浮点数	[-1.0, 1.0]
BFI/NeuroFB/RelaxAvg	从兴奋到放松	浮点数	[-1.0, 1.0]

这些是相同的神经反馈分数，重新映射到0到1的正范围，以应对可能需要的情况。

参数	描述	类型	范围
BFI/NeuroFB/FocusLeftPos	左脑从不专注到专注	浮点数	[0.0, 1.0]
BFI/NeuroFB/FocusRightPos	右脑从不专注到专注	浮点数	[0.0, 1.0]
BFI/NeuroFB/FocusAvgPos	从不专注到专注	浮点数	[0.0, 1.0]
BFI/NeuroFB/RelaxLeftPos	左脑从兴奋到放松	浮点数	[0.0, 1.0]
BFI/NeuroFB/RelaxRightPos	右脑从兴奋到放松	浮点数	[0.0, 1.0]
BFI/NeuroFB/RelaxAvgPos	从兴奋到放松	浮点数	[0.0, 1.0]

功率频带

这些参数给出了EEG测量中常用频率带的功率值，按位置测量。要了解每个功率带的含义，请在此处阅读更多信息：什么是脑电波

参数	描述	类型	范围
BFI/PwrBands/Left/Alpha	左脑Alpha波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Right/Alpha	右脑Alpha波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Avg/Alpha	脑电波Alpha波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Left/Beta	左脑Beta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Right/Beta	右脑Beta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Avg/Beta	脑电波Beta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Left/Theta	左脑Theta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Right/Theta	右脑Theta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Avg/Theta	脑电波Theta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Left/Delta	左脑Delta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Right/Delta	右脑Delta波段	浮点数	[0.0, 1.0]
BFI/PwrBands/Avg/Delta	脑电Delta频段	浮点数	[0.0, 1.0]
BFI/PwrBands/Left/Gamma	左脑Gamma频段	浮点数	[0.0, 1.0]
BFI/PwrBands/Right/Gamma	右脑Gamma频段	浮点数	[0.0, 1.0]
BFI/PwrBands/Avg/Gamma	脑电Gamma频段	浮点数	[0.0, 1.0]

附加功能

这些参数是BFiVRC的额外功能

参数	描述	类型	范围
BFI/Addons/HueShift	该参数使用放松/专注的组合来驱动材质特效的单一浮点参数	浮点数	[0.0, 1.0]

生物指标

如果您的硬件支持，这些参数可以读取设备的其他生物指标数据

参数	描述	类型	范围
BFI/Biometrics/Supported	您的硬件是否支持心率和呼吸读数	布尔值	真/假
BFI/Biometrics/HeartBeatsPerSecond	每秒计算的心率	浮点数	[0.0, 无穷大)
BFI/Biometrics/HeartBeatsPerMinute	每分钟计算的心率	整数	[0, 255]
BFI/Biometrics/OxygenPercent	血氧百分比	浮点数	[0.0, 1.0]
BFI/Biometrics/BreathsPerSecond	估计每秒呼吸次数	浮点数	[0.0, 无穷大)
BFI/Biometrics/BreathsPerMinute	估计每分钟呼吸次数	整数	[0, 255]

调试

为了便于调试，添加--debug启动参数。这将使控制台显示所有发送的OSC消息的调试信息，并缩短参数名称，以便在VRChat的OSC调试面板以及其他OSC显示器上可读。

致谢

感谢

@Mitzi_DelverVRC和AartHark在PPG信号工作方面的帮助。
@wordweaver1001进行初步用户测试。
AtriusX帮助创建参数模式。
sync1211增强重连重试逻辑。
Hosomi、Eni、AtriusX、Rantis、DeliciousSalad开发和测试动作分类模型及其集成。
Summer和Programmerboi开发自监督模型。
Scapsters添加使用多个录制会话进行训练数据收集的功能。

故障排除

我的电脑内置蓝牙适配器坏了，想用外接蓝牙适配器。如何将头带连接到外接适配器？
1. 断开要使用的蓝牙适配器
2. 在开始菜单搜索"设备管理器"
3. 找到蓝牙无线电条目，右键点击并禁用
4. 重新插入新的蓝牙适配器
Muse头带能正常连接，但几秒钟后就超时。解决方案：重置头带
1. 关闭头带电源
2. 按住电源按钮直到开机。继续按住直到指示灯变化。
3. 重新连接。
我已经设置好一切并创建了新头像，但它仍然没有反应
- 原因：VRChat存储了你头像的缓存OSC参数，这些参数在头像更新新参数时不会更新
- 解决方案：进入C:\Users\<你的用户名>\AppData\LocalLow\VRChat\VRChat\OSC并删除其下所有文件夹，然后重新加载头像
如果Python似乎无法识别，这是Windows 10/11的问题
- 解决方案：对于步骤5和8，将python替换为py