跳到主要内容
版本：v3

实时语音开发指南

SDK 获取​

可以在 下载页 获得 TapSDK，引入 TapRTC 模块：

请先确保系统已安装 git-lfs，然后通过 UPM 方式添加依赖：

"dependencies":{
...
"com.taptap.tds.rtc":"https://github.com/taptap/tapsdk-v3-unity.git?path=/RTC#3.30.3",
}

注意事项​

  • RTC 使用前需要在开发者中心进行相关配置。
  • 开发者需要在自己的服务器上实现相应的签名鉴权服务。
  • C# SDK 需要周期性的调用 TapRTC.Poll 接口，才能触发相关的事件回调。

Android 平台需要申请网络、音频相关权限：

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

iOS 平台需要申请麦克风权限（Privacy - Microphone Usage Description）。

游戏通常没有后台通话的需求，玩家一般边玩游戏边语音，游戏保持在前台。 如果游戏类型比较特殊，需要支持后台通话，那么还需申请后台播放权限： 在 target 中配置 Capability > Background Modes > Audio, AirPlay, and Picture in Picture。

核心接口​

RTC 通过 TapRTCConfig 来进行初始化配置。初始化的过程是异步的，需要等待初始化结果返回之后，才能进行下一步的操作。

  • ClientId、ClientToken、ServerUrl，参见关于应用凭证的说明。
  • UserId: 开发者自定义的用户 Id，用于标记玩家
  • DeviceId: 开发者自定义的设备 Id，用于标记设备
  • AudioPerfProfile: 音频质量配置（LOW、MID、HIGH，默认为 MID）
using TapTap.RTC;

var config = new TapRTCConfig.Builder()
            .ClientID("ClientId")
            .ClientToken("ClientToken")
            .ServerUrl("ServerUrl")
            .UserId("UserId")
            .DeviceId("DeviceId")
            .AudioProfile(AudioPerfProfile.MID)
            .ConfigBuilder();
            
ResultCode code = await TapRTC.Init(config);

if (code == ResultCode.OK) {
    // 初始化成功
} else {
    // 失败
}
// SDK 的 RTC 模块中，返回 ResultCode 的接口均以 ResultCode.OK 表示操作成功。

触发回调事件​

C# SDK 需要在 Update 方法中调用 Poll 方法触发事件回调。如果不调用该方法，会导致 SDK 运行异常。

public void Update()
{
    ResultCode code = TapRTC.Poll();
    if (code == ResultCode.OK) {
        // 成功触发回调
    } else {
        // 失败
    }
}

Java SDK、Objective-C SDK 无需定期调用 Poll 方法。

恢复系统​

ResultCode code = TapRTC.Resume();
if (code == ResultCode.OK) {
    // 成功恢复
} else {
    // 失败
}

暂停系统​

ResultCode code = TapRTC.Pause();
if (code == ResultCode.OK) {
    // 成功暂停
} else {
    // 失败
}

房间相关接口​

创建房间​

初始化成功之后，SDK 在创建房间之后，才可以进行实时语音通话。 创建房间时需指定房间号（roomId）。 是否启用范围语音也需在创建房间时设置，C# SDK 默认不启用，Java SDK 创建时必须指定是否启用范围语音，Objective-C SDK 使用单独的接口创建范围语音房间。

bool enableRangeAudio = false;
var room = await TapRTC.AcquireRoom("roomId", enableRangeAudio);

注册房间相关的回调事件​

room.RegisterEventAction(new TapRTCEvent()
{
    OnDisconnect = (code, message) => { label.text += "\n" + $"断开连接 code:{code} msg:{e}"; },
    OnEnterFailure = s => { label.text += "\n" + $"进入房间失败:{s}"; },
    OnEnterSuccess = () => { label.text += "\n" + $"进入房间成功"; },
    OnExit = () => { label.text += "\n" + $"退出房间成功"; },
    OnUserEnter = userId => { label.text += "\n" + $"玩家{userId}进入房间"; },
    OnUserExit = userId => { label.text += "\n" + $"玩家{userId}退出房间"; },
    OnUserSpeaker = (userId, volume) => { label.text += "\n" + $"玩家{userId}在房间说话，音量{volume}"; },
    OnUserSpeakEnd = userId => { label.text += "\n" + $"玩家{userId}在房间说话结束"; },
    // 返回切换后的音质，参见下文「切换音频质量」一节
    OnRoomTypeChanged = (i) => { label.text += "\n" + $"房间音质改为{i}"; },
    OnRoomQualityChanged = (weight, loss, delay) =>
    {
       Debug.Log($"音频质量:{weight} 丢包率:{loss}% 延迟:{delay}ms");
    },

});

加入房间​

使用服务端生成的鉴权信息进入房间。

进入房间成功之后，会通过 TapRTCEvent 中的 OnEnterSuccess 进行回调。

ResultCode code = await room.Join("authBuffer");
if (code == ResultCode.OK) {
    // 成功加入
}
if (code == ResultCode.ERROR_ALREADY_IN_ROOM) {
    // 玩家已经在此房间内
}

authBuffer 是在服务端生成的鉴权信息，详见下文服务端鉴权一节的说明。

退出房间​

退出房间之后，会通过 TapRTCEvent 中的 OnExit 进行回调。

ResultCode code = room.Exit();

收听某人语音（默认收听）​

ResultCode code = room.EnableUserAudio("userId");
if (code == ResultCode.OK) {
    // 成功
}
if (code == ResultCode.ERROR_USER_NOT_EXIST) {
    // 玩家不存在
}

拒收某人语音​

ResultCode code = room.DisableUserAudio("userId");
if (code == ResultCode.OK) {
    // 成功
}
if (code == ResultCode.ERROR_USER_NOT_EXIST) {
    // 玩家不存在
}

打开/关闭语音​

这个接口设置音频下行的开关。 一般来说，推荐游戏使用打开/关闭扬声器的接口。

// 开启
ResultCode code = room.EnableAudioReceiver(true);

// 关闭
ResultCode code = room.EnableAudioReceiver(false);

切换音频质量​

音频质量分为 LOW、MID、HIGH 三档。

进入房间后，可以切换音频质量。

room.ChangeRoomType(AudioPerfProfile.LOW);
room.ChangeRoomType(AudioPerfProfile.MID);
room.ChangeRoomType(AudioPerfProfile.HIGH);

切换音频质量会触发 OnRoomTypeChanged 回调。

获取当前房间的用户​

HashSet<string> userIdList = room.Users;

音频控制相关接口​

打开/关闭麦克风​

// 打开
ResultCode code = TapRTC.GetAudioDevice().EnableMic(true);

// 关闭
ResultCode code = TapRTC.GetAudioDevice().EnableMic(false);

打开/关闭扬声器​

// 打开
ResultCode code = TapRTC.GetAudioDevice().EnableSpeaker(true);

// 关闭
ResultCode code = TapRTC.GetAudioDevice().EnableSpeaker(false);

设置/获取音量​

音量是 0 到 100 之间的整数。

int vol = 60;

// 设置麦克风音量
ResultCode code = TapRTC.GetAudioDevice().SetMicVolume(vol);
// 设置扬声器音量
ResultCode code = TapRTC.GetAudioDevice().SetSpeakerVolume(vol);

// 获取麦克风音量
int micVolume = TapRTC.GetAudioDevice().GetMicVolume();
// 获取扬声器音量
int speakerVolume = TapRTC.GetAudioDevice().GetSpeakerVolume();

打开/关闭播放设备​

// 打开
ResultCode code = TapRTC.GetAudioDevice().EnableAudioPlay(true);
// 关闭
ResultCode code = TapRTC.GetAudioDevice().EnableAudioPlay(false);

打开/关闭耳返​

// 打开
ResultCode code = TapRTC.GetAudioDevice().EnableLoopback(true);
// 关闭
ResultCode code = TapRTC.GetAudioDevice().EnableLoopback(false);

范围语音​

范围语音功能可以支持以下特性：

  • 玩家附近一定范围内的其他小队玩家也能听到该玩家的语音；
  • 在同一房间内，支持大量用户同时打开麦克风进行语音通话。

要使用范围语音功能，首先创建房间时需要指定启用范围语音功能：

bool enableRangeAudio = true;
var room = await TapRTC.AcquireRoom("roomId", enableRangeAudio);

其次，玩家进入房间前，需要切换音频质量为 LOW：

room.ChangeRoomType(AudioPerfProfile.LOW);

接着设定小队号，并指定语音模式：

  • 世界模式：距离当前玩家一定范围内的其他小队成员也可以听到该玩家的语音；
  • 小队模式：仅小队成员之间可以互相通话。

无论哪种模式下，小队成员之间都能互相通话，不论距离远近。

int teamId = 12345678;
ResultCode code = room.GetRtcRangeAudioCtrl().SetRangeAudioTeam(teamId);
if (code == ResultCode.OK) {
    // 成功
}
if (code == ResultCode.ERROR_NOT_RANGE_ROOM) {
    // 该房间未启用范围语音
}

// 世界模式 
ResultCode resultCode = room.GetRtcRangeAudioCtrl().SetRangeAudioMode(RangeAudioMode.WORLD);
if (resultCode == ResultCode.OK) {
    // 成功
}
if (resultCode == ResultCode.ERROR_NOT_RANGE_ROOM) {
    // 该房间未启用范围语音
}
// 小队模式
ResultCode resultCode = room.GetRtcRangeAudioCtrl().SetRangeAudioMode(RangeAudioMode.TEAM);
if (resultCode == ResultCode.OK) {
    // 成功
}
if (resultCode == ResultCode.ERROR_NOT_RANGE_ROOM) {
    // 该房间未启用范围语音
}

然后进入房间，并设置语音接收范围、更新声源方位，范围语音即可生效。

进入房间后，如需切换语音模式，可再次调用 SetRangeAudioMode。

设置语音接收范围​

语音接收范围控制世界模式下其他小队成员能否听到声音，在进房后调用，一般仅需设置一次。

int range = 300;
ResultCode code = room.GetRtcRangeAudioCtrl().UpdateAudioReceiverRange(range);
if (code == ResultCode.OK) {
    // 成功
}
if (code == ResultCode.ERROR_NOT_RANGE_ROOM) {
    // 该房间未启用范围语音
}

范围（range）之外的其他小队成员无法听到。

如果同时启用 3D 语音，那么距离远近还会影响音量大小：

音源距离音量衰减
N < range/101.0（无衰减）
N >= range/10range/10/N

更新声源方位朝向​

成功进入房间后，需要在 Unity 的 Update 方法中调用该接口更新声源方位、朝向，范围语音才能生效。 方位通过世界坐标系的前、右、上三个坐标指定，朝向通过自身坐标系的前、右、上轴的单位向量指定。

int x = 1;
int y = 2;
int z = 3;
Position position = new Position(x, y, z);

float[] axisForward = new float[3] {1.0, 0.0, 0.0};
float[] axisRight = new float[3] {0.0, 1.0, 0.0};
float[] axisUp = new float[3] {0.0, 0.0, 1.0};
Forward forward = new Forward(axisForward, axisRight, axisUp);
ResultCode code = room.GetRtcRangeAudioCtrl().UpdateSelfPosition(position, forward);
if (code == ResultCode.OK) {
    // 成功
}
if (code == ResultCode.ERROR_NOT_RANGE_ROOM) {
    // 该房间未启用范围语音
}

朝向不影响是否能听到语音，因此如未启用 3D 语音，更新声源方位朝向时，朝向参数可随意设置。 但启用 3D 语音时，需正确设置朝向，这样才能得到准确的 3D 音效。

开关 3D 语音​

开启 3D 语音，可以将无方位感的声音处理成带有声源方位感的声音，以增加玩家的沉浸感。 这个接口接受两个参数，第一个参数指定当前玩家是否可以听到 3D 音效，第二个参数指定 3D 语音是否作用于小队内部。

bool enable3D = true;
bool applyToTeam = true;
ResultCode code = TapRTC.GetAudioDevice().EnableSpatializer(enable3D, applyToTeam);

错误码​

上述文档中的部分操作会返回 ResultCode，代码示例中给出了部分常见的错误类型对应的错误码。 完整的错误码列表如下：

namespace TapTap.RTC
{
    public enum ResultCode
    {
        OK = 0,
        ERROR_UNKNOWN = 1,
        ERROR_UNIMPLEMENTED = 2,
        ERROR_NOT_ON_MAIN_THREAD = 3,
        ERROR_INVAIDARGS = 4,
        ERROR_NOT_INIT = 5,
        ERROR_CONFIG_ERROR = 11,
        ERROR_NET = 21,
        ERROR_NET_TIMEOUT = 22,
        ERROR_USER_NOT_EXIST = 101,
        ERROR_ROOM_NOT_EXIST = 102,
        ERROR_DEVICE_NOT_EXIST = 103,
        ERROR_TEAM_ID_NOT_NULL = 104,
        ERROR_ALREADY_IN_ROOM = 105,
        ERROR_NO_PERMISSION = 106,
        ERROR_AUTH_FAILED = 107,
        ERROR_LIB_ERROR = 108,
        ERROR_NOT_RANGE_ROOM = 109,
    }
}

服务端​

为了保证聊天通道的安全性，实时语音服务需要搭配游戏自己的鉴权服务器使用。 此外，游戏自己的服务器还用于响应合规回调和调用剔除玩家的接口。

服务端鉴权​

客户端加入房间前，需要先通过开发者自己的鉴权服务器获取签名，之后实时语音云端会验证该签名，只有附带有效签名的请求才会被执行，非法请求会被阻止。

  1. 客户端加入房间前，向游戏自己的鉴权服务器请求签名；
  2. 鉴权服务器根据下文所述的鉴权密钥算法生成签名返回给客户端；
  3. 客户端获得签名后，编码到请求中，发给实时语音服务器；
  4. 实时语音服务器对请求的内容和签名做一遍验证，验证通过后执行后续的实际操作。

签名采用 HMAC-SHA1 算法和 Base64 结合。 针对不同的请求，开发者生成不同的签名（参见后续格式说明），总体上，签名就是使用特定的密钥（在这里我们使用应用的 Master Key），对玩家和房间信息进行签名。

鉴权密钥算法​

鉴权所用到的签名产生过程涉及到明文、密钥和加密算法。

明文​

明文为以下字段的 json 字符串（字段顺序无关）

字段类型/长度说明
userIdstring进入语音聊天房间的用户标识
appIdstring游戏的 Client ID
expireAtunsigned int/4过期时间（当前时间+有效期（单位：秒, 建议值：300s））
roomIdstring房间 ID
密钥​

游戏的 Master Key（即 Server Secret）。 Client ID 和 Server Secret 都可在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 查看。

加密算法​

加密算法采用 HMAC-SHA1 算法和 Base64 结合，类似 JWT 的格式。 生成的结果包含 payload（明文）和 sign（加密串）两部分。

  1. 按照上面表格中字段构造 JSON 字符串。

  2. Base64 编码上一步的 JSON 字符串得到 payload。

  3. 通过 HMAC-SHA1 对 payload 用 密钥 生成 sign。

  4. 使用 . （英文半角句号）拼接 payload 和 sign。

注意：JSON 字符串本身是字段顺序无关的，但是传递的 payload 和用于生成 sign 的 payload 的字段顺序必须相同，否则无法通过实时语音服务云端的校验。

下面给出 Java 和 Go 的示例代码供参考：

Java 示例
import com.google.gson.Gson;
import org.junit.Test;
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import static org.junit.Assert.*;

import java.time.Instant;
import java.util.Base64;

public class JUnitTestSuite {

    private static final String MAC_NAME = "HmacSHA1";

    @Test
    public void testToken() throws Exception {
        String masterKey = "masterKey";
        Token t = new Token();
        t.appId = "appId";
        t.userId ="user_test";
        t.roomId ="room_test";;

        int expTime = (int) Instant.now().getEpochSecond() + 5 * 60;
        t.expireAt = expTime;

        // server authBuff to your SDK Client
        String authBuff = genToken(t, masterKey);
        assertNotNull(authBuff);
    }

    private  String genToken(Token token, String key) throws Exception {
        Gson gson = new Gson();
        String t  = gson.toJson(token);
        String payload = Base64.getEncoder().encodeToString(t.getBytes(StandardCharsets.UTF_8));
        byte[] pEncryptOutBuf = hmacSHA1Encrypt(payload.getBytes(StandardCharsets.UTF_8), key);
        String sign = Base64.getEncoder().encodeToString(pEncryptOutBuf);
        return payload + "." + sign;
    }


    byte[] hmacSHA1Encrypt(byte[] text, String key) throws Exception {
        byte[] data = key.getBytes(StandardCharsets.UTF_8);
        SecretKey secretKey = new SecretKeySpec(data, MAC_NAME);
        Mac mac = Mac.getInstance(MAC_NAME);
        mac.init(secretKey);
        return mac.doFinal(text);
    }

    class Token {
        String userId;
        String appId;
        String roomId;
        long expireAt;
    }
}
Go 示例
package configs

import (
   "crypto/hmac"
   "crypto/sha1"
   "encoding/base64"
   "encoding/json"
   "fmt"
   "testing"
   "time"

   "github.com/stretchr/testify/assert"
)


func TestToken(t *testing.T) {
   assert := assert.New(t)
   t1 := &Token{
      UserId:   "appId",
      AppId:    "user_test",
      RoomId:   "roomId_test",
      ExpireAt: time.Now().Unix() + 5*60,
   }
   authBuff := GenToken(t1, "masterKey")
   assert.NotEmpty(authBuff)
   fmt.Println(authBuff)
}


const (
   sep = "."
)

func GenToken(t *Token, masterKey string) string {
   b, err := json.Marshal(t)
   if err != nil {
      return ""
   }
   payload := base64.StdEncoding.EncodeToString(b)
   sign := base64.StdEncoding.EncodeToString(HmacSHA1(masterKey, payload))
   return payload + sep + sign

}


func HmacSHA1(key string, data string) []byte {
   mac := hmac.New(sha1.New, []byte(key))
   mac.Write([]byte(data))
   return mac.Sum(nil)
}

type Token struct {
   UserId   string `json:"userId,omitempty"`
   AppId    string `json:"appId,omitempty"`
   RoomId   string `json:"roomId,omitempty"`
   ExpireAt int64  `json:"expireAt,omitempty"`
}

部署方式​

由于加密密钥使用了 Server Secret，加密算法的逻辑需在服务端实现，切勿在客户端部署加密方案。

使用方法​

游戏自己的鉴权服务器生成加密串后，下发给客户端，客户端调用加入房间的接口时传入相应的鉴权信息。

C# SDK 还提供了一个 GenToken 工具方法，供客户端接入 SDK 测试开发时使用。 比如，客户端开发人员可以在等待服务端开发人员实现、部署相应接口前先行在客户端测试加入房间的功能。 再比如，客户端开发人员可以比较 SDK 自带的 GenToken 生成的加密串和服务端生成的加密串是否一致，以便验证服务端正确实现了加密算法。

var authBuffer = AuthBufferHelper.GenToken(appId, roomId, userId, masterKey);

注意，由于这个方法需要传入 Server Secret 作为参数，因此仅供内部测试开发时使用，切勿在对外提供的代码或安装包中使用。 如果担心因为人为失误导致对外提供的代码或安装包中泄漏 Server Secret，或者出于安全考虑希望尽可能少的内部开发人员接触到 Server Secret，建议不使用 SDK 提供的 GenToken 方法，内部测试开发时也同样通过游戏自己的鉴权服务器生成加密串。

合规回调​

开发者在实时语音服务管理后台（开发者中心 > 你的游戏 > 游戏服务 > 实时语音 > 设置）设置回调地址后，语音内容有违规时会调用设置的回调地址。

回调地址需要是一个 HTTP(S) 协议接口的 URL，需要支持 POST 方法，传输数据编码采用 UTF-8。

回调的 POST body 示例：

{
    "HitFlag":true,
    "Msg":"不堪入目的消息内容",
    "ScanFinishTime":1634893736,
    "ScanStartTime":1634893734,
    "Scenes":[
        "default"
    ],
    "VoiceFilterPiece":[
        {
            "Duration":14000,
            "HitFlag":true,
            "Info":"不堪入目的消息内容",
            "MainType":"abuse",
            "Offset":0,
            "PieceStartTime":1634893734,
            "RoomId":"1234",
            "UserId":"123456",
            "VoiceFilterDetail":[
                {
                    "EndTime":0,
                    "KeyWord":"不堪入目的关键词",
                    "Label":"abuse",
                    "Rate":"0.00",
                    "StartTime":0
                }
            ]
        }
    ]
}

开发者可以在回调的 Header 中拿到 sign 字段，以便校验请求是否来自实时语音服务云端。

合规回调校验算法​

  1. 在回调的 POST body 前附加 POST 前缀，得到 payload：

    POST{"HitFlag":true,"Msg":"不堪入目的消息内容",/* 略 */}

    注意：

    • 请直接从 HTTP 请求体中读取 JSON 内容，反序列化到程序语言的数据结构可能会改变字段顺序，导致校验失败。
    • POST 和 body 直接连接，中间无空格。

  2. 对 payload 进行 HMAC-SHA1 加密，密钥为游戏应用的 Server Secret。

  3. 对上一步的结果进行 BASE64 编码，得到 sign。

  4. 和回调的 HTTP 头中的 sign 字段的值进行比较，相同则表明请求来自实时语音服务云端。

下面给出 Go 的示例代码供参考：

Go 示例
package main

import (
   "crypto/hmac"
   "crypto/sha1"
   "encoding/base64"
   "github.com/labstack/echo/v4"
   "io/ioutil"
   "net/http"
)


func testCallback(c echo.Context) error {
   sign := c.Request().Header.Get("sign")
   body, _ := ioutil.ReadAll(c.Request().Body)
   checkGMESign(sign, "yourMasterKey", string(body))
   return c.NoContent(http.StatusOK)
}


func checkGMESign(signature, secretKey, body string) bool {
   sign := genSign(secretKey, body)
   return sign == signature
}

func genSign(secretKey, body string) string {
   content := "POST" + body
   a := hmacSHA1(secretKey, content)
   return base64.StdEncoding.EncodeToString(a)
}

func hmacSHA1(key string, data string) []byte {
   mac := hmac.New(sha1.New, []byte(key))
   mac.Write([]byte(data))
   return mac.Sum(nil)
}

剔除玩家​

在一些场景下，游戏可能有从房间剔除玩家（踢人）的需求，比如涉及违规内容时。 开发者可以在自己的服务端调用实时语音服务的 REST API 接口实现这一需求。

请求格式​

对于 POST 和 PUT 请求，请求的主体必须是 JSON 格式，而且 HTTP Header 的 Content-Type 需要设置为 application/json。

请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的，参数如下表：

KeyValue含义来源
X-LC-Id{{appid}}当前应用的 App Id（即 Client Id）可在控制台查看
X-LC-Key{{masterkey}},master当前应用的 Master Key（即 Server Secret）可在控制台查看

Base URL​

REST API 请求的 Base URL（下文 curl 示例中用 {{host}} 表示）即应用的 API 自定义域名，可以在控制台绑定、查看。详见文档关于域名的说明。

REST API​

curl -X DELETE \
-H "Content-Type: application/json" \
-H "X-LC-Id: {{appId}}" \
-H "X-LC-Key: {{masterKey}},master" \
-d '{"roomId":"YOUR-ROOM-ID", "userId":"YOUR-USER-ID"}' \
https://{{host}}/rtc/v1/room/member

成功剔除时响应的 HTTP 状态码为 200，出错时响应的 HTTP 状态码为相应的错误码，例如没有权限时 HTTP 状态码为 401.

注意，剔除玩家后，玩家可以重新加入房间，加入房间后又可以发言。 游戏还需在自己的鉴权服务器上实现对应的封禁逻辑，相应玩家重新加入房间时不下发签名，以阻止玩家通过重新加入房间的方式绕开限制。