> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elata.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# 在现有浏览器应用中添加 EEG

> 逐步将 Elata EEG 处理接入浏览器应用，并验证 WASM 路径可以正常工作。

如果你已经有一个浏览器应用，并希望按推荐方式集成 EEG，请阅读本页。

如果你想从脚手架开始，请参阅[快速开始](/cn/sdk/tutorials/first-app)。如果你只想先了解包模型，请参阅[在浏览器应用中使用 EEG](/cn/sdk/guides/eeg-browser)。

本教程展示将 `@elata-biosciences/eeg-web` 添加到现有浏览器应用的推荐路径。

在典型的 Elata 使用路径中，EEG 是**可选的**。除非你的产品需要脑电信号功能，**摄像头 rPPG** 通常才是主要的集成方式。

当你的应用需要在浏览器中使用 EEG 分析 API 时，请按本教程操作。如果还需要实时头带传输，完成本教程后再添加 `@elata-biosciences/eeg-web-ble`。

## 你将构建什么

你将：

1. 安装 `@elata-biosciences/eeg-web`
2. 初始化 EEG WASM 运行时
3. 运行一个简单的分析调用
4. 验证你的应用可以提供打包的 WASM 资源

## 第 1 步：安装包

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add @elata-biosciences/eeg-web
  ```

  ```bash npm theme={null}
  npm install @elata-biosciences/eeg-web
  ```
</CodeGroup>

## 第 2 步：创建一个小型 EEG 模块

在应用中创建一个小模块，让集成保持隔离且易于测试（例如 `src/eeg.ts`）：

```ts eeg.ts theme={null}
import { initEegWasm, band_powers } from "@elata-biosciences/eeg-web";

let eegInitPromise: Promise<void> | null = null;

async function ensureEegReady() {
  if (!eegInitPromise) {
    eegInitPromise = initEegWasm();
  }
  await eegInitPromise;
}

export async function analyzeExampleEeg() {
  await ensureEegReady();

  const eegData = new Float32Array([0.2, 0.5, 0.1, -0.3, -0.4, 0.1, 0.2, 0.6]);
  const powers = band_powers(eegData, 256);

  return powers;
}
```

为什么这样组织：

* 使用分析函数之前应先运行 `initEegWasm()`
* 模块级的 Promise 可以避免重复初始化，包括并发调用的情况
* 放在一个文件中，之后更容易换成真实样本

## 第 3 步：从界面中调用

例如，在组件或入口文件中：

```ts theme={null}
import { analyzeExampleEeg } from "./eeg";

const powers = await analyzeExampleEeg();
console.log("alpha", powers.alpha);
console.log("beta", powers.beta);
```

这一阶段你还没有使用真实头带。你只是在证明浏览器应用可以加载运行时并正确执行 EEG 函数。

## 第 4 步：验证 WASM 资源路径

在开发环境中运行应用，确认模块初始化时没有错误。

如果 `initEegWasm()` 失败，最可能的原因是你的打包工具或部署没有正确提供打包的 `wasm/` 资源。

在添加更多产品逻辑之前，这是首先要解决的问题。

如果你使用 Vite，两种常见的修复方式是：

1. 添加 `vite-plugin-wasm` 和 `vite-plugin-top-level-await`，然后继续使用 `await initEegWasm()`
2. 直接导入 WASM 资源 URL，并传给 `initEegWasm(wasmUrl)`

关于这两种修复方式的更多信息，参见[故障排查](/cn/sdk/operations/troubleshooting)。

如果仍然无法解决，请先把你的应用与脚手架生成的 `eeg-demo` 应用进行对比，再判断是不是包本身有问题。

## 第 5 步：用真实应用数据替换示例数据

示例调用正常后，把占位数组换成应用中真实的 EEG 样本缓冲区。

常见的模式是：

1. 接收或加载 EEG 样本
2. 将它们规范化为类型化数组
3. 调用 Elata 分析函数
4. 把结果映射到应用状态、反馈、评分或可视化中

最后一步就是你的产品行为所在。

## 何时添加 `eeg-web-ble`

当你需要从受支持的 Muse 兼容头带获取实时浏览器传输时，添加 `@elata-biosciences/eeg-web-ble`。

如果基本的 EEG 运行时还不能工作，不要从那里开始。先让 WASM 加载正常，再添加传输层。

## 常见问题

* `initEegWasm()` 抛出错误：你的应用可能没有正确加载打包的 `wasm/` 资源
* 你期望设备发现：`eeg-web` 本身不负责蓝牙传输
* 你在从零开始评估 SDK：请从[构建你的第一个 Elata 应用](/cn/sdk/tutorials/first-app)开始，而不是手动设置

## 下一步

<CardGroup cols={3}>
  <Card title="添加 Web Bluetooth" icon="bluetooth" href="/cn/sdk/tutorials/eeg-ble-live-stream">
    通过 BLE 输出 Muse EEG 数据
  </Card>

  <Card title="eeg-web 参考" icon="brain" href="/cn/sdk/eeg-web/getting-started">
    包 API 和导出
  </Card>

  <Card title="在浏览器中使用 EEG" icon="book-open" href="/cn/sdk/guides/eeg-browser">
    集成概览
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.