# create-audio-permission

**Repository Path**: hccwh_admin/create-audio-permission

## Basic Information

- **Project Name**: create-audio-permission
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-12
- **Last Updated**: 2025-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


## 分端版本说明

### 🖥️ PC端版本 (`src/pc/`)
**适用场景**：桌面浏览器环境（Chrome、Firefox、Safari、Edge等）

**特性**：
- 预检测AudioContext状态优化
- 针对桌面浏览器的交互事件优化
- 更完善的键盘事件支持
- 桌面端特有的权限处理策略

**使用方式**：
```javascript
// JavaScript版本
import createAudioPermission from './src/pc/js/create-audio-permission.js'

// TypeScript版本
import createAudioPermission from './src/pc/ts/create-audio-permission.ts'
```

### 📱 移动端版本 (`src/mobile/`)
**适用场景**：移动设备浏览器环境（iOS Safari、Android Chrome等）

**特性**：
- 专门针对移动端的触摸事件优化
- iOS Safari特殊处理逻辑
- 移动端权限管理策略
- 触摸交互事件监听

**使用方式**：
```javascript
// JavaScript版本
import createAudioPermission from './src/mobile/js/create-audio-permission.js'

// TypeScript版本
import createAudioPermission from './src/mobile/ts/create-audio-permission.ts'
```

### 🌐 全端版本 (`src/universal/`)
**适用场景**：需要同时支持PC和移动端的项目

**特性**：
- 自动平台检测
- 动态策略切换
- 完整的跨平台兼容性
- 统一的API接口

**使用方式**：
```javascript
// JavaScript版本
import createAudioPermission from './src/universal/js/create-audio-permission.js'

// TypeScript版本
import createAudioPermission from './src/universal/ts/create-audio-permission.ts'
```

## 版本选择建议

| 项目类型 | 推荐版本 | 理由 |
|---------|---------|------|
| 纯PC端Web应用 | PC端版本 | 体积更小，性能更优，针对性优化 |
| 移动端Web应用/PWA | 移动端版本 | 专门优化移动端体验，处理移动端特殊情况 |
| 响应式Web应用 | 全端版本 | 一套代码适配所有平台，维护成本低 |
| 桌面端Electron应用 | PC端版本 | 针对桌面环境优化 |
| 混合开发应用 | 全端版本 | 统一的API，便于跨平台开发 |

## 功能特性

### 🎵 音频播放权限管理
- **跨平台兼容**：支持PC、iOS Safari、Android Chrome等主流平台
- **智能检测**：自动检测AudioContext状态，优化用户体验
- **用户交互监听**：监听用户交互事件，确保符合浏览器自动播放策略
- **错误处理**：提供详细的错误类型和错误信息

### 🎤 麦克风权限管理
- **安全上下文检查**：确保在HTTPS环境下正常工作
- **权限状态管理**：跟踪权限授权状态，避免重复请求
- **超时处理**：防止权限请求无限等待
- **设备兼容性**：处理不同设备和浏览器的兼容性问题

## 核心类说明

### AudioPermission
统一的音频权限管理类，整合了播放权限和麦克风权限的管理。

### AudioPlaybackPermission
专门处理音频播放权限的类，实现了以下策略：
- **PC端**：预检测AudioContext状态，如果suspended则监听用户交互
- **iOS Safari**：必须在用户交互事件的调用栈中调用resume()，需要50ms延迟确保状态变更
- **Android**：直接在用户交互后检测AudioContext状态

### MicrophonePermission
专门处理麦克风权限的类，支持：
- 安全上下文验证
- 权限状态缓存
- 超时控制
- 详细的错误分类

### AudioPermissionError
自定义错误类，提供了丰富的错误类型：
- `NO_USER_INTERACTION_ERROR`：需要用户交互才能播放音频
- `AUTOPLAY_BLOCKED`：自动播放被浏览器阻止
- `SECURE_CONTEXT_ERROR`：麦克风权限需要在安全上下文中使用
- `PERMISSION_DENIED_PERMANENTLY`：权限已被永久拒绝
- 更多错误类型...

## 使用方法

### 基本用法

```javascript
// 根据项目需求选择对应版本
import createAudioPermission from './src/pc/js/create-audio-permission.js'        // PC端
// import createAudioPermission from './src/mobile/js/create-audio-permission.js'  // 移动端
// import createAudioPermission from './src/universal/js/create-audio-permission.js' // 全端

// 创建音频权限管理实例
const audioPermission = createAudioPermission()

// 请求音频播放权限
try {
  await audioPermission.requestPlaybackPermission()
  console.log('音频播放权限获取成功')
} catch (error) {
  console.error('音频播放权限获取失败:', error.message)
}

// 请求麦克风权限
try {
  await audioPermission.requestMicrophonePermission()
  console.log('麦克风权限获取成功')
} catch (error) {
  console.error('麦克风权限获取失败:', error.message)
}
```

### 错误处理

```javascript
// 只需要导入createAudioPermission即可
import createAudioPermission from './src/universal/js/create-audio-permission.js'

const audioPermission = createAudioPermission()

try {
  await audioPermission.requestPlaybackPermission()
} catch (error) {
  switch (error.name) {
    case 'NoUserInteractionError':
      // 提示用户需要交互
      console.log('请先点击页面任意位置，然后再播放音频')
      break
    case 'AutoplayBlocked':
      // 处理自动播放被阻止
      console.log('浏览器阻止了自动播放，请手动播放')
      break
    case 'PermissionDeniedPermanently':
      // 权限被永久拒绝
      console.log('权限已被拒绝，请在浏览器设置中开启权限')
      break
    case 'SecureContextError':
      // 需要HTTPS环境
      console.log('请在HTTPS环境下使用麦克风功能')
      break
    default:
      // 处理其他错误
      console.error('未知错误:', error.message)
      break
  }
}
```

**常见错误类型**：
- `NoUserInteractionError`：需要用户交互才能播放音频
- `AutoplayBlocked`：自动播放被浏览器阻止
- `AutoplayUnknownError`：未知自动播放错误
- `SecureContextError`：麦克风权限需要在安全上下文（HTTPS）中使用
- `PermissionDeniedPermanently`：权限已被永久拒绝
- `NotAllowedError`：麦克风权限被拒绝
- `MediaDevicesApiUnavailable`：MediaDevices API不可用
- `NotFoundError`：未找到音频输入设备
- `NotReadableError`：音频设备被其他应用程序占用
- `OverconstrainedError`：音频设备不满足指定的约束条件
- `SecurityError`：安全策略阻止访问麦克风
- `MicrophoneUnknownError`：未知麦克风权限错误
- `MicrophoneTimeoutError`：获取麦克风权限超时

## 平台兼容性

| 平台 | PC端版本 | 移动端版本 | 全端版本 | 备注 |
|------|---------|-----------|---------|------|
| Chrome (PC) | ✅ | ❌ | ✅ | PC端版本专门优化 |
| Firefox (PC) | ✅ | ❌ | ✅ | PC端版本专门优化 |
| Safari (PC) | ✅ | ❌ | ✅ | PC端版本专门优化 |
| iOS Safari | ❌ | ✅ | ✅ | 移动端版本专门优化 |
| Android Chrome | ❌ | ✅ | ✅ | 移动端版本专门优化 |
| Edge | ✅ | ❌ | ✅ | PC端版本专门优化 |

## 技术实现原理

### 音频播放权限
根据MDN文档，音频播放权限需要满足以下条件之一：
1. 音频被静音或音量为0
2. 用户已与网站产生交互（点击、触摸、按键等）
3. 网站已被加入自动播放白名单
4. 通过Permissions Policy授权

### 麦克风权限
根据MDN文档，getUserMedia需要满足：
1. 安全上下文（HTTPS）
2. 用户明确授权
3. 顶级文档上下文或通过Permissions Policy授权的iframe

## 版本差异对比

| 特性 | PC端版本 | 移动端版本 | 全端版本 |
|------|---------|-----------|----------|
| 包体积 | 最小 | 小 | 大 |
| 性能 | 最优 | 优 | 良 |
| 平台检测 | 无 | 无 | 有 |
| 预检测优化 | 有 | 无 | 有 |
| 触摸事件优化 | 无 | 有 | 有 |
| 键盘事件支持 | 完整 | 基础 | 完整 |
| 维护成本 | 低 | 低 | 中 |

## 注意事项

1. **HTTPS要求**：麦克风权限必须在HTTPS环境下使用（localhost除外）
2. **用户交互**：音频播放权限需要用户先产生交互行为
3. **权限缓存**：浏览器会缓存用户的权限决定，被拒绝后需要用户手动在浏览器设置中重新开启
4. **iOS特殊处理**：iOS Safari需要在用户交互的调用栈中调用AudioContext.resume()
5. **超时设置**：麦克风权限请求设置了10秒超时，避免无限等待
6. **版本选择**：根据项目实际需求选择合适的版本，避免不必要的代码冗余

## 开发建议

1. **版本选择**：优先选择专用版本（PC端/移动端），只有在必要时才使用全端版本
2. **权限时机**：在用户明确需要音频功能时再请求权限
3. **错误处理**：提供清晰的权限说明和错误提示
4. **备选方案**：为权限被拒绝的情况提供备选方案
5. **开发环境**：在开发环境使用localhost或HTTPS
6. **兼容性测试**：测试不同平台和浏览器的兼容性
7. **按需加载**：可以根据用户代理动态加载对应版本，进一步优化性能

## 许可证

MIT License