Skip to content

Commit e1d3f05

Browse files
AbySwifterAbySwifter
authored
Merge pull request #17 from Hanpto/main
add api-example
2 parents 0052ff7 + dccc583 commit e1d3f05

99 files changed

Lines changed: 13370 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎api-example/.gitignore‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Miscellaneous
2+
*.class
3+
*.log
4+
*.pyc
5+
*.swp
6+
.DS_Store
7+
.atom/
8+
.build/
9+
.buildlog/
10+
.history
11+
.svn/
12+
.swiftpm/
13+
migrate_working_dir/
14+
15+
# IntelliJ related
16+
*.iml
17+
*.ipr
18+
*.iws
19+
.idea/
20+
21+
# The .vscode folder contains launch configuration and tasks you configure in
22+
# VS Code which you may wish to be included in version control, so this line
23+
# is commented out by default.
24+
#.vscode/
25+
26+
# Flutter/Dart/Pub related
27+
**/doc/api/
28+
**/ios/Flutter/.last_build_id
29+
.dart_tool/
30+
.flutter-plugins
31+
.flutter-plugins-dependencies
32+
.pub-cache/
33+
.pub/
34+
/build/
35+
.metadata
36+
pubspec.lock
37+
analysis_options.yaml
38+
39+
# Symbolication related
40+
app.*.symbols
41+
42+
# Obfuscation related
43+
app.*.map.json
44+
45+
# Android Studio will place build artifacts here
46+
/android/app/debug
47+
/android/app/profile
48+
/android/app/release

‎api-example/README.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# AtomicXCore API 示例 Demo — Flutter
2+
3+
[English](./README_EN.md) | 中文
4+
5+
## 项目简介
6+
7+
本项目是 **AtomicXCore SDK** 的 Flutter 端 API 示例 Demo，通过四个渐进式阶段完整展示了从基础推拉流到复杂互动直播的全部核心功能。项目基于 Flutter 原生 Widget 体系 + `ValueListenable` 响应式状态管理构建，支持 Android 和 iOS 双平台，适合开发人员快速了解和集成 AtomicXCore SDK。
8+
9+
## 功能概览
10+
11+
| 阶段 | 功能模块 | 说明 |
12+
|:---:|:---|:---|
13+
| 1 | **BasicStreaming** 基础推拉流 | 直播创建/加入、摄像头/麦克风管理、视频渲染 |
14+
| 2 | **Interactive** 实时互动 | 弹幕消息、礼物系统（含 SVGA 动画）、点赞、美颜、音效 |
15+
| 3 | **CoGuest** 观众连线 | 观众申请上麦、主播邀请连线、麦位管理、多人视频 |
16+
| 4 | **LivePK** 直播 PK 对战 | 跨房连线、PK 对战、实时积分、倒计时、战斗结果展示 |
17+
18+
> 四个阶段层层递进，每个后续阶段都包含前一阶段的全部功能并增加新能力。
19+
20+
## 技术栈
21+
22+
| 类别 | 技术 | 版本 |
23+
|:---:|:---|:---|
24+
| 框架 | Flutter | 3.29.3 |
25+
| 语言 | Dart | 3.7.2 |
26+
| 核心 SDK | AtomicXCore (`atomic_x_core`) | ^4.0.0 |
27+
| 状态管理 | Flutter 原生 ValueNotifier / ValueListenableBuilder | — |
28+
| 动画引擎 | svgaplayer_flutter | ^2.2.0 |
29+
| 图片缓存 | cached_network_image | ^3.3.1 |
30+
| 权限管理 | permission_handler | ^11.3.1 |
31+
| 本地存储 | shared_preferences | ^2.5.3 |
32+
| 加密工具 | crypto | ^3.0.6 |
33+
| 国际化 | Flutter Localizations + intl | — |
34+
| 代码规范 | flutter_lints | ^5.0.0 |
35+
36+
## 项目架构
37+
38+
### 架构模式
39+
40+
项目采用 **Store + ValueListenable 响应式架构**（类似 MVVM/Flux 混合模式）：
41+
42+
- **Store 层**：由 `atomic_x_core` SDK 提供，包含 `LoginStore`、`LiveListStore`、`DeviceStore`、`BarrageStore`、`GiftStore` 等全局单例或实例化 Store
43+
- **状态暴露**：各 Store 通过 `xxxState` 属性暴露状态对象，字段类型为 `ValueListenable<T>`（即 Flutter 原生 `ValueNotifier`）
44+
- **UI 绑定**：使用 `ValueListenableBuilder<T>` 在 Widget Tree 中进行精确的局部重建
45+
- **事件回调**：SDK 提供 Listener 回调模式（如 `GiftListener`、`BattleListener` 等），通过 `addXxxListener` / `removeXxxListener` 注册
46+
- **无第三方状态管理依赖**：不使用 Provider、Riverpod、Bloc 等，完全基于 Flutter 原生能力
47+
48+
### 目录结构
49+
50+
```
51+
flutter/lib/
52+
├── main.dart # 应用入口（MaterialApp + 语言切换监听）
53+
├── components/ # 可复用 UI 组件层
54+
│ ├── components.dart # 统一导出桶文件
55+
│ ├── audio_effect_setting_widget.dart # 音效设置面板（变声/混响/耳返）
56+
│ ├── barrage_widget.dart # 弹幕消息列表 + 输入框
57+
│ ├── beauty_setting_widget.dart # 美颜设置面板（磨皮/美白/红润）
58+
│ ├── co_host_user_list_widget.dart # 可连线主播列表（分页加载）
59+
│ ├── device_setting_widget.dart # 设备管理面板（摄像头/麦克风/镜像/清晰度）
60+
│ ├── gift_animation_widget.dart # 礼物动画展示（SVGA 全屏 + 弹幕滑动）
61+
│ ├── gift_panel_widget.dart # 礼物选择面板（分页网格 + 发送）
62+
│ ├── like_button.dart # 点赞按钮（爱心粒子贝塞尔曲线动效）
63+
│ ├── localized_manager.dart # 本地化管理器（中英文切换 + 持久化）
64+
│ ├── permission_helper.dart # 运行时权限封装（相机/麦克风）
65+
│ ├── role.dart # 角色枚举（ANCHOR/AUDIENCE）
66+
│ └── setting_panel_controller.dart # 通用半屏浮层容器
67+
├── debug/
68+
│ └── generate_test_user_sig.dart # 调试用 UserSig 本地生成工具
69+
├── l10n/ # 国际化资源
70+
│ ├── app_en.arb # 英文字符串（模板文件，355 条）
71+
│ ├── app_zh.arb # 简体中文字符串（212 条）
72+
│ ├── app_localizations.dart # 生成的 l10n 入口
73+
│ ├── app_localizations_en.dart # 生成的英文实现
74+
│ └── app_localizations_zh.dart # 生成的中文实现
75+
└── scenes/ # 业务场景页面层
76+
├── login/
77+
│ ├── login_page.dart # 用户登录页
78+
│ └── profile_setup_page.dart # 资料完善页（昵称 + 头像选择）
79+
├── feature_list/
80+
│ └── feature_list_page.dart # 功能列表首页（4 个阶段入口卡片）
81+
├── basic_streaming/
82+
│ └── basic_streaming_page.dart # 阶段 1: 基础推拉流
83+
├── interactive/
84+
│ └── interactive_page.dart # 阶段 2: 实时互动
85+
├── co_guest/
86+
│ └── co_guest_page.dart # 阶段 3: 观众连线
87+
└── live_pk/
88+
└── live_pk_page.dart # 阶段 4: 直播 PK 对战
89+
```
90+
91+
### 应用流程
92+
93+
```
94+
LoginPage (输入 UserID → SDK 登录)
95+
│
96+
├─ 昵称为空 ──→ ProfileSetupPage (设置昵称 + 选择头像)
97+
│ │
98+
│ ▼
99+
└─ 昵称已设置 ──→ FeatureListPage (4 个阶段入口卡片)
100+
│
101+
├─ 选择阶段 → 角色选择 BottomSheet
102+
│ ├─ 主播 → 直接进入对应页面
103+
│ └─ 观众 → 输入房间号 Dialog → 进入对应页面
104+
│
105+
├──→ BasicStreamingPage (阶段 1)
106+
├──→ InteractivePage (阶段 2)
107+
├──→ CoGuestPage (阶段 3)
108+
└──→ LivePKPage (阶段 4)
109+
```
110+
111+
### Store 类型与生命周期
112+
113+
| Store | 类型 | 使用场景 |
114+
|:---|:---|:---|
115+
| `LoginStore.shared` | 全局单例 | 登录、用户信息设置 |
116+
| `LiveListStore.shared` | 全局单例 | 直播房间生命周期管理 |
117+
| `DeviceStore.shared` | 全局单例 | 摄像头/麦克风/视频质量 |
118+
| `BaseBeautyStore.shared` | 全局单例 | 美颜调节 |
119+
| `AudioEffectStore.shared` | 全局单例 | 音效/变声/耳返 |
120+
| `BarrageStore.create(liveID)` | 按房间实例化 | 弹幕收发 |
121+
| `GiftStore.create(liveID)` | 按房间实例化 | 礼物收发 |
122+
| `LikeStore.create(liveID)` | 按房间实例化 | 点赞互动 |
123+
| `CoGuestStore.create(liveID)` | 按房间实例化 | 观众连线管理 |
124+
| `CoHostStore.create(liveID)` | 按房间实例化 | 跨房连线管理 |
125+
| `BattleStore.create(liveID)` | 按房间实例化 | PK 对战管理 |
126+
| `LiveAudienceStore.create(liveID)` | 按房间实例化 | 观众列表 |
127+
| `LiveSeatStore.create(liveID)` | 按房间实例化 | 麦位管理 |
128+
129+
## AtomicXCore SDK API 使用说明
130+
131+
### 阶段 1：BasicStreaming — 基础推拉流
132+
133+
| Store | 关键 API | 功能 |
134+
|:---|:---|:---|
135+
| `LoginStore` | `login()`, `setSelfInfo()`, `loginState` | 用户登录与状态管理 |
136+
| `LiveListStore` | `createLive()`, `joinLive()`, `endLive()`, `leaveLive()` | 直播房间生命周期管理 |
137+
| `DeviceStore` | `openLocalCamera()`, `openLocalMicrophone()`, `switchCamera()` | 本地设备控制 |
138+
| `LiveCoreWidget` | `LiveCoreController.create(CoreViewType)` | 视频渲染 Widget |
139+
140+
### 阶段 2：Interactive — 实时互动
141+
142+
| Store | 关键 API | 功能 |
143+
|:---|:---|:---|
144+
| `BarrageStore` | `sendTextMessage()`, `barrageState.messageList` | 弹幕消息收发 |
145+
| `GiftStore` | `sendGift()`, `refreshUsableGifts()`, `setLanguage()` | 礼物系统 |
146+
| `LikeStore` | `sendLike()`, `addLikeListener()` | 点赞互动 |
147+
| `BaseBeautyStore` | `setSmoothLevel()`, `setWhitenessLevel()`, `setRuddyLevel()` | 美颜调节 |
148+
| `AudioEffectStore` | `setAudioChangerType()`, `setAudioReverbType()`, `setVoiceEarMonitorEnable()` | 音效与耳返 |
149+
150+
### 阶段 3：CoGuest — 观众连线
151+
152+
| Store | 关键 API | 功能 |
153+
|:---|:---|:---|
154+
| `CoGuestStore` | `applyForSeat()`, `inviteToSeat()`, `acceptApplication()`, `disconnect()` | 连线请求管理 |
155+
| `LiveSeatStore` | `openRemoteCamera()`, `kickUserOutOfSeat()` | 麦位与远端设备管理 |
156+
| `LiveAudienceStore` | `fetchAudienceList()` | 观众列表 |
157+
| `LiveCoreWidget` | `videoWidgetBuilder` | 自定义连线用户视频覆盖层 |
158+
159+
### 阶段 4：LivePK — 直播 PK 对战
160+
161+
| Store | 关键 API | 功能 |
162+
|:---|:---|:---|
163+
| `CoHostStore` | `requestHostConnection()`, `acceptHostConnection()`, `exitHostConnection()` | 跨房连线管理 |
164+
| `BattleStore` | `requestBattle()`, `acceptBattle()`, `exitBattle()`, `battleState` | PK 对战管理与实时积分 |
165+
| `LiveListStore` | `fetchLiveList()` | 获取可连线主播列表 |
166+
167+
## 环境要求
168+
169+
- **Flutter**: 3.29.3（Dart SDK 3.7.2）
170+
- **Android**: minSdkVersion 21+
171+
- **iOS**: iOS 12.0+
172+
- **开发工具**: Android Studio / VS Code + Flutter 插件
173+
174+
## 快速开始
175+
176+
### 1. 克隆项目
177+
178+
```bash
179+
git clone <repository-url>
180+
cd atomic-api-example/flutter
181+
```
182+
183+
### 2. 安装依赖
184+
185+
```bash
186+
flutter pub get
187+
```
188+
189+
### 3. 配置 SDK 凭证
190+
191+
编辑 `lib/debug/generate_test_user_sig.dart`，填入你的腾讯云应用凭证：
192+
193+
```dart
194+
const int SDKAPPID = 0; // 替换为你的 SDKAPPID
195+
const String SECRETKEY = ''; // 替换为你的 SECRETKEY
196+
```
197+
198+
> ⚠️ **安全提示**: `SECRETKEY` 仅用于本地调试。生产环境中，UserSig 必须由后端服务生成，切勿将 SECRETKEY 嵌入客户端发布包中。
199+
200+
### 4. 运行
201+
202+
```bash
203+
# Android
204+
flutter run -d android
205+
206+
# iOS
207+
cd ios && pod install && cd ..
208+
flutter run -d ios
209+
```
210+
211+
## 权限说明
212+
213+
### Android
214+
215+
| 权限 | 用途 |
216+
|:---|:---|
217+
| `CAMERA` | 摄像头采集 |
218+
| `RECORD_AUDIO` | 麦克风采集 |
219+
| `MODIFY_AUDIO_SETTINGS` | 音频设置调节 |
220+
221+
### iOS
222+
223+
| 权限 | 用途 |
224+
|:---|:---|
225+
| `NSCameraUsageDescription` | 直播视频采集 |
226+
| `NSMicrophoneUsageDescription` | 直播音频采集 |
227+
228+
## 国际化支持
229+
230+
项目支持中英文双语切换，采用 Flutter 官方 `flutter_localizations` + ARB 方案：
231+
232+
| 文件 | 说明 |
233+
|:---|:---|
234+
| `lib/l10n/app_en.arb` | 英文字符串（模板文件，355 条） |
235+
| `lib/l10n/app_zh.arb` | 简体中文字符串（212 条） |
236+
237+
- 默认跟随系统语言（中文系统 → zh，其他 → en）
238+
- 用户可在功能列表页的设置菜单中手动切换语言
239+
- 语言偏好通过 `SharedPreferences` 持久化保存

0 commit comments

Comments
 (0)