腾讯云在线K歌(KTV)

更新记录

5.2.0（2023-03-09）

升级IM SDK至版本7.0.3754;
升级TRTC SDK至版本10.9.0;

5.1.0（2022-08-22）

新增简单IM功能(内测);

5.0.0（2022-08-05）

升级IM SDK至版本6.5.2816;
升级TRTC SDK至版本10.4.0;
升级基础库;

平台兼容性

Android	Android CPU类型	iOS
适用版本区间：4.4 - 12.0	armeabi-v7a：未测试，arm64-v8a：未测试，x86：未测试	适用版本区间：9 - 16

原生插件通用使用流程：

购买插件，选择该插件绑定的项目。
在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

体验 KTV 的能力，包括低延时K歌、麦位管理、收发礼物、文字聊天等 TRTC 在 KTV 场景下的相关能力。支持以下功能：

房主创建新的 Karaoke 房间开播，听众进入 Karaoke 房间收听/互动。
房主可以管理点歌、将座位上的麦上主播踢下麦。
房主还能对座位进行封禁，其他听众就不能再进行申请上麦了。
听众可以申请上麦，变成麦上主播，上麦后可以点歌和唱歌，也可以随时下麦成为普通的听众。
支持发送礼物和各种文本、自定义消息，自定义消息可用于实现弹幕、点赞等。

接口模式(纯API)

扫描下方二维码，安装示例代码，快速体验插件功能:

Android	iOS	联系我们

扫码添加技术支持(微信号: ruanyunkeji006)，开通测试账号。

UI模式

扫描下方二维码，安装示例代码，快速体验插件功能:

Android	iOS	联系我们

扫码添加技术支持(微信号: ruanyunkeji006)，开通测试账号。

定制UI

扫码添加我们技术支持(微信号: ruanyunkeji006)，联系定制UI

技术支持

建议扫码添加我们技术支持，协助接入和测试。

联系我们	微信号	更多功能
	ruanyunkeji006	群组管理用户信息托管

API 接口文档

使用教程

快速开始

步骤1: 插件加载

加载插件

首先，uniapp平台的原生插件，需要自定义基座后才能使用，您可以按照自定义基座文档进行自定义基座操作。

新建nvue文件，注意该模块必须在nvue中使用。

插件名称为: RY-TencentTrtcKaraoke，使用标签

<view>
        <RY-TencentTrtcKaraoke ref="karaoke" v-bind:style = "{ width: playerWidth, height: playerHeight }"></RY-TencentTrtcKaraoke>
<view>

腾讯云配置

注册或登录腾讯云账号，并进行实名认证；
点击实时音视频，点击"创建应用"创建实时音视频应用。

生成签名

手动签名点击 UserSig生成&校验选择对应的sdkAppId的应用，输入userId，获取对应的用户签名userSig；

如果您需要【自动签名】，联系我们（微信号: ruanyunkeji006）获取。

步骤2: 插件初始化

必须调用 init 函数后，才可以使用插件个各个功能。

this.$refs.karaoke.init({}, ret => {
    console.log(ret);
});

步骤3: 设置监听

调用 setKaraokeListener 函数注册组件的事件回调。

this.$refs.karaoke.setKaraokeListener({}, ret => {
    console.log(ret);
});

步骤4: 登录

调用 login 函数完成组件的登录，请参考下表填写关键参数

var self = this
this.$refs.karaoke.login({
    sdkAppId: self.sdkAppId,
    userId: self.userId, 
    userSig: self.userSig
}, ret => {
        console.log(ret);
});

步骤5: 房主端开播

房主执行步骤4 登录后，可以调用 setSelfProfile 设置自己的昵称和头像。
房主调用 createRoom 创建新的 KTV 房间，此时传入房间 ID、上麦是否需要房主确认、麦位数等房间属性信息。
房主创建房间成功后，可以调用 enterSeat 进入座位。
房主收到组件的 onSeatListChange 麦位表变化事件通知，此时可以将麦位表变化刷新到 UI 界面上。
房主还会收到麦位表有成员进入的 onAnchorEnterSeat 的事件通知，此时会自动打开麦克风采集。

主播端开播

// 1.房主设置昵称和头像
this.$refs.karaoke.setSelfProfile({
    userName: 'Lucy',
    avatarUrl: 'http://xxx.cos.myqcloud.com/xxx.png'
}, ret => {
    // 结果回调
    console.log(ret);
});

// 2.房主端创建房间
this.$refs.karaoke.createRoom({
    roomId: 1234, 
    roomParam: {
        roomName: '房间名称',
        coverUrl: '封面Url',
        seatCount: 8, 
        setInfoList: [
            {
                userId: 'test001',
                mute: true,
                status: 0
            },
            ...
        ]
    }
}, ret => {
    console.log(ret);
    // 3. 创建房间成功后开始占座
    this.$refs.karaoke.enterSeat({
        seatIndex: 0
    }, ret => {
    if (ret.status) {
        // 房主占座成功
    } else {
        // 房主占座失败
    }
});
});

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 4.上麦成功后，收到 onSeatListChange 事件通知
        if ('onSeatListChange' == ret.eventType) {
            // 刷新您的麦位列表
        }
        // 5. 收到 onAnchorEnterSeat 事件通知
        if ('onAnchorEnterSeat' == ret.eventType) {
            // 处理房主上麦事件
        }
    }
});

步骤6: 听众端观看

听众端执行步骤4 登录后，可以调用 setSelfProfile 设置自己的昵称和头像。
听众端向业务后台获取最新的 KTV 房间列表。

说明：

App 中的 KTV 房间列表仅做演示使用，KTV 房间列表的业务逻辑千差万别，腾讯云暂不提供 KTV 房间列表的管理服务，请自行管理您的 KTV 房间列表。

听众端调用 getRoomInfoList 获取房间的详细信息，该信息是在房主端调用 createRoom 创建 KTV 房间时设置的简单描述信息。

注意：

如果您的 KTV 房间列表包含了足够全面的信息，可跳过调用 getRoomInfoList 相关步骤。

听众选择一个 KTV 房间，调用 enterRoom 并传入房间号即可进入该房间。
进房后会收到组件的 onRoomInfoChange 房间属性变化事件通知，此时可以记录房间属性并做相应改变，例如 UI 展示房间名、记录上麦是否需要请求房主同意等。
进房后会收到组件的 onSeatListChange 麦位表变化事件通知，此时可以将麦位表变化刷新到 UI 界面上。
进房后还会收到麦位表有主播进入的 onAnchorEnterSeat 的事件通知。

观众端观看

// 1.听众设置昵称和头像
this.$refs.karaoke.setSelfProfile({
    userName: 'test002',
    avatarUrl: 'http://xxx.cos.myqcloud.com/xxx.png'
}, ret => {
    // 结果回调
    console.log(ret);
});

// 2.假定您从业务后台获取房间列表为 roomIdList
// 3.通过调用 getRoomInfoList 获取房间的详细信息
this.$refs.karaoke.getRoomInfoList({
    roomIdList: [
        1234,
        ...
    ]
}, ret => {
    // 获取结果，此时可以刷新UI
    console.log(ret);
});

// 4. 传入 roomId 进入房间
this.$refs.karaoke.enterRoom({
  roomId: 1234,
}, ret => {
    // 进入房间结果回调
    console.log(ret);
    if (ret.status) {
        // 进房成功
    }
});

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 5.进房成功后，收到 onRoomInfoChange 事件通知
        if ('onRoomInfoChange' == ret.eventType) {
            // 可以更新房间名称等信息
        }

        // 6.进房成功后，收到 onSeatListChange 事件通知
        if ('onSeatListChange' == ret.eventType) {
            // 刷新麦位列表
        }

        // 7. 收到 onAnchorEnterSeat 事件通知
        if ('onAnchorEnterSeat' == ret.eventType) {
            // 处理上麦事件
        }
    }
})

步骤7: 麦位管理

房主端：

pickSeat 传入对应的麦位和听众 userId, 可以抱人上麦，房间内所有成员会收到 onSeatListChange 和 onAnchorEnterSeat 的事件通知。
kickSeat 传入对应麦位后，可以踢人下麦，房间内所有成员会收到 onSeatListChange 和 onAnchorLeaveSeat 的事件通知。
muteSeat 传入对应麦位后，可以静音/解除静音，房间内所有成员会收到 onSeatListChange 和 onSeatMute 的事件通知。
closeSeat 传入对应麦位后，可以封禁/解禁某个麦位，封禁后听众端将不能再上麦，房间内所有成员会收到 onSeatListChange 和 onSeatClose 的事件通知。

房主端

麦位操作后的事件通知顺序如下：callback > onAnchorEnterSeat 等独立事件。

// case 1: 房主抱人上1号麦位
this.$refs.karaoke.pickSeat({
    seatIndex: 1,
    userId: 'test001'
}, ret => {
    // 结果回调
    console.log(ret);
})

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 3.收到 onSeatListChange 回调，刷新您的麦位列表
        if ('onSeatListChange' == ret.eventType) {
            // 刷新的麦位列表
        }

        // 4.单个麦位变化的通知，可以在这里判断听众是不是真的上麦成功
        if ('onAnchorEnterSeat' == ret.eventType) {
            // 处理上麦事件
        }
    }
})

听众端:

enterSeat 传入对应的麦位后，可以进行上麦，房间内所有成员会收到 onSeatListChange 和 onAnchorEnterSeat 的事件通知。
leaveSeat 主动下麦，房间内所有成员会收到 onSeatListChange 和 onAnchorLeaveSeat 的事件通知。

观众端

麦位操作后的事件通知顺序如下：callback > onAnchorEnterSeat 等独立事件。

// case 2: 听众主动上2号麦位
this.$refs.karaoke.enterSeat({
    seatIndex: 2
}, ret => {
    // 上麦结果回调
});

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 3.收到 onSeatListChange 回调，刷新您的麦位列表
        if ('onSeatListChange' == ret.eventType) {
            // 刷新的麦位列表
        }

        // 4.单个麦位变化的通知，可以在这里判断是不是自己并进行相应处理
        if ('onAnchorEnterSeat' == ret.eventType) {
            // 处理上麦事件
        }
    }
});

步骤8：邀请信令使用

在麦位管理中，听众上下麦、房主抱人上麦都不需要经过对方的同意就可以直接操作。如果您的 App 需要对方同意才能进行下一步操作的业务流程，那么邀请信令可以提供相应支持。

听众主动申请上麦:

听众端调用 sendInvitation 传入房主的 userId 和业务的自定义命令字等，此时函数会返回一个 inviteId，记录该 inviteId。
房主端收到 onReceiveNewInvitation 的事件通知，此时 UI 可以弹窗并询问房主是否同意。
房主选择同意后，调用 acceptInvitation 并传入 inviteId。
听众端收到 onInviteeAccepted 的事件通知，调用 enterSeat 进行上麦。

听众主动申请上麦

// 听众(test002)视角
// 1.调用 sendInvitation，请求上1号麦位
this.$refs.karaoke.sendInvitation({
    cmd: 'ENTER_SEAT', 
    userId: 'test001',
    content: '1'
}, ret => {
    // 发送结果回调
    console.log(ret);
});

// 2.收到邀请的同意请求, 正式上麦
this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        if ('onInviteeAccepted' == ret.eventType) {
            if (ret.invitee == 'test002') {
                this.$refs.karaoke.enterSeat({}, ret => {
                    // 上麦结果回调
                    console.log(ret);
                });
            }
        }
    }
});

// 房主端test001视角
// 1.房主收到请求
this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        if ('onReceiveNewInvitation' == ret.eventType) {
            if (cmd == 'ENTER-SEAT') {
                // 2.房主同意听众请求
                this.$refs.karaoke.acceptInvitation({
                    inviteId: ret.inviteId
                }, ret => {
                    console.log(ret);
                });
            }
        }
    }
})

房主邀请听众上麦：

房主端调用 sendInvitation 传入听众的 userId 和业务的自定义命令字等，此时函数会返回一个 inviteId，记录该 inviteId。
听众端收到 onReceiveNewInvitation 的事件通知，此时 UI 可以弹窗并询问听众是否同意上麦。
听众选择同意后，调用 acceptInvitation 并传入 inviteId。
房主端收到 onInviteeAccepted 的事件通知，调用 pickSeat 抱听众上麦。

需要主播发送申请才能抱观众上麦

// 房主端视角
// 1.房主调用 sendInvitation，请求抱听众“123”上麦
this.$refs.karaoke.sendInvitation({
    cmd: 'PICK_SEAT',
    userId: '123',
    content: '2'
}, ret => {
    // 发送结果回调
    console.log(ret);
});

// 2.收到邀请的同意请求, 正式上麦
this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        if ('onInviteeAccepted' == ret.eventType) {
            if (inviteId = self.inviteId) {
                this.$refs.karaoke.pickSeat({
                    userId: '123'
                }, ret => {
                    // 上麦结果回调
                    console.log(ret);
                });
            }
        }
    }
});

// 听众端视角
// 1.听众收到请求
this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        if ('onReceiveNewInvitation' == ret.eventType) {
            if (ret.cmd == 'PICK_SEAT') {
                // // 2.听众同意房主请求
                this.$refs.karaoke.acceptInvitation({
                    inviteId: ret.inviteId
                }, ret => {
                    console.log(ret);
                });
            }
        }
    }
});

步骤9：实现文字聊天和弹幕消息

通过 sendRoomTextMsg 可以发送普通的文本消息，所有在该房间内的主播和听众均可以收到 onRecvRoomTextMsg 回调。即时通信 IM 后台有默认的敏感词过滤规则，被判定为敏感词的文本消息不会被云端转发

// 发送端：发送文本消息
this.$refs.karaoke.sendRoomTextMsg({
    msg: 'This is a msg'
}, ret => {
    console.log(ret);
});

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 接收端：监听文本消息
        if ('onRecvRoomTextMsg' == ret.eventType) {
            // 收到的message信息处理方法    
        }
    }
})

通过 sendRoomCustomMsg 可以发送自定义（信令）的消息，所有在该房间内的主播和听众均可以收到 onRecvRoomCustomMsg 回调。自定义消息常用于传输自定义信令，例如用于点赞消息的发送和广播。

// 例如：发送端：您可以通过自定义Cmd来区分弹幕和点赞消息
// eg:"CMD_DANMU"表示弹幕消息，"CMD_LIKE"表示点赞消息
this.$refs.karaoke.sendRoomCustomMsg({
    cmd: 'CMD_DANMU', 
    msg: 'hello world'
}, ret => {
    console.log(ret);
});
this.$refs.karaoke.sendRoomCustomMsg({
    cmd: 'CMD_LIKE', 
    msg: ''
}, ret => {
    console.log(ret);
});

this.$refs.karaoke.setKaraokeListener({}, ret => {
    if (ret.hasOwnProperty('eventType')) {
        // 接收端：监听自定义消息
        if ('onRecvRoomCustomMsg' == ret.eventType) {
            if ('CMD_DANMU' == ret.cmd) {
                // 收到弹幕消息
            }
            if（'CMD_LIKE' == ret.cmd) {
                // 收到点赞消息
            }
        }
    }
});