ArkTS + HarmonyOS 声律实验(第 5 讲):拍位事件账本与练习复盘【共创稿事节】

节拍器里最容易做错的一张图,是一张看起来特别漂亮的“准确率”图。只要看到圆点亮起就统计一次成功,甚至把 SoundPool.play() Promise 返回当作“用户听到一个准时的拍”,数字就会既精确又不可信。此前“声律实验”已经把基础 BPM 参数、定时漂移修正、强弱拍短音、分段课程及拍位跳过组合成一条演奏路径。到了第五篇,真正需要的不是再加一个音频特效,而是建立可解释的事件账本:什么时候计划发声,什么时候实际进入回调,什么情况下因为迟到而主动跳过。
本次选择实验研究与故障分析结合的写法。核心目标是把“触发调用次数”“因为迟到跳过的次数”“因静音或音色未就绪而未触发的次数”“发声请求抛错次数”分开统计。它不测量麦克风接收到的声音,也不声称检测到了输出设备的真实延迟。该区分影响整个产品的可信度:应用能知道自己发出了一个播放请求,却不能仅凭这件事证明声波何时抵达耳朵。
一、先定义有证据的观测语义
第四篇中 PracticeMark 包含 atMs、stageIndex、barIndex、beatIndex、bpm、strong。既然时间线已经建好,报告就不应另造一个拍位数组。每个计划拍位拥有由时间线下标构成的稳定键,结果分为四类:attempted 表示已调用播放方法;late 表示回调到来时已经错过允许窗口;muted 表示用户关闭声音或音源尚未准备;failed 表示播放请求返回异常。attempted 不等于音频设备确认实际发声。
// entry/src/main/ets/common/practice/PracticeReport.ets
import { PracticeMark } from './PracticePlan';
export type BeatOutcome = 'attempted' | 'late' | 'muted' | 'failed';
export interface BeatEvent {
index: number;
stageIndex: number;
barIndex: number;
beatIndex: number;
plannedMs: number;
observedMs: number;
outcome: BeatOutcome;
}
export interface StageSummary {
stageIndex: number;
planned: number;
attempted: number;
late: number;
muted: number;
failed: number;
}
export function summarize(
marks: PracticeMark[], events: BeatEvent[], stageCount: number
): StageSummary[] {
const result: StageSummary[] = [];
for (let stage: number = 0; stage < stageCount; stage++) {
result.push({ stageIndex: stage, planned: 0,
attempted: 0, late: 0, muted: 0, failed: 0 });
}
for (const mark of marks) { result[mark.stageIndex].planned++; }
for (const event of events) {
const row = result[event.stageIndex];
if (event.outcome === 'attempted') { row.attempted++; }
else if (event.outcome === 'late') { row.late++; }
else if (event.outcome === 'muted') { row.muted++; }
else { row.failed++; }
}
return result;
}
这个结构也解释了为什么不能直接写 successRate = attempted / planned。planned 包含尚未走到的后续拍位,练习未结束时分母天然更大;而且 attempted 是请求,绝不是硬件输出证据。界面可显示“计划拍位”“已触发调用”“迟到跳过”等具体指标,避免容易误导人的“节奏准确率”。对于已结束课程,可检查四类结果总和是否等于实际处理拍位数量;对尚在运行的课程,则明确显示“已处理 / 总计划”。

在设计报表之前,还应先约束事件内容的最小可解释性。plannedMs 与 observedMs 采用同一练习开始时刻作为零点,因此可以比较相对差值;它们不是 Unix 时间戳,也不应被直接打印成某年某月某日。barIndex 与 beatIndex 延续代码中的零起始约定,展示给用户时才加一。事件结果不要保存可识别的个人声音或录音文件,它们对这类节拍练习并无必要;只记录拍位的业务状态就足以重放统计逻辑,也更容易控制存储和排查权限范围。
另一个不可偷换的概念是“漏拍”。当页面退到后台或主线程繁忙时,计划时间点可能过去,但回调并没有按照每个标记分别执行。把每个已经越过的 PracticeMark 记录为 late,能解释为什么视觉上出现了跳步,却不会假装系统真的执行了这些过期回调。若把“尚未执行”的拍位也写成漏拍,那么课程刚开始时准确率就会被推到很低;若不记录过期拍位,用户又无法理解回到前台后为什么突然从第一段跳到第三段。账本是产品解释机制,而不是单纯计数器。
二、在旧调度器旁边记账,不让记账决定下一拍
真正的时序约束是“先确定应触发的拍位,再决定是否发声,然后记录事件”。不能为了统计而把音频播放放到 await 队列后面等待,否则统计逻辑反而改变拍点。这里沿用第四篇 marks、cursor、startedAt、runId、queueNext()、sounds、soundOn、soundReady,只把 tickCourse() 更新为带事件采集的版本。需要强调:若多个拍位已过期,旧拍位只记 late,不补放历史短音。这是实时节拍器,而非离线音频渲染器。
// entry/src/main/ets/pages/Index.ets:增量成员与替换方法
@State private beatEvents: BeatEvent[] = [];
@State private reportHint: string = '尚未开始记录';
private markEvent(index: number, outcome: BeatOutcome, now: number): void {
const mark: PracticeMark = this.marks[index];
const event: BeatEvent = {
index: index, stageIndex: mark.stageIndex, barIndex: mark.barIndex,
beatIndex: mark.beatIndex, plannedMs: mark.atMs,
observedMs: now, outcome: outcome
};
this.beatEvents = [...this.beatEvents, event];
}
private setFailed(index: number): void {
this.beatEvents = this.beatEvents.map((e: BeatEvent): BeatEvent =>
e.index === index && e.outcome === 'attempted'
? { ...e, outcome: 'failed' } : e);
}
private tickCourse(token: number): void {
if (!this.running || token !== this.runId) { return; }
const now: number = Date.now() - this.startedAt;
while (this.cursor + 1 < this.marks.length &&
this.marks[this.cursor + 1].atMs <= now) {
this.markEvent(this.cursor, 'late', now);
this.cursor++;
}
const index: number = this.cursor;
const mark: PracticeMark = this.marks[index];
const interval: number = 60000 / mark.bpm;
this.stageIndex = mark.stageIndex;
this.barIndex = mark.barIndex;
this.pulseIndex = mark.beatIndex;
this.courseHint = `第 ${mark.stageIndex + 1} 段 / 第 ${mark.barIndex + 1} 小节`;
if (now - mark.atMs >= interval) {
this.markEvent(index, 'late', now);
} else if (!this.soundOn || !this.soundReady || this.sounds === null) {
this.markEvent(index, 'muted', now);
} else {
this.markEvent(index, 'attempted', now);
this.sounds.play(mark.strong).catch(() => {
this.failedForRun(index, token);
});
}
this.cursor++;
this.reportHint = `已处理 ${this.beatEvents.length} / ${this.marks.length} 拍`;
this.queueNext(token);
}
markEvent 是最简单也最可靠的边界:它只负责记录,不调用音频引擎,也不延迟下一次定时器。setFailed 采用按 index 更新,不让一次 Promise 拒绝错误地修改当前正在播放的另一拍。实务上应进一步把 runId 一并写入事件,防止结束旧练习后其异步 Promise 才拒绝、导致新练习同下标记录误标为失败;若还存在旧 Promise,应按练习会话令牌过滤。此处为篇幅聚焦,额外保护在下面明确给出。
// Index.ets:在正式工程中按会话令牌保护异步回报
private failedForRun(index: number, token: number): void {
if (token !== this.runId) { return; }
this.setFailed(index);
}
上面的异步回报采用 failedForRun,只在会话令牌仍匹配时更新对应事件。开始新课程之前应先 runId++、取消旧定时器,再清空 beatEvents;停止时同样让旧回调失效。特别是暂停或手动结束,应把尚未处理的计划拍位标为“未执行”,而不是自动补记为 late;否则报告把用户主动停止误判为调度迟到。
三、把账本折叠成能读懂的阶段复盘
第四篇的训练表是三段:慢速热身 为 72 BPM、4/4 拍、2 小节;稳定练习 为 96 BPM、4/4 拍、3 小节;提速收尾 为 120 BPM、3/4 拍、2 小节。计划拍位总数恰好是 2×4 + 3×4 + 2×3 = 26,其中每小节第一拍为强拍,因此强拍总数是 2+3+2=7。这两个数只是课程配置的确定性结果,不是帧率、系统延迟或音频输出实测。
// Index.ets:可计算属性与 ArkUI 呈现片段
private get summaries(): StageSummary[] {
return summarize(this.marks, this.beatEvents, TRAINING.length);
}
@Builder
private summaryPanel() {
Column({ space: 10 }) {
Text('练习复盘').fontSize(22).fontWeight(FontWeight.Bold)
Text(this.reportHint).fontSize(14).fontColor('#596B7D')
ForEach(this.summaries, (row: StageSummary) => {
Column({ space: 4 }) {
Text(TRAINING[row.stageIndex].title).fontSize(18)
Text(`计划 ${row.planned} 拍 · 触发 ${row.attempted} 拍`)
Text(`迟到 ${row.late} · 静音 ${row.muted} · 请求失败 ${row.failed}`)
.fontSize(14).fontColor('#536476')
}.padding(12).backgroundColor('#F2F5FB').borderRadius(14)
}, (row: StageSummary) => `${row.stageIndex}`)
}.width('100%').alignItems(HorizontalAlign.Start)
}
要让统计对用户有价值,页面还需清楚区分“运行中”和“课程已结束”。运行中可以看到某段已处理几拍,未到达的时间线不应提前填为 0 次失败;结束后才将完整计划与处理量比较。若静音练习是用户主动选择,muted 不是异常;如果声源未就绪则应显示独立提示,而不是默默用静音数覆盖资源故障。为了让界面不被细节淹没,主面板放四个核心指标,具体事件列表留给可展开的诊断区。

展示层要克制地避免“百分比崇拜”。在课程尚未结束时,以 已处理 15 / 26 拍 说明时间线进度;在课程结束时,以四个互斥结果的绝对数量说明应用曾经做过什么。如果确实想提供比例,分母应该是已经处理的拍位,而非全部未来计划拍位,并且名称必须是“触发调用占比”,绝不能直接写成“音频准确率”。这种措辞不是挑剔,它决定用户是否会把程序内部执行统计误认为训练效果评估。
这里采用 ForEach 显示三个 StageSummary,每个 stageIndex 都是稳定且唯一的 key。阶段数很少,简单渲染足够;若以后要展示数千条事件,则应将详情列表切换为适合大量数据的惰性加载策略,并采用可控的状态更新节奏,避免每拍重新构建整张长列表。主界面的统计频率也无需快于真实的节拍事件发生频率,反复安排额外计时器只会增加页面生命周期的负担。

四、异常路径是统计设计的一部分
官方 Timer 文档指出,界面退到后台后定时器触发机制可能被冻结;回到前台,过期回调的处理顺序与延迟就不能当作恒定实时保证。这正是记录 late 的依据,而不是去编造毫秒级“精度测试”。setTimeout 本身是一次性回调,调度轮次需要明确取消;沿用第三、四篇的 runId 可防止老回调改变新会话状态。参考 Timer 官方接口 与 SoundPool 短音播放指南。
更隐蔽的失败是音色加载状态和 UI 状态不一致。若 soundReady 尚未变真,定时器仍可把拍位推进,但必须记为 muted 并给出“音色未就绪”的诊断,而不是同时报“触发成功”。若播放请求发出后 Promise 拒绝,事件应从 attempted 更新为 failed,并记录该拍位序号而不是整个课程的总报错次数。若声音真的播放了但手机蓝牙输出存在延迟,这套账本仍然无法证实物理声学延迟。需要测得它,就必须另行设计有授权、可复现的音频回采实验,不能拿 UI 的时间戳凑数。
可以用纯函数的测试向量给 summarize 做第一层自测:当全部 26 拍都记录为 attempted,各段结果应分别是 8、12、6 次触发;当第 3 拍和第 4 拍标为 late,首段迟到数应为 2、触发数为 6。再构造课程一半时主动停止的情况,只处理到的事件进入分组,剩余计划拍位既不是 late,也不是 failed。对事件重复上报,应由 index + runId 共同实现幂等保护;离线测试如果发现同一会话同一拍位两条事件,说明需要检查 cursor 与重入路径。
进行异常测试时建议固定三条可复现路径。第一条是课程运行一小段后主动停止,检查 runId 增加、旧定时器清理、最后一条记录仍归属旧会话;第二条是临时关闭声音,观察拍位继续推进但事件结果变为静音;第三条是用可控制的回调延迟构造前台繁忙,检查跨越多个计划时间时是否只对当前仍在窗口内的拍位调用音频,而过期拍位均被记账。三条用例覆盖的并不是“播放音质”,而是调度、状态与诊断之间的契约。这里能实现的是逻辑验收,真实音频输出仍需要设备端另行验证。
还应加入记录容量保护。即使单次课程只有 26 个标记,长期连续保存多个会话后,数组同样可能增长。为每个会话规定有限的事件数量,保存时记录 schema 和来源课程摘要,比无限追加到一个 Preferences 字符串更可靠。本篇暂不持久化,避免把尚不稳定的事件语义固化到长期数据格式中;第六篇再为会话 ID、旧记录升级与清理策略设计正式存储协议。
五、可以交付什么,不能把什么写进结论
这次新增的真正产物是一个可审查、可归因、可重算的练习过程模型。它与 UI 互相独立:事件可以用纯函数折叠成报表,也可以在测试中逐项比较;UI 可以换成条形图、数字卡片或完整列表,而不必修改调度器。已有的 SoundPool 继续负责短音,定时器继续根据目标时间选择当前拍位,记录逻辑不取代它们。
但边界同样重要。一个被统计为 attempted 的拍位只意味着软件调用了播放入口,它没有证明声音播放成功、没有证明用户听到了、没有证明节奏医学或训练上的准确性。界面上展示的是示例课程及代码所定义的状态,而不是设备现场测得的音频性能。下一篇将把异步会话隔离、练习记录持久化和最终工程验收接起来,再讨论产品该如何安全地保存、恢复与清理训练结果。
更多推荐

所有评论(0)