# MynaTalk iOS App（八哥口语 iOS 版）

iOS 端与 [android/](../android/README.md) 示例 App 功能对齐的移动端：

- 在线视频目录（`GET /api/v1/videos`，仅展示 `ready` 课程，自动解析相对流地址）
- AVPlayer 在线播放 + 本地缓存导入；单击播放/暂停
- 左划 / 右划：上一句 / 下一句（无句边界时回退为 10 秒快退 / 快进）
- 长按播放区：按触摸点水平位置变速（左慢右快，0.5x - 2.0x），松手恢复原速
- 按句跳转：句边界来自 `GET /api/v1/videos/{sha256}/sentence-boundaries`
- 连续播放开关：关闭时循环播放当前句子，开启时按句子顺序连续播放
- 进度条拖动定位、播放状态 / 句号 / 变速显示
- 横屏全屏播放（半透明句面板，与安卓端横屏布局一致）
- 本地视频导入：复制到缓存并计算 SHA-256，自动匹配服务端句边界
- 朗读评测：麦克风录音（AAC 16kHz），上传
  `POST /api/v1/videos/{sha256}/sentences/{index}/assessments`，
  展示内容 / 流畅度 / 时长 / 停顿 / 语速等分数与漏读、多读、反馈
- HTTPS 因 TLS 问题失败时自动降级重试 HTTP（与安卓端 `allowHttpFallback` 一致）

## 目录结构

```
ios/
├── OralTrainer.xcodeproj        # Xcode 工程
└── OralTrainer/
    ├── Config.swift             # 服务端地址与评测密钥（改这里）
    ├── Models/                  # 课程 / 句边界 / 评测数据模型
    ├── Services/                # HTTP 客户端、课程目录、句边界、评测上传
    ├── Player/                  # 播放控制器（AVPlayer）+ 手势播放区
    └── Views/                   # SwiftUI 界面（训练 / 测试 / 全屏）
```

## 构建与运行

1. 需要 macOS + Xcode（16 或更新版本），iOS 部署目标 16.0。
2. 打开 `ios/OralTrainer.xcodeproj`，在 Signing 里选择你的开发者团队。
3. 选一台 iPhone / iPad 或模拟器运行；真机评测录音需要麦克风权限
   （首次点击“开始录音”时会自动请求）。
4. 本机没有 Xcode 时，也可在另一台装有 Xcode 的 Mac 上打开本目录构建。

## 配置

- 服务端地址：改 `OralTrainer/Config.swift` 里的 `serverBaseURL`
  （内网可填 `http://<服务器IP>:<端口>`）。
- 评测密钥：改 `assessmentAPIKey`，填服务器 `sentence_api/.env` 里的
  `CLIENT_API_KEY`；安卓端示例 App 用的是同一个密钥。
- 生产环境建议保持 HTTPS；`Info.plist` 中的 `NSAllowsArbitraryLoads`
  与安卓端的明文 HTTP 开关一样，仅为内网/私有部署提供便利。

## 与安卓端的差异说明

- 播放内核为系统 AVPlayer（对应安卓 Media3/ExoPlayer），支持 MP4/MOV/M4V
  及 HLS；MKV/WEBM 需先转码，与 iOS 系统播放器能力一致。
- 横屏全屏：点播放区右下角的旋转按钮进入；iPhone 会自动锁定横屏，
  退出后恢复竖屏；iPad 允许全部方向。
- 速度胶囊支持点击循环 1x → 1.25x → 1.5x → 1.75x → 2.0x
  （安卓端只有长按变速，这里作为 iOS 便捷补充）。

## 常见问题

- “云端暂不可用：…”：检查手机能否访问服务端、地址是否填对、网关证书是否有效。
- 本地视频评测提示“仅云端课程支持朗读评测”：本地文件需先通过管理端上传到服务器。
- 录音提示失败：在 设置 > 隐私 > 麦克风 中允许本 App 使用麦克风。