# 蓝牙录音设备接入技术方案

## 一、概述

本文档详细说明如何在uni-app项目中实现蓝牙录音设备的连接、数据接收和文件处理功能。

## 二、技术架构

### 2.1 技术栈
- **框架**: uni-app (Vue 3)
- **平台**: APP端 (Android/iOS)
- **蓝牙协议**: BLE (低功耗蓝牙) / 经典蓝牙
- **音频格式**: PCM (可根据设备调整)

### 2.2 核心组件

1. **蓝牙工具类** (`common/bluetooth.js`)
   - 蓝牙适配器管理
   - 设备搜索与连接
   - 数据接收与处理
   - 连接状态管理

2. **蓝牙录音页面** (`pages/bluetooth-recorder/bluetooth-recorder.vue`)
   - 设备搜索界面
   - 连接管理界面
   - 数据监控界面
   - 文件保存与上传

## 三、实现步骤

### 步骤1: 配置权限

在 `manifest.json` 中添加蓝牙相关权限：

**Android权限**:
```xml
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
```

**iOS权限**:
在 `manifest.json` 的 `app-plus` -> `ios` 配置中添加：
```json
"privacyDescription": {
  "NSBluetoothAlwaysUsageDescription": "需要蓝牙权限以连接录音设备",
  "NSBluetoothPeripheralUsageDescription": "需要蓝牙权限以连接录音设备",
  "NSLocationWhenInUseUsageDescription": "需要位置权限以搜索蓝牙设备"
}
```

### 步骤2: 初始化蓝牙适配器

```javascript
import bluetoothRecorder from '@/common/bluetooth.js'

// 初始化蓝牙适配器
await bluetoothRecorder.initBluetoothAdapter()
```

### 步骤3: 搜索蓝牙设备

```javascript
// 开始搜索
await bluetoothRecorder.startScan({
  allowDuplicatesKey: false,  // 不允许重复上报
  interval: 0                 // 上报间隔
})

// 监听设备发现
bluetoothRecorder.onDeviceFound = (device) => {
  console.log('发现设备:', device.name, device.deviceId)
}
```

### 步骤4: 连接蓝牙设备

```javascript
// 连接设备
await bluetoothRecorder.connectDevice(deviceId)

// 监听连接状态
bluetoothRecorder.onDeviceConnected = (deviceId) => {
  console.log('设备连接成功:', deviceId)
}

bluetoothRecorder.onDeviceDisconnected = (deviceId) => {
  console.log('设备断开:', deviceId)
}
```

### 步骤5: 接收音频数据

连接成功后，系统会自动：
1. 获取设备的服务列表
2. 查找可通知的特征值
3. 启用特征值通知
4. 监听数据变化

```javascript
// 监听音频数据接收
bluetoothRecorder.onAudioDataReceived = (data) => {
  // data.data: Base64编码的音频数据
  // data.arrayBuffer: ArrayBuffer格式的音频数据
  // data.timestamp: 时间戳
  
  console.log('收到音频数据:', data)
}
```

### 步骤6: 处理音频数据

#### 6.1 保存到本地文件

```javascript
// 获取所有音频数据
const audioData = bluetoothRecorder.mergeAudioData()

// 转换为ArrayBuffer
const arrayBuffer = uni.base64ToArrayBuffer(audioData)

// 保存到文件系统
const fs = uni.getFileSystemManager()
const filePath = `${uni.env.USER_DATA_PATH}/recording.pcm`

fs.writeFile({
  filePath: filePath,
  data: arrayBuffer,
  success: () => {
    console.log('文件保存成功:', filePath)
  }
})
```

#### 6.2 上传到服务器

```javascript
// 准备上传数据
const audioData = bluetoothRecorder.mergeAudioData()
const arrayBuffer = uni.base64ToArrayBuffer(audioData)

// 上传到服务器
const formData = {
  audio: arrayBuffer,
  fileName: 'recording.pcm',
  deviceId: deviceId
}

const res = await post('/api/audioManagement/uploadBluetoothAudio', formData, {
  header: {
    'Content-Type': 'multipart/form-data'
  }
})
```

## 四、蓝牙设备协议说明

### 4.1 服务UUID和特征值

不同的蓝牙录音设备可能使用不同的服务UUID和特征值。常见的有：

**标准音频服务**:
- 服务UUID: `0000110a-0000-1000-8000-00805f9b34fb` (A2DP)
- 特征值UUID: 设备特定

**自定义服务**:
- 需要根据设备厂商提供的文档配置

### 4.2 数据格式

蓝牙设备传输的音频数据通常是：
- **格式**: PCM (脉冲编码调制)
- **采样率**: 8kHz, 16kHz, 44.1kHz 等
- **位深**: 16bit
- **声道**: 单声道或立体声

### 4.3 数据包处理

蓝牙BLE设备通常以数据包形式传输音频：
- 每个数据包大小: 20字节 (BLE限制)
- 需要将多个数据包合并为完整的音频流
- 可能需要处理数据包丢失和重排序

## 五、使用示例

### 5.1 完整使用流程

```javascript
import bluetoothRecorder from '@/common/bluetooth.js'

// 1. 初始化
await bluetoothRecorder.initBluetoothAdapter()

// 2. 搜索设备
bluetoothRecorder.onDeviceFound = (device) => {
  console.log('发现设备:', device)
}

await bluetoothRecorder.startScan()

// 3. 连接设备
await bluetoothRecorder.connectDevice(deviceId)

// 4. 接收数据
bluetoothRecorder.onAudioDataReceived = (data) => {
  // 处理音频数据
  console.log('收到数据:', data)
}

// 5. 保存数据
const audioData = bluetoothRecorder.mergeAudioData()
// ... 保存或上传逻辑

// 6. 断开连接
await bluetoothRecorder.disconnectDevice()

// 7. 清理资源
await bluetoothRecorder.closeBluetoothAdapter()
```

### 5.2 页面集成

在需要使用的页面中：

```vue
<template>
  <view>
    <button @click="connectBluetooth">连接蓝牙设备</button>
    <button @click="saveAudio">保存录音</button>
  </view>
</template>

<script>
import bluetoothRecorder from '@/common/bluetooth.js'

export default {
  methods: {
    async connectBluetooth() {
      await bluetoothRecorder.initBluetoothAdapter()
      await bluetoothRecorder.startScan()
    },
    
    async saveAudio() {
      const audioData = bluetoothRecorder.mergeAudioData()
      // 保存逻辑
    }
  }
}
</script>
```

## 六、注意事项

### 6.1 权限要求

1. **Android 12+**: 需要 `BLUETOOTH_SCAN` 和 `BLUETOOTH_CONNECT` 权限
2. **位置权限**: 搜索蓝牙设备需要位置权限（Android要求）
3. **运行时权限**: 需要在代码中动态申请权限

### 6.2 平台差异

1. **iOS**: 
   - 需要用户明确授权蓝牙权限
   - 后台运行限制更严格
   - 某些蓝牙功能可能受限

2. **Android**:
   - 权限管理更复杂
   - 不同版本API差异较大
   - 需要处理权限动态申请

### 6.3 性能优化

1. **数据缓冲**: 使用缓冲区避免频繁处理小数据包
2. **内存管理**: 及时清理不需要的数据，避免内存溢出
3. **连接管理**: 合理管理连接状态，避免资源泄漏

### 6.4 错误处理

常见错误及处理：

1. **蓝牙未开启**: 提示用户开启蓝牙
2. **权限被拒绝**: 引导用户到设置页面授权
3. **设备连接失败**: 检查设备是否在范围内，是否已被其他设备连接
4. **数据接收中断**: 实现重连机制

## 七、调试方法

### 7.1 日志输出

工具类已内置详细日志，可通过控制台查看：
- 设备搜索日志
- 连接状态日志
- 数据接收日志
- 错误日志

### 7.2 测试步骤

1. 确保手机蓝牙已开启
2. 确保蓝牙录音设备已开启并处于可发现状态
3. 运行应用，点击"开始搜索"
4. 等待发现设备后，点击设备进行连接
5. 连接成功后，观察数据接收情况
6. 测试保存和上传功能

## 八、扩展功能

### 8.1 音频格式转换

如果需要转换为其他格式（如MP3、WAV），可以使用：
- 前端转换库（如 lamejs）
- 后端转换服务

### 8.2 实时播放

可以结合 `uni.createInnerAudioContext()` 实现实时播放接收到的音频数据。

### 8.3 数据加密

如果需要对传输的音频数据进行加密，可以在接收数据后进行解密处理。

## 九、常见问题

### Q1: 搜索不到设备？
- 检查蓝牙是否开启
- 检查位置权限是否授权
- 检查设备是否处于可发现状态
- 尝试重启蓝牙

### Q2: 连接失败？
- 检查设备是否在范围内
- 检查设备是否已被其他应用连接
- 检查设备是否支持BLE
- 查看错误日志获取详细信息

### Q3: 接收不到数据？
- 检查是否已启用特征值通知
- 检查服务UUID和特征值UUID是否正确
- 检查设备是否正在发送数据
- 查看设备文档确认数据格式

### Q4: 数据不完整？
- 检查数据包是否丢失
- 实现数据包校验和重传机制
- 检查缓冲区是否溢出

## 十、参考资料

- [uni-app 蓝牙API文档](https://uniapp.dcloud.net.cn/api/system/bluetooth.html)
- [Android 蓝牙开发指南](https://developer.android.com/guide/topics/connectivity/bluetooth)
- [iOS Core Bluetooth 文档](https://developer.apple.com/documentation/corebluetooth)

## 十一、更新日志

- **2024-01-XX**: 初始版本，实现基础蓝牙连接和数据接收功能
- 后续根据实际使用情况进行优化和扩展