# realtime_demo

**Repository Path**: jimonik/realtime_demo

## Basic Information

- **Project Name**: realtime_demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Voice Call Android

一个原生 Android 示例，提供三个 App 内实时语音通话入口：

- OpenAI GPT-Live：`gpt-live-1`，`marin` 音色，默认入口。
- OpenAI Realtime：`gpt-realtime-2.1`，`marin` 音色。
- xAI Speech to Speech：`grok-voice-3.0`，`eve` 音色。

## 可选通话模型

以下清单按官方文档于 **2026-10-19** 核对。“可直接切换”是指模型可使用本项目已经接入的实时传输：GPT-Live 和 OpenAI Realtime 使用各自的 WebRTC 协议，xAI 使用 `/v1/realtime` WebSocket；是否实际可用仍取决于账号权限、区域和限额。

### OpenAI

#### 当前 Realtime 模型（本项目可直接切换）

| 模型 ID | 定位 | 输入 / 输出 | 上下文 / 最大输出 | Realtime 能力 |
| --- | --- | --- | --- | --- |
| `gpt-realtime-2.1` | **当前默认，推荐** | 文本、音频输入输出；图片输入 | 128K / 32K | 可配置推理强度、函数调用；相对 2.0 改进字母数字识别、静音与噪声处理和打断行为；支持 WebRTC、WebSocket、SIP |
| `gpt-realtime-2.1-mini` | 低成本、低延迟 | 文本、音频输入输出；图片输入 | 128K / 32K | 2.1 的蒸馏推理模型，支持函数调用；字母数字识别优于 2.0；支持 WebRTC、WebSocket、SIP |
| `gpt-realtime-2` | 上一代高级推理语音模型 | 文本、音频输入输出；图片输入 | 128K / 32K | 可配置推理强度、较强指令遵循与工具调用，适合复杂 Voice Agent；支持 WebRTC、WebSocket、SIP |
| `gpt-realtime-1.5` | 上一代旗舰音频模型 | 文本、音频输入输出；图片输入 | 32K / 4,096 | 面向 Voice Agent 和客服，支持函数调用；不具备 2.x 的可配置推理能力 |

上述模型都支持原生语音到语音、服务端 VAD、打断、输出音频转写，以及文本或音频响应。App 可在拨号前直接选择全部上述 OpenAI Realtime 模型，默认选择 `gpt-realtime-2.1`。

#### GPT-Live（本项目默认通话入口）

| 模型 ID | 输入 / 输出 | 能力 | 与本项目的关系 |
| --- | --- | --- | --- |
| `gpt-live-1` | 文本、音频输入输出；不支持图片或视频 | 真正全双工，可同时聆听和说话，打断更自然；可把推理和工具任务委派给后端 Agent | 已通过 `/v1/live/sessions` + WebRTC 接入；使用独立的 Live 事件协议 |

### xAI

| 模型 ID | 状态 | Realtime 能力 |
| --- | --- | --- |
| `grok-voice-3.0` | 当前旗舰固定版本 | 双向实时音频与文本；推理强度支持 `high`（默认）或 `none`；支持函数、文件搜索、网页搜索、X 搜索和 MCP 工具；支持服务端 VAD、空闲超时主动搭话、断线会话恢复、自定义音色，以及 PCM、PCMU、PCMA、Opus 输入 |

Grok 服务的模型选择器会列出当前可用于这套 Realtime WebSocket 协议的全部模型；目前为固定版本 `grok-voice-3.0`，以避免动态别名升级后行为发生变化。

## Function Calling 支持

当前列出的通话模型都能参与 Function Calling，但 GPT-Live 与 Realtime / Grok Voice 的架构不同：

| 模型 ID | Function Calling | 调用方式 |
| --- | --- | --- |
| `gpt-realtime-2.1` | 支持 | Realtime 模型直接选择并调用客户端函数；支持并行工具调用 |
| `gpt-realtime-2.1-mini` | 支持 | Realtime 模型直接选择并调用客户端函数；支持并行工具调用 |
| `gpt-realtime-2` | 支持 | Realtime 模型直接选择并调用客户端函数；支持并行工具调用 |
| `gpt-realtime-1.5` | 支持 | Realtime 模型直接选择并调用客户端函数；工具选择能力弱于 2.x |
| `gpt-live-1` | 通过委派支持 | GPT-Live 负责通话，把任务委派给 Responses 模型或自有 Agent，由后端选择和调用函数 |
| `grok-voice-3.0` | 支持 | Grok Voice 直接选择并调用客户端函数；支持一次产生多个函数调用 |

OpenAI Realtime（通过 WebRTC DataChannel）和 xAI Speech to Speech（通过 WebSocket）的客户端函数调用事件流程基本一致：

1. App 在 `session.update` 的 `tools` 中使用 JSON Schema 声明函数。
2. 模型决定调用函数，并通过 `response.function_call_arguments.done` 返回函数名和参数。
3. App 校验参数、权限和必要的用户确认，然后执行本地代码或后端 API。
4. App 发送包含 `function_call_output` 的 `conversation.item.create`，把执行结果交还模型。
5. App 发送 `response.create`，让模型基于函数结果继续生成语音回答。

当一次产生多个函数调用时，可并行执行互不依赖的函数，但必须提交全部 `function_call_output` 后再发送一次 `response.create`。对于会修改数据、产生费用或触发外部行为的函数，App 必须自行完成鉴权、参数校验和用户确认，不能仅依赖模型判断。

GPT-Live 不采用上述“语音模型直接执行工具循环”的结构。`gpt-live-1` 负责自然对话，并通过以下任一方式委派任务：

- **Responses 委派**：配置一个独立的 Responses 模型负责推理、选择函数和工具；OpenAI 管理 Live 与后端模型之间的上下文传递。
- **客户端委派**：App 自己运行现有 Agent 或业务工作流，并把经过校验的结果返回 GPT-Live 进行口头表达。

### 当前项目的实现状态

模型具备 Function Calling 能力不代表本项目已经接好工具循环。目前代码只处理语音和转写事件，尚未：

- 在 `VoiceProvider.sessionUpdate()` 中配置 `tools` 和 `tool_choice`。
- 在 `RealtimeCall.onMessage()` 中处理 `response.function_call_arguments.done`。
- 执行业务函数并发送 `function_call_output`。
- 在函数结果提交后发送 `response.create` 继续对话。
- 对函数参数、权限、确认、超时、失败及重复调用进行保护。

因此当前 App 还不能实际执行 Function Calling。GPT-Live 基础通话已经接通，但工具能力仍需额外配置 Responses delegation 或 client delegation；Realtime 和 Grok 则需要补齐各自的直接工具调用循环。

## 本地运行

当前版本用于本地测试，OpenAI 和 Grok Key 都从根目录 `gradle.properties` 编译进 Debug APK：

```properties
OPENAI_API_KEY=
XAI_API_KEY=
```

然后使用 Android Studio 打开项目，运行 `app`。首次拨号时允许麦克风权限。拨号前可选择服务、Realtime 模型及默认输出设备；通话过程中可随时在听筒和扬声器间切换。

> 不要提交真实 Key，也不要分发这个测试 APK。APK 中的 Key 可以被提取；正式发布前必须改为可信后端创建 OpenAI 会话，并为 Grok 使用后端签发的临时令牌。

## 能力边界

当前“打电话”是手机 App 内与 AI 的全双工语音对话，不会拨打真实手机或固话号码。接入 PSTN 需要另外配置 SIP/电话运营商、呼叫权限、号码和后端控制。

GPT-Live 与 OpenAI Realtime 的音频都由 WebRTC 媒体轨传输，系统 WebRTC 音频模块负责回声消除和播放缓冲。GPT-Live 自己管理全双工讲话时机；Realtime 使用官方默认 `server_vad` 自动应答与打断，并随路由选择 `near_field` 或 `far_field` 输入降噪。xAI 仍使用 24 kHz、16-bit、单声道 PCM WebSocket 音频流。

## 官方资料

- [OpenAI 模型目录](https://developers.openai.com/api/docs/models/all)
- [OpenAI Realtime 对话](https://developers.openai.com/api/docs/guides/realtime-conversations)
- [OpenAI Realtime WebRTC](https://developers.openai.com/api/docs/guides/voice-webrtc)
- [OpenAI GPT-Realtime-2.1](https://developers.openai.com/api/docs/models/gpt-realtime-2.1)
- [OpenAI GPT-Realtime-2.1 Mini](https://developers.openai.com/api/docs/models/gpt-realtime-2.1-mini)
- [OpenAI Realtime 工具与 Function Calling](https://developers.openai.com/api/docs/guides/realtime-mcp)
- [OpenAI GPT-Live 1](https://developers.openai.com/api/docs/models/gpt-live-1)
- [OpenAI GPT-Live 入门](https://developers.openai.com/api/docs/guides/live)
- [OpenAI GPT-Live 委派与工具](https://developers.openai.com/api/docs/guides/live-delegation)
- [xAI Speech to Speech 与模型选择](https://docs.x.ai/developers/model-capabilities/audio/speech-to-speech)
- [xAI 临时令牌](https://docs.x.ai/developers/model-capabilities/audio/ephemeral-tokens)