KTV打分组件接入文档

1. 总览和功能

KTV打分组件为K歌应用提供实时打分功能，支持两种样式：

2.0版本（旧样式）：基于MidiScoreView的传统打分界面

3.0版本（新样式）：基于SingIntonationViewer的现代化打分界面，支持更炫的效果

打分功能分为两种模式：

普通打分：提供总分和单句分数

五维打分：提供总分、音准、节奏、技巧、气息、情感五个维度的分数

2. 2.0版本打分组件（旧样式）

2.1 布局中添加MidiScoreView

在播放页布局中添加MidiScoreView组件：

<FrameLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <com.tme.ktv.midi.MidiScoreView
        android:id="@+id/midi_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:layout_marginBottom="130dp"/>
</FrameLayout>

2.2 初始化配置Activity

在Activity中初始化MidiScoreView并设置Activity：

2.3 回调事件中MidiScoreView响应

2.3.1 实现打分回调监听器

2.3.2 实现播放器回调监听器

2.3.3 添加监听器到播放器

2.4 MidiView修改配置

2.4.1 打分条配置

自定义打分条布局：

打分条可以根据 KaraokePlayer 的打分回调 OnScoreListener自定义实现
ScoreBarView.setLayoutResId 支持应用传入layout, layout 布局参考 layout_karaoke_score_level.xml，可以在这个layout 基础上修改，只支持修改布局属性，控件ID 需要保持不变。

获取ScoreBarView并修改属性：

2.4.2 音高数据配置

修改音高数据的背景和画笔风格：

2.5 打分开关

判断歌曲是否支持五维打分：

3. 3.0版本打分组件（新样式）

3.1 布局中添加打分View

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/intonation_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:background="@android:color/transparent"
        android:clipToPadding="false"
        android:clipChildren="false"
        tools:ignore="MissingDefaultResource">

    <com.tme.ktv.intonation.view.PerfectAnimView
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:id="@+id/karaoke_perfect_view"
            />

    <com.tme.ktv.intonation.view.SimpleScoreBar
            android:focusable="false"
            android:id="@+id/pk_score_bar"
            android:layout_width="match_parent"
            android:layout_height="45dp"
            android:layout_marginStart="@dimen/pk_score_layout_margin_left"
            android:layout_marginTop="160dp" />

    <com.tme.ktv.intonation.SingIntonationViewer
            android:id="@+id/player_float_intonation_viewer"
            android:layout_width="match_parent"
            android:layout_height="80dp"
            android:layout_gravity="bottom"
            android:layout_marginStart="30dp"
            android:layout_marginEnd="30dp"
            android:layout_marginBottom="130dp" />
</FrameLayout>

3.2 初始化打分辅助类

3.3 设置打分回调

（代码中isPollMode 是用于多屏一起唱的场景，如果不涉及直接把isPollMode认为false 不需要这个分支的逻辑）
注意：即使设置了开启五维打分也要同时设置普通打分的回调，因为部分歌曲支持打分但是不支持五维打分，此时会自动回落到普通打分。

3.3.1 实现打分回调监听器

3.3.2 实现播放器回调监听器

3.3.3 添加监听器到播放器

4. 五维打分功能

五维打分提供更丰富的评分维度，包括：

音准分数：lastStableScore / finalStableScore

节奏分数：lastRhythmScore / finalRhythmScore

技巧分数：skillScore / finalSkillScore

气息分数：lastLongToneScore / finalLongToneScore

情感分数：dynamicScore / finalDynamicScore

4.1 使用五维打分

确保已开启五维打分：

在onDoingMultiScore回调中处理五维分数数据

在onMultiScoreFinish回调中处理最终五维分数

4.2 分数等级计算规则

分数等级按照单句平均分来定级：

注意：使用打分功能，需要把 songtype设置为SONG_TYPE_K_SONG 录唱模式，其他模式不支持打分

5. 2.0打分文档补充

5.1 初始化配置Activity

mMidiScoreView.setActivity(this) 这个Api 需要设置，不然影响动画

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    mMidiScoreView = this.findViewById(R.id.midi_view);
    mMidiScoreView.setActivity(this);

5.2 Callback 事件中 MidiScoreView 响应

private class ScoreListenerImpl extends KaraokePlayer.OnScoreListener{

    @Override
    protected void onPrepareScore(SingCompetitor competitor, int nums) {
        //获取到节拍数据，设置给midiView，其中 nums是打分的总句子数，不一定等于歌词行数
        mMidiScoreView.initData(competitor);
    }
   //普通打分单句回调
    @Override
    protected void onDoingScore(int score, String level, int timeStamp) {
        //普通打分的单句实时打分结果，数值和等级
        mIntonationDelegate?.postUpdateScore(score,timeStamp.toFloat(),null)
    }
//普通打分回调
    @Override
    protected void onFinishScore(int totalScore, String level) {
       //普通打分演唱结束后的总分结果
    }
   
       /** 
         *五维打分回调
         * 每唱完一句出一次分数,上一句就是刚唱完的那一句
         * @param lastScore 上一句的分数
         * @param timeStamp 时间戳
         * @param lastLongToneScore 上一句的气息分数
         * @param lastRhythmScore 上一句的节奏分数
         * @param lastStableScore 上一句的音准分数
         * @param dynamicScore 上一句的情感分数
         * @param skillScore 上一句的技巧分数
         * @param lastSkillTrillCount 上一句命中的颤音个数
         * @param lastSkillGlintCount 上一句命中的滑音个数
         * @param lastSkillTransliterationCount 上一句命中的转音个数
         */
        public void onDoingMultiScore(int lastScore, long timeStamp, int lastLongToneScore, int lastRhythmScore,
                                      int lastStableScore, int dynamicScore, int skillScore,
                                      int lastSkillTrillCount, int lastSkillGlintCount,
                                      int lastSkillTransliterationCount) {
                        //五维打分实时回调
                        multiScoreResultInfo.resetLastScore()
                        multiScoreResultInfo.lastLongToneScore = lastLongToneScore
                        multiScoreResultInfo.lastRhythmScore = lastRhythmScore
                        multiScoreResultInfo.lastStableScore = lastStableScore
                        multiScoreResultInfo.lastDynamicScore = dynamicScore
                        multiScoreResultInfo.lastSkillScore = skillScore
                        multiScoreResultInfo.lastSkillTrillCount = lastSkillTrillCount
                        multiScoreResultInfo.lastSkillTransliterationCount = lastSkillGlintCount
                        mIntonationDelegate?.postUpdateScore(lastScore, timeStamp.toFloat(), multiScoreResultInfo)
        }


       /** 
         * 五维打分结束回调
         * @param finalLongToneScore 气息分数
         * @param finalRhythmScore 节奏分数
         * @param finalStableScore 音准分数
         * @param finalDynamicScore 情感分数
         * @param finalSkillScore 技巧分数
         * @param lastSentenceIndex 最后一句歌词的索引
         * @param totalSentences 这首歌的句子数
         */
        public void onMultiScoreFinish(int finalLongToneScore, int finalRhythmScore, int finalStableScore,
                                       int finalDynamicScore, int finalSkillScore, int lastSentenceIndex,
                                       int totalSentences) {
        }
}
    inner class KtvMidiCallbackImpl : KaraokePlayerListener() {

        private fun startMidiView() {
            if (KtvPlayerConfig.getInstance().isEnableScore) {
                log("startMidiView")
                midiView.startMidi(viewModel.currPlayer()?.timeLineTime ?: 0)
            }
        }

        private fun stopMidiView() {
            midiView.stopMidi()
        }

        override fun onPlayStart(request: KaraokePlayRequest) {
            log("onPlayStart:$request")
            if (request.songInfoObject.mNoteBytes == null && request.songInfoObject.songType == SongType.SONG_TYPE_K_SONG) {
                log("current song has no noteBytes, close score")
                if (MediaProperties.get().isEnableScore) {
                    PlayConsole.get().setScoreOpen(false)
                    KGToast.show("该歌曲不支持打分，已为您关闭打分")
                }
            }
        }

        override fun onLyricResourceChanged(request: KaraokePlayRequest) {
            super.onLyricResourceChanged(request)
            stopMidiView()
            startMidiView()
        }

        override fun onResume(mKtvPlayRequest: KaraokePlayRequest) {
            log("call onResume")
            startMidiView()
        }

        override fun onPause(mKtvPlayRequest: KaraokePlayRequest) {
            log("onPause")
            stopMidiView()
        }

        override fun onPlayEnd(request: KaraokePlayRequest, endInfo: PlayEndInfo) {
            Log.e(TAG, "onPlayEnd")
            mHandler.post {
                stopMidiView()
                midiView.releaseMidi()

                val openScore =
                    viewModel.currSongInfo().value?.mNoteBytes != null && viewModel.currSongInfo().value?.songType == SongType.SONG_TYPE_K_SONG
                if (!openScore && endInfo.isPlayFinish) {
                    playNextIfNeed()
                }
            }
        }

        override fun onSeekComplete(request: KaraokePlayRequest, position: Long) {
            log("onPlayPositionChange currentTime $position ")
            midiView.seekMidi(position)
        }

        override fun onBufferingStart(request: KaraokePlayRequest?) {
            stopMidiView()
        }

        override fun onBufferingEnd(request: KaraokePlayRequest?) {
            startMidiView()
        }
    }


 需要把两个实现添加到播放器中
 karaokePlayer.addCallback(CallbackImpl())  
 karaokePlayer.addOnScoreListener(ScoreListenerImpl())

5.3 MidiView 修改配置

音高数据

音高数据支持修改背景和画笔风格

MidiScoreView.getIntonationViewGroup().getIntonationView().getIntonationViewerParam();

IntonationViewerParam 画笔如下

更改midiView的高度背景色打分条的画笔颜色粗细
例如：在midiView的界面内，获取到MidiScoreView后：

        val intonationViewerParam = midiView.intonationViewGroup.intonationView.intonationViewerParam

        midiView.midiViewHeight = DisplayUtil.dp2px(140f)
        midiView.midiViewBackgroundColor = getActivity()?.resources?.getColor(R.color.ktv_brown) ?: -1

        val missPaint = Paint()
        missPaint.color = Color.parseColor("#234512")
        missPaint.strokeWidth = DisplayUtil.dp2px(8.0F).toFloat()
        intonationViewerParam.noteMissPaint = missPaint

        val hitPaint = Paint()
        hitPaint.color = Color.parseColor("#666666")
        hitPaint.strokeWidth = DisplayUtil.dp2px(8.0F).toFloat()
        intonationViewerParam.noteHitPaint = hitPaint

6. 重要注意事项

歌曲类型设置：使用打分功能必须将songType设置为SONG_TYPE_K_SONG（录唱模式），其他模式不支持打分。

歌词配置：确保正确设置歌词信息，否则无法打分：

轮询模式：3.0版本支持轮询模式（isPollMode），用于多屏一起唱的场景。在轮询模式下，需要实现ScoreResultRequester接口来获取打分数据。

兼容性处理：即使设置了开启五维打分，也要同时设置普通打分的回调，因为部分歌曲支持打分但不支持五维打分，此时会自动回落到普通打分。

Activity设置：2.0版本中必须调用MidiScoreView.setActivity(this)，否则会影响动画效果。

资源释放：在播放结束或Activity销毁时，确保调用releaseMidi()释放资源。

歌曲支持判断：通过songInfoObject.mNoteBytes是否为null判断歌曲是否支持打分，通过songInfoObject.mOriginalMultiScoreContent是否为null判断歌曲是否支持五维打分。

KtvSDK-打分

KTV打分组件接入文档#

1. 总览和功能#

2. 2.0版本打分组件（旧样式）#

2.1 布局中添加MidiScoreView#

2.2 初始化配置Activity#

2.3 回调事件中MidiScoreView响应#

2.3.1 实现打分回调监听器#

2.3.2 实现播放器回调监听器#

2.3.3 添加监听器到播放器#

2.4 MidiView修改配置#

2.4.1 打分条配置#

2.4.2 音高数据配置#

2.5 打分开关#

3. 3.0版本打分组件（新样式）#

3.1 布局中添加打分View#

3.2 初始化打分辅助类#

3.3 设置打分回调#

3.3.1 实现打分回调监听器#

3.3.2 实现播放器回调监听器#

3.3.3 添加监听器到播放器#

4. 五维打分功能#

4.1 使用五维打分#

4.2 分数等级计算规则#

5. 2.0打分文档补充#

5.1 初始化 配置Activity#

5.2 Callback 事件中 MidiScoreView 响应#

5.3 MidiView 修改配置#

音高数据#

6. 重要注意事项#