软件逻辑概览

RealityTap Studio 的核心逻辑是：用项目承载素材与触觉文件，用触觉编辑器生成或编辑事件，再根据线性马达配置和采样率输出到触觉套件或导出为 RTP 文件。硬件相关能力通过工具页和套件管理器完成。

核心对象	含义	与其他对象的关系
项目	保存一个触觉作品的工程容器。	项目内包含一个或多个 .he 触觉文件，并可能关联音频或视频素材。
.he 触觉文件	可编辑的触觉事件文件。	在编辑器中选择、播放、重命名、删除，或导出为 RTP。
触觉事件	触觉时间轴上的事件。	分为瞬态事件和连续事件；连续事件可包含曲线点。
线性马达配置	线性马达或触觉算法配置。	决定播放和导出时的线性马达参数，既有本地配置也有套件端配置。
触觉套件	蓝牙触觉硬件。	连接后可播放效果、设为默认设备、管理线性马达配置并升级固件。
RTP/bin 文件	可直接播放的触觉波形数据。	由 .he 导出，或在 RTP 播放工具中选择并播放。

项目 → .he 触觉文件 → 事件时间轴 → 马达配置 + 采样率 → 播放 / 导出 RTP → 触觉套件

重要说明

按钮名称和流程以实际安装版本为准；涉及固件升级、寄存器参数和硬件配置时，请优先遵循项目团队发布的正式硬件规范。

02

快速上手流程

创建或打开项目

1 在首页选择新建项目，从音频或触觉文件创建新项目；也可选择打开项目打开本地项目。
2 如果拿到的是归档包，选择导入项目导入。
3 想快速体验，可在示例项目中选择项目，下载完成后打开。

连接并设置默认套件

1 打开触觉套件管理，或使用 Ctrl+D 打开/关闭套件管理器。
2 点击扫描套件按钮扫描附近设备。
3 在目标设备卡片上点击连接。
4 如果有多个设备，点击设为默认，把常用设备设为默认输出。

编辑、播放和导出

1 在触觉编辑器左侧选择 .he 文件。
2 选择马达配置和采样率。
3 在时间轴上新增或选中事件，调节强度、频率、时长等参数。
4 点击播放在触觉套件上播放振动效果；需要停止时点击停止。
5 右键 .he 文件，选择导出为 RTP，导出可播放波形。

进入编辑器播放与导出确认左侧 .he 文件、马达配置、采样率、时间轴和播放控件。

03

首页与项目管理

首页围绕项目的创建、打开、导入和示例项目体验组织。顶部主导航包含项目、工具、资源、管理等入口。

区域	可见功能	使用说明
顶部入口	新建项目 / 打开项目 / 导入项目	新建项目、打开本地工程、从归档文件导入项目。
最近项目	最近项目卡片	显示项目名、路径、日期和触觉文件数量，便于快速继续工作。
示例项目	示例项目卡片	显示作者、触觉数量、文件大小、下载次数、标签与版本。已下载表示项目已经下载到本地。
顶部状态栏	连接状态、语言、账号/头像	可观察当前是否连接硬件、当前语言和登录状态。

正式项目优先使用新建项目或打开项目；教学演示优先使用示例项目，因为示例项目通常包含完整素材和触觉文件。

04

触觉编辑器

触觉编辑器是主要工作区。左侧是触觉文件列表，中间是时间轴曲线，顶部是编辑器状态和播放控制，右侧会在选中事件或曲线点后显示属性面板。

界面区域	作用	关键操作
触觉文件列表	管理当前项目中的 .he 文件。	选择文件、刷新列表、右键打开文件菜单。
马达配置	选择线性马达或算法配置。	从下拉框选择 LRA 0809、LRA 8282 等配置。
采样率	选择采样率和精度。	示例值包括 12KHz - 中等精度。
时间轴/曲线区	显示并编辑触觉事件。	点击或拖拽事件，右键或点击位置可新增事件。
播放区	控制当前触觉文件播放。	点击播放，播放中可查看当前时间，点击停止结束播放。
属性面板	编辑选中事件参数。	调整开始时间、强度、频率、时长和曲线点参数。

新增触觉事件

在时间轴上选定位置后，界面会显示新增事件菜单，并提示该位置附近的可用时间空间。可选择瞬态事件或连续事件。

瞬态事件适合短促、脉冲式触觉，例如点击、撞击、节拍。
连续事件适合一段持续变化的触觉，例如拖拽、震动、加速、环境振动。
新增事件前注意可用时间空间，避免事件之间互相重叠或过密。

编辑连续事件

选择连续事件后，右侧事件属性面板显示连续事件。可调参数包括开始时间、全局强度、全局频率和持续时间。

连续事件属性面板右上角浮层对应选中的连续事件，可调整开始时间、强度、频率和时长。

参数	作用	调整建议
开始时间	事件起始时间。	用于与音频或视频节奏对齐。
全局强度	事件整体强度。	先调全局强度，再微调曲线点强度。
全局频率	事件整体频率。	应匹配当前线性马达配置和目标触觉风格。
持续时间	事件持续时间。	控制连续事件覆盖的时间范围。

编辑曲线点

点击连续事件中的白色曲线点后，面板会显示选中的曲线点。可调整曲线点相对强度和曲线点相对频率，并查看计算后的绝对强度和频率。

点相对强度用于塑造包络形状。数值越高，该点处触觉越强。
点相对频率用于给连续事件增加频率变化。
界面提示可按住 Ctrl 并垂直拖拽来调整频率。
黑色提示框显示鼠标当前位置对应的时间和振幅，适合精细定位。

05

从音频生成触觉事件

从音频生成触觉事件功能用于根据音频自动生成触觉事件。它适合快速生成初稿，但自动结果仅作为参考，最终效果必须在真实触觉套件上测试并调整。

参数	示例值	作用
预设模式	低密度	选择生成策略。低密度通常减少事件数量，适合作为清爽初稿。
启用强度增益	未勾选	启用后可能根据音频能量增强强度。
瞬态灵敏度	0.3	瞬态检测灵敏度，提高后会更容易生成短促事件。
最小时长	200 ms	事件最小时长，避免生成过短的连续事件。
包络分辨率	20 Hz	音频包络解析频率，影响变化细节。
事件间隔	50 ms	事件之间的最小间隔，避免生成过密。

播放、预览与导出

在编辑器中播放

连接默认触觉套件后，在编辑器顶部点击播放即可播放当前 .he 文件。播放中界面显示当前播放时间和总时长，并可显示视频预览浮窗。

播放前确认顶部状态为已连接，且目标套件已设为默认设备。
如果播放时需要对齐画面节奏，开启视频预览并观察当前时间。
调试过程中建议先用较低强度播放，再逐步提高。

触觉文件右键操作

触觉文件列表中的 .he 文件支持右键菜单。

菜单项	用途	注意事项
播放效果	直接播放当前触觉文件。	需要连接可用套件。
导出为 RTP	导出为 RTP/bin 波形文件。	导出前确认马达配置和采样率设置正确。
重命名文件	重命名触觉文件。	建议使用能表达场景或片段的名称。
删除触觉文件	删除触觉文件。	删除前确认已有备份或不再需要。

07

工具页与 RTP 播放

工具页提供独立工具入口。最近使用工具显示近期使用的工具，全部工具显示全部工具卡片。

工具	用途	典型场景
RTP 播放	实时播放 RTP 波形数据。	验证导出的 RTP/bin 文件是否能正确驱动套件。
本地马达配置管理器	管理本地线性马达配置文件。	新增或更新编辑器可选择的线性马达配置。
触觉套件马达管理器	管理远端套件上的线性马达配置。	给硬件写入或导出线性马达参数。
触觉套件升级	升级套件固件。	获取新功能、修复问题或统一设备版本。

使用 RTP 播放

1 进入工具页，打开 RTP 播放。
2 在文件选择区域点击浏览，选择 RTP/bin 文件。
3 确认文件状态为已就绪。
4 选择采样率，例如 24000 Hz。
5 连接触觉套件后点击播放；需要停止时点击停止。

常见限制

RTP 播放提示需先连接触觉套件时，说明未连接套件，无法向硬件输出。播放前先完成设备连接。

08

触觉套件设备管理

套件管理器用于发现和控制蓝牙触觉设备。每个设备卡片展示设备名称、连接状态、设备 ID、频率、芯片系列和固件。

操作	按钮/状态	说明
扫描设备	扫描套件	刷新附近可发现套件。
连接设备	连接	连接目标套件。成功后状态变为已连接。
断开设备	断开连接	结束与当前套件的连接。
设置默认设备	设为默认 / 默认	默认设备会成为编辑器和播放工具的主要输出对象。
移除离线设备	移除	从列表中移除不再使用的离线设备记录。
查看固件	固件字段	用于判断是否需要升级。

默认设备规则

如果同时连接多个套件，请明确设置默认设备。否则播放、导出验证或远端配置操作可能作用到非预期设备。

09

线性马达配置管理

本地马达配置管理器

本地线性马达配置管理器展示可供编辑器选择的配置。下图把管理入口和编辑器下拉框放在同一视野中：在 008 中上传或维护的本地配置，会出现在 009 的马达配置下拉框里。默认配置包括 LRA 0809 Normal 170Hz 和 LRA 8282 Normal 170Hz。

008 → 009 先维护本地马达配置，再在编辑器中选择同一套配置。

本地配置列表 → 编辑器马达配置选项

编辑器中切换线性马达配置 — 009 编辑器马达配置下拉框：选择上一步维护的配置

马达配置获取

如需新增或更新马达配置，请联系您的 AWA 销售或商务获取对应配置文件。

触觉套件马达管理器

触觉套件马达管理器管理硬件端配置。左侧选择套件并查看马达配置列表；右侧编辑基本信息和芯片参数。

区域	可见字段	用途
选择触觉套件	AWA-KIT-9581 等设备	选择要管理的目标硬件。
马达配置列表	配置名、F0 范围、启用状态	查看当前设备上的配置，启用表示正在使用。
基本信息	配置名称、额定频率、F0 校准比例	定义配置名称、额定频率和 F0 校准比例。
芯片参数	Reg 0x83、0x84、0x86、0x87、0x88、0x89、0x8a、0x8b	编辑驱动芯片寄存器参数。
导入 / 导出	导入、导出配置	用于备份、迁移或批量应用配置。

硬件参数风险

寄存器和校准值会直接影响硬件输出。没有明确硬件规范或测试计划时，不建议随意修改。

10

固件升级

固件升级流程由套件卡片中的升级图标进入，也可通过工具页打开触觉套件升级，覆盖发现可更新版本、选择固件、发送固件到升级完成的完整链路。

选择固件

1 打开触觉套件升级。
2 在触觉套件选择区中选择目标设备。
3 查看当前固件，确认当前版本。
4 如果有最新在线版本，可点击使用此版本。也可以点击更换固件选择本地固件文件。
5 确认文件名和 SHA256 后点击开始升级。

升级期间界面显示正在发送固件和百分比进度。完成后显示升级成功，并提示触觉套件会在几秒内自动重启以应用新固件。

升级安全要求

升级过程中保持电脑供电、保持套件连接，不要断开蓝牙、关闭软件或拔掉设备。升级完成并重启后，再重新连接并确认固件版本。

11

常见问题与最佳实践

问题/目标	建议处理方式
点击播放无法输出触觉	先确认顶部状态为已连接；在套件管理器中连接设备并设置默认套件；确认马达配置和采样率已选择。
自动生成事件太多	降低瞬态灵敏度，增大事件间隔，或选择低密度预设。
触觉过强或刺耳	先降低事件全局强度，再调整曲线点；确认使用了匹配线性马达的马达配置。
触觉与视频不同步	播放时打开视频预览，参考当前播放时间，调整事件开始时间和曲线点位置。
导出的 RTP 播放不对	回到编辑器确认马达配置、采样率、事件时长和强度；用 RTP 播放工具选择相同采样率验证。
多设备播放到错误套件	在触觉套件管理中重新设置默认设备。
固件升级后设备短暂不可用	等待设备自动重启，重新扫描并连接。
需要迁移线性马达配置	使用触觉套件马达管理器的导出/导入功能备份和导入配置。

总体原则：先连接硬件，再选择正确线性马达配置；先生成粗稿，再手动调关键点；先以低强度播放振动效果，再逐步提高；固件和寄存器参数变更前先备份。

用户操作手册