一段 96 BPM、4/4 的节拍声,可以让人跟着练习,却很难单独承担一节完整课程。鼓手希望两小节慢速热身、三小节标准练习,再用两小节较快速度收尾。如果靠手工拖动速度条,每次切换都会打断注意力;如果把三个 setInterval 接在一起,又可能发生上一段最后一拍和下一段第一拍重叠、页面离开后声音继续触发,或者卡顿恢复时一口气补发大量拍声。节拍训练真正需要的是一条可解释的练习时间线,而不是更多计时器。

《声律实验》前三篇已经实现 PulseCraft 的 BPM 与 3/4、4/4 参数、单通道 setTimeout 调度、runId 失效令牌,以及预加载 accent.ogg 和 tick.ogg 的 BeatSoundBank。本篇在这些基础上加入课程段落,保留短音池负责“发声”的单一职责。新的状态由 stageIndex、barIndex、pulseIndex 和预计算时间表构成,页面既能显示“现在第几段第几小节”,也能确定停止、重新开始和后台切换该做什么。文中的预期效果是前台练习播放器,不能把普通 UI 定时回调说成专业音频采样时钟。

声律实验分段课程的技术封面

一、从一个速度值变成一条可审查的课程时间线

单段节拍器只需一个 bpm 和 meter。但加入课程后,如果在 tick 回调里写很多条件:当 barIndex 等于二就修改速度、等于五就切换拍号,代码很快会把显示状态、业务结构与计时逻辑搅在一起。更稳妥的做法是把课程看成一组声明式段落,每段带名称、速度、拍号和小节数。一个具体的课程为“慢速热身:72 BPM、4/4、两小节”“稳定练习:96 BPM、4/4、三小节”“提速收尾:120 BPM、3/4、两小节”。总拍位是 8 + 12 + 6 = 26 次,最后一段结束后主动停表。

每一拍都可以先被展开成 PracticeMark:它记录所属段落、小节索引、拍内索引和从课程起点算起的目标毫秒数。切换段落时不修改另一只定时器的周期,只读取下一条拍位。这样,UI 显示与声音触发都来自同一条时间线,日志与问题定位也能使用相同编号。起点之后的目标时间应由过去所有拍位持续累加,不能在每次回调执行完之后再固定加 600ms 作为下一拍的依据,否则回调自身的迟到会不断积累进时间表。

// entry/src/main/ets/common/practice/PracticePlan.ets
export interface PracticeStage {
  title: string;
  bpm: number;
  meter: number;
  bars: number;
}
export interface PracticeMark {
  atMs: number;
  stageIndex: number;
  barIndex: number;
  beatIndex: number;
  bpm: number;
  strong: boolean;
}

export const TRAINING: PracticeStage[] = [
  { title: '慢速热身', bpm: 72, meter: 4, bars: 2 },
  { title: '稳定练习', bpm: 96, meter: 4, bars: 3 },
  { title: '提速收尾', bpm: 120, meter: 3, bars: 2 }
];

export function buildTimeline(stages: PracticeStage[]): PracticeMark[] {
  const result: PracticeMark[] = [];
  let elapsed: number = 0;
  stages.forEach((stage: PracticeStage, stageIndex: number) => {
    if (!Number.isFinite(stage.bpm) || stage.bpm < 40 || stage.bpm > 240 ||
        !Number.isSafeInteger(stage.bars) || stage.bars < 1 || stage.bars > 64 ||
        (stage.meter !== 3 && stage.meter !== 4)) {
      throw new Error('无效的练习段落参数');
    }
    for (let bar: number = 0; bar < stage.bars; bar++) {
      for (let beat: number = 0; beat < stage.meter; beat++) {
        result.push({ atMs: elapsed, stageIndex: stageIndex,
          barIndex: bar, beatIndex: beat,
          bpm: stage.bpm, strong: beat === 0 });
        elapsed += 60000 / stage.bpm;
      }
    }
  });
  return result;
}

这份纯数据函数非常适合独立测试。atMs 的值是相对课程起点的目标位置,不是实际扬声器发出的时间。段落换速不会丢失时间基准,而且每个 strong 都严格取自该小节内的零号拍。参数校验可以避免 BPM 为零造成除零、负小节造成空课程,或奇怪拍号与界面四个圆点数量不符。这里的节奏模型仍只支持 3/4 和 4/4;例如 6/8 的复合拍强弱关系需要另一套显示与重音策略,不应该把“六个圆点”直接等同于音乐上完整的 6/8 分组。

二、延迟的回调应该跳过旧拍,不能补放一串历史声音

UI 定时器不是实时调度器。HarmonyOS 的 Timer 文档明确提醒,setTimeout 受事件循环与后台挂起影响;即便要求零延时,也只是等下一个可执行时机。假设第二段中某个拍位预定于课程第 4.5 秒,但页面做了重排导致回调在 5.4 秒才被执行,直接播放这个旧拍再安排下一拍,会让整个课程向后拖。另一种极端做法是用循环立刻补出迟到的所有声音,听感则会出现一串无意义的“哒哒哒”。

本篇策略是忽略已经被后续拍位超越的历史事件:回调触发时计算课程已经过去的时间,找到此刻应该处理的最新一个拍位,丢弃更旧的事件;本次回调最多请求一次短音。因为课程总共只有 26 拍,查找过程成本可控;扩展成很长的课程时可以用时间索引二分查找。即使找到当前拍,也要判断是否超出了合理的迟到窗口;本版选择在迟到超过该拍正常间隔后只更新 UI,不再补放那次音。这个窗口是示例的产品取舍,不是假称 SoundPool 保证了音频精度。

// entry/src/main/ets/pages/Index.ets 中的关键增量成员
import { PracticeMark, PracticeStage, TRAINING, buildTimeline } from '../common/practice/PracticePlan';

@State private stageIndex: number = 0;
@State private barIndex: number = 0;
@State private pulseIndex: number = -1;
@State private courseHint: string = '等待开始';
@State private running: boolean = false;
private marks: PracticeMark[] = buildTimeline(TRAINING);
private cursor: number = 0;
private startedAt: number = 0;
private timerId: number = -1;
private runId: number = 0;

private queueNext(token: number): void {
  if (!this.running || token !== this.runId) { return; }
  if (this.cursor >= this.marks.length) {
    this.finishCourse(); return;
  }
  const delay: number = Math.max(0,
    this.startedAt + this.marks[this.cursor].atMs - Date.now());
  this.timerId = setTimeout(() => { this.tickCourse(token); }, delay);
}
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.cursor++; }
  const mark: PracticeMark = this.marks[this.cursor];
  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.soundOn && this.soundReady &&
      this.sounds !== null) {
    this.sounds.play(mark.strong).catch(() => {
      this.soundStatus = '音色播放失败';
    });
  }
  this.cursor++;
  this.queueNext(token);
}

代码延续第三篇的 soundOn、soundReady、soundStatus 和 sounds: BeatSoundBank | null,而不是创建第二份音频池。上一版的 queue()、tick()、step、nextDue 属于单段练习的具体调度实现;接入课程模式时应由 queueNext()、tickCourse() 取代,不应同时让两套定时链运行。这里依赖的是事件到达后追赶目标索引,不是物理时间逆转。由于 Date.now() 会随系统时间调整变化,正式音频训练可改用经核实的单调时间源或音频时钟;本版把这一点公开列为精度边界。

分段练习时间线和跳过过期拍位的技术图

三、停止、重启和离开页面必须共享同一个取消规则

一条容易被忽视的竞态是“停止后马上开始”。clearTimeout 撤掉了已登记的回调,却不能撤销一个已经进入执行过程的旧函数。如果只保留 running 布尔值,旧回调看到新一次开始后的 running=true,仍可能继续修改页面。runId 就是跨次运行的身份标记:每次停止递增,让旧回调在入口处失效;重新开始生成新的时间起点、新的 cursor 和新的计划。这样切换预设、点击停止、页面隐藏都复用同一套取消边界。

private startCourse(): void {
  if (this.running) { return; }
  this.stopCourse();
  this.marks = buildTimeline(TRAINING);
  this.cursor = 0;
  this.stageIndex = 0;
  this.barIndex = 0;
  this.pulseIndex = -1;
  this.startedAt = Date.now();
  this.courseHint = '课程进行中';
  this.running = true;
  const token: number = this.runId;
  this.queueNext(token);
}
private stopCourse(): void {
  this.runId++;
  if (this.timerId >= 0) { clearTimeout(this.timerId); }
  this.timerId = -1;
  this.running = false;
}
private finishCourse(): void {
  this.stopCourse();
  this.courseHint = '本轮课程完成';
}
onPageHide(): void { this.stopCourse(); }
aboutToDisappear(): void {
  this.stopCourse();
  const bank: BeatSoundBank | null = this.sounds;
  this.sounds = null;
  if (bank !== null) { bank.dispose().catch(() => {}); }
}

上述写法依赖第三篇已经建立的音效初始化逻辑:组件出现时用合法的 UIAbilityContext 调用 BeatSoundBank.prepare(),在两个 loadComplete 都到达之后才将 soundReady 置为真。它同样保留“音色失效也可以无声练习”的设计:soundReady=false 不会停止课程时间线,只是不执行 sounds.play()。如果新交互要求第一拍必须有声,应用可以在 soundReady 为假时禁用开始按钮,不要在计时器里不停重试加载音频。

段落之间没有重新加载音源,也不需要新建 SoundPool。强拍与弱拍仍按第 03 篇的规则区分;“加速收尾”的首拍是该段第一小节的重拍,而不是上一段四拍循环里的下一个圆点。页面隐藏后应停止本次练习,不把课程悄悄继续到后台;SoundPool 官方对后台播放与音频打断能力存在明确限制,本案例不能替代需要专业音频时间线的产品设计。

四、课程进度可读,比增加一个华丽的计时盘更重要

UI 采用“节拍工坊”作为页面标题,顶部显示“分段练习”,课程概览依次列出“慢速热身 72 BPM · 4/4 · 2 小节”“稳定练习 96 BPM · 4/4 · 3 小节”“提速收尾 120 BPM · 3/4 · 2 小节”。当前段落使用浅蓝背景高亮,下方显示“第 2 段 / 第 1 小节”和四个拍位圆点。进入三拍段落时只显示三个圆点,避免让用户误以为还存在第四拍。声音状态仍显示“音色已就绪”或“音色加载中”,但它只是资源状态,不等于系统音量或外部扬声器的实测结果。

// 插入 Index.build() 的 Column 中,接在页面主标题之后
Text('分段练习').fontSize(22).fontWeight(FontWeight.Bold)
ForEach(TRAINING, (stage: PracticeStage, i: number) => {
  Row() {
    Text(stage.title).fontSize(16)
    Text(`${stage.bpm} BPM · ${stage.meter}/4 · ${stage.bars} 小节`)
      .fontSize(13).fontColor('#627187')
  }
  .padding(14).width('100%')
  .backgroundColor(this.stageIndex === i ? '#E6EFFF' : '#F4F6FA')
  .borderRadius(14)
}, (stage: PracticeStage) => stage.title)
Text(this.courseHint).fontSize(17)
Row({ space: 12 }) {
  ForEach([0, 1, 2, 3].filter((i: number) =>
    i < TRAINING[this.stageIndex].meter), (i: number) => {
    Circle().width(22).height(22)
      .fill(this.pulseIndex === i ? '#375DFB' : '#CBD5E1')
  }, (i: number) => `${i}`)
}
Button(this.running ? '停止练习' : '开始课程')
  .onClick(() => { this.running ? this.stopCourse() : this.startCourse(); })

节拍工坊分段练习的竖屏效果设计

这里将课程数据直接用 ForEach 渲染,并用段落标题作为稳定 key。实际允许同名段落时应给 PracticeStage 增加不可重复的 id,不能假定标题总是唯一。课程列出的三段数据应当保持固定顺序,用户选择其他训练方案时先停止当前课程,再生成新时间线。选中项高亮与进度数字来自 stageIndex、barIndex,不会因为音源失败就突然跳回第一段;当用户手动停止时页面保留最近的进度供观察,但再次开始明确从头演奏。

五、用边界情形验证分段练习,别拿视觉圆点当音频证据

最基础的检查是把 TRAINING 交给纯函数 buildTimeline(),期望得到 26 条事件;每段的第一拍应是 strong=true,同小节后续拍都是 false。可计算出时间线长度来自 72、96、120 BPM 三段的每拍间隔累加,而不是把全部事件按固定 625ms 排队。手动将第三段改成 3/4 后,页面进入该段时显示三个圆点;恢复 4/4 则应显示四个。再把 BPM 设为零、把 bars 设为负数,预期立刻得到参数错误,而不是把异常状态交给定时器。

交互层面要覆盖“开始→立即停止→重新开始”和“播放中切到后台→重新打开页面”。旧回调令牌必须无法更新新会话;只有新的 startedAt 作为目标时间基准。可以在开发环境人为放入一段耗时操作,再观察恢复时是否只触发当前有效拍位,而不是挤出多声历史短音。最后将 tick.ogg 故意改错路径,确认音效报错不会阻止可视课程,页面销毁后不继续发起新的 play() 请求。任何“听起来很准”的感受都需要额外用录音设备和真实测量方法证明,不能单凭定时器回调输出的时间戳替代音频测量。

这篇实践的价值在于把单段节拍器升级成可以复现、可停止、可定位阶段的课程执行器:练习数据决定拍位表,单通道 Timer 仅负责尽可能接近目标时刻,SoundPool 只负责已加载短音的播放,UI 展示当前阶段且处理明确的停表事件。其边界也清楚:适合教学示例和一般前台节奏辅助,不宣称专业低抖动音频基准。下一篇可在此基础上讨论课程预设持久化、用户自定义段落与异常恢复,但不应把本篇的 TRAINING 写成无法维护的硬编码分支。相关能力见华为官方 SoundPool API、SoundPool 使用指南及 Timer API,目标工程可采用 API 12 Stage 项目并以 DevEco Studio 对应 SDK 校验实际类型与运行行为。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐