# 场景化 API 方案概览 (/zh-CN/solutions/online-ktv/ktv-scenario)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

场景化 API 方案将复杂的实时互动 SDK API 封装成几个简单易用的 API，帮助开发者降低集成难度。通过场景化 API，你可以快速实现独唱、实时合唱、抢唱、接唱等多种 K 歌场景。

<OverviewActions actions={[
  { label: '方案对比', href: '/zh-CN/solutions/online-ktv/ktv-scenario/reference/solution-compare' },
  { label: '客户端 API', href: '/zh-CN/api-reference/api?product=online-ktv&apiType=client' },
  { label: '服务端 API', href: '/zh-CN/api-reference/online-ktv/android/ktv-scenario/api/music-content-center' },
]} />

## 开始构建 [#开始构建]

<Cards>
  <Card title="快速开始" href="/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi" description="运行示例或完成最小可用集成，快速验证核心流程。" />
  <Card title="构建功能" href="/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service" description="按业务任务接入核心能力，并完成生产环境配置。" />
  <Card title="参考信息" href="/zh-CN/solutions/online-ktv/ktv-scenario/reference/billing" description="查看版本、计费、限制、错误码、API 和兼容性说明。" />
</Cards>


## 场景描述 [#场景描述]

在线 K 歌房是声网提供的线上 K 歌场景化解决方案，结合声网实时互动 SDK 和声网内容中心等产品，将其复杂的 API 进行模块整合，实现了功能组件化，降低了开发门槛。在此方案中，歌房里的主播可以点歌成为主唱，跟随歌曲伴奏演唱给歌房内的听众，在网络情况优良的条件下还可以实现双人合唱，在演唱过程中：

- 主唱可以控制歌曲的暂停、播放和切换，并且可以自己调节伴奏和人声音量。
- 主唱可以选择合唱模式邀请房间内的其他用户进行合唱。
- 主唱可以开启打分模式，会根据主唱音准的匹配程度，系统给出得分。
- 歌房内有歌词板块，唱歌时会根据歌曲播放进度显示对应的歌词。
- 声网内容中心提供热门歌曲曲库，主播可以搜索想唱的歌曲，点歌并查看已点列表。
- 听众可以通过上麦点歌进行排麦演唱，并随时与房主和其他连麦主播进行实时音频互动。

**房间内的角色及描述**

| 角色     | 描述                                                         |
| :------- | :----------------------------------------------------------- |
| 房主     | 歌房创建者                                                   |
| 连麦主播 | 进入歌房后，通过上麦成为连麦主播                             |
| 主唱     | 连麦主播点歌后成为主唱，并进行排麦演唱                       |
| 合唱者   | 主唱在合唱模式下点歌可邀请房间内的连麦主播成为合唱者，一起低延时合唱 |
| 听众     | 进入歌房的倾听者                                             |

## 功能列表 [#功能列表]

在线 K 歌房场景化解决方案提供以下核心功能：

**实时音频互动**

超低延时下，听众实时接收连麦主播的音频流，保证互动的流畅性。

**互动连麦**

听众可自主上麦成为连麦主播，连麦主播之间可以进行实时音频互动，房间内用户可以实时观看连麦主播互动。

**曲库组件**

声网内容中心提供热门歌曲的曲库，曲库支持搜索功能。

**实时合唱**

升级实时合唱技术，支持两人及以上用户合唱，各端相互独立、互不影响，真实还原线下体验。

**点歌排麦**

连麦主播从声网内容中心点歌，歌曲进入已点列表；当点歌人数大于1时，根据点歌顺序进行排麦演唱，开始播放歌曲后点歌用户成为主唱。

**歌曲控制**

主唱可以控制歌曲的播放、暂停，切换伴奏/原唱，以及控制伴奏和人声的音量。

**歌词组件**

- 歌曲播放时，根据播放进度显示对应的歌词；
- 滑动歌词可以改变歌曲进度；
- 主唱演唱时显示评分的动画效果；
- 主唱可以改变歌词背景。

**麦位控制**

房主可以对房间内成员进行上麦、下麦操作，同时房间内所有用户都能看到每个麦位的实时状态。

**低延时耳返**

支持耳返功能，在低延时的情况下可以给主唱一个比较真实的反馈。

## 技术方案 [#技术方案]

声网使用场景化 API、实时互动 SDK 和声网内容中心共同搭建在线 K 歌房场景。

**在线 K 歌独唱方案架构图**

![](https://web-cdn.agora.io/docs-files/1677210514106)

**在线 K 歌合唱方案架构图**

![](https://web-cdn.agora.io/docs-files/1680256324257)

独唱和合唱的角色、频道及音频流流程，详见 [独唱实现](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/solo) 和 [合唱实现](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/chorus)。

除此之外，声网还提供[大合唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/grand-chorus)、[抢唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/gaming)、[接唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/relay)等实现方案，你可以根据你的业务需求进行选择。

**各 SDK 或服务实现的功能如下：**

| 产品 | 实现功能 |
| --- | --- |
| 声网 SDK | 加入频道，发布和接收音频流。 |
| 声网内容中心 | 提供在线 K 歌房场景所需歌曲及歌曲配套信息，如歌词、专辑封面、海报等。 |
| 声网歌词组件 | 根据歌曲播放进度实时显示歌词。支持自定义歌词界面布局，更换背景图片等操作。 |
| 第三方云服务 | [introduction-markdown-1-4-1 details](#table-slot-introduction-markdown-1-4-1) |

<a id="table-slot-introduction-markdown-1-4-1"></a>

**introduction-markdown-1-4-1 details**

实现麦位控制、房间信息和用户信息管理等功能。
声网在线 K 歌房示例项目中使用的云服务由声网实现。如果你需要使用相同功能，则需要自行部署第三方云服务。

## 方案优势 [#方案优势]

### 版权曲库整合 [#版权曲库整合]

曲库覆盖热门流行歌曲，一站式接入海量正版数字音乐。歌曲类型丰富多元，满足多样化用户喜好。

### 九大场景功能 [#九大场景功能]

- 支持搜歌点歌、歌词同步、原唱/伴唱切换、歌唱打分、美声音效、实时合唱等九大场景功能，还原线下 KTV 真实场景。
- 50 ms 超低延时耳返，告别走音跑调。

### 模块化组件设计 [#模块化组件设计]

- 模块化组件设计，降低开发成本，快速搭建 K 歌房。
- 灵活接入各类娱乐社交应用场景，简单调用让 app 有声有色。

### 媲美专业设备音质音效 [#媲美专业设备音质音效]

- 声网 SOLO™、NOVA™ 语音引擎，支持 48 kHz 全频带采样，还原声音高保真度，音频 MOS 分高达 4.7。
- 支持美声和音效，摆脱专业设备和人员束缚，让你的声音更动听、更有趣。