first commit

TUICallKit-Vue3/training/hooks/useMetronome.ts

@@ -0,0 +1,278 @@
+import { ref, computed, onUnmounted } from 'vue'
+
+export interface MetronomeOptions {
+    initialBpm?: number
+    bpmMin?: number
+    bpmMax?: number
+    clickSrc?: string
+    accentSrc?: string
+    accentEvery?: number
+    poolSize?: number
+    volume?: number  // 节拍音音量 0-1
+    silent?: boolean // 静音模式:只驱动节拍回调,不发声(如握力环只需视觉节拍)
+    onBeat?: (beatIndex: number, isAccent: boolean) => void
+}
+
+/**
+ * 音频实例池：每个 click 用一个独立 InnerAudioContext，循环复用。
+ * 解决两个问题：
+ *  1. seek+play 模式在某些设备上首拍冷启动延迟（100-300ms）
+ *  2. BPM 偏快时上一拍音频还没播完，下一拍 play 会被阻塞或丢失
+ */
+class AudioPool {
+    private list: UniApp.InnerAudioContext[] = []
+    private cursor = 0
+    private warmedUp = false
+    private targetVolume = 1
+
+    constructor(
+        private src: string,
+        private size: number,
+        volume = 1,
+    ) {
+        this.targetVolume = volume
+    }
+
+    private create() {
+        for (let i = 0; i < this.size; i++) {
+            const ctx = uni.createInnerAudioContext()
+            ctx.src = this.src
+            ctx.obeyMuteSwitch = false
+            ctx.autoplay = false
+            ctx.volume = this.targetVolume
+            this.list.push(ctx)
+        }
+    }
+
+    setVolume(volume: number) {
+        this.targetVolume = Math.max(0, Math.min(1, volume))
+        this.list.forEach((ctx) => {
+            try {
+                ctx.volume = this.targetVolume
+            } catch (_) {}
+        })
+    }
+
+    /**
+     * 预热：短暂播放,让音频文件下载/解码到内存
+     * 真正首次 play 不会再卡冷启动
+     */
+    warmUp() {
+        if (this.warmedUp) return
+        if (this.list.length === 0) this.create()
+
+        this.list.forEach((ctx) => {
+            try {
+                ctx.volume = 0 // 静音预热,避免进入页面时响声
+                ctx.play()
+                setTimeout(() => {
+                    try {
+                        ctx.stop()
+                        ctx.volume = this.targetVolume // 恢复目标音量
+                    } catch (_) {}
+                }, 60)
+            } catch (_) {}
+        })
+        this.warmedUp = true
+    }
+
+    play() {
+        if (this.list.length === 0) {
+            this.create()
+            this.warmUp()
+        }
+        const ctx = this.list[this.cursor]
+        this.cursor = (this.cursor + 1) % this.list.length
+        try {
+            // 强制停止所有正在播放的音频，避免重叠
+            this.list.forEach(c => {
+                try { c.stop() } catch (_) {}
+            })
+            // iOS 上 seek(0) + play() 不一定能从头播放;stop() + play() 更稳
+            ctx.play()
+        } catch (_) {
+            try { ctx.play() } catch (__) {}
+        }
+    }
+
+    destroy() {
+        this.list.forEach((ctx) => {
+            try {
+                ctx.destroy?.()
+            } catch (_) {}
+        })
+        this.list = []
+        this.warmedUp = false
+    }
+}
+
+/* InnerAudio 兼容本地路径和网络 URL,这里默认走 CDN,跟 BgAudio 保持一致便于维护
+   首次播放会下载 ~3KB,实测 100~300ms 完成,然后小程序会缓存,后续触发零延迟 */
+const DEFAULT_CLICK_SRC =
+    'https://gz-1349751149.cos.ap-guangzhou.myqcloud.com/uploads/file/20260526/20260526105128557ef8669.mp3'
+
+export function useMetronome(options: MetronomeOptions = {}) {
+    const {
+        initialBpm = 80,
+        bpmMin = 40,
+        bpmMax = 240,
+        clickSrc = DEFAULT_CLICK_SRC,
+        accentSrc,
+        poolSize = 4,
+        volume = 1,
+        silent = false,
+        onBeat,
+    } = options
+
+    const bpm = ref<number>(initialBpm)
+    const isPlaying = ref<boolean>(false)
+    const beatIndex = ref<number>(0)
+    const isAccent = ref<boolean>(false)
+    const accentEveryRef = ref<number>(options.accentEvery ?? 4)
+
+    const intervalMs = computed(() => 60000 / bpm.value)
+
+    let clickPool: AudioPool | null = null
+    let accentPool: AudioPool | null = null
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let nextTickAt = 0
+
+    const ensureAudio = () => {
+        if (silent) return
+        if (!clickPool) {
+            clickPool = new AudioPool(clickSrc, poolSize, volume)
+            clickPool.warmUp()
+        }
+        if (accentSrc && !accentPool) {
+            accentPool = new AudioPool(accentSrc, Math.max(2, Math.ceil(poolSize / 2)), volume)
+            accentPool.warmUp()
+        }
+    }
+
+    const playSound = (accent: boolean) => {
+        if (accent && accentPool) {
+            accentPool.play()
+        } else if (clickPool) {
+            clickPool.play()
+        }
+    }
+
+    const tick = () => {
+        if (!isPlaying.value) return
+
+        const every = Math.max(1, accentEveryRef.value)
+        const accent = beatIndex.value % every === 0
+        isAccent.value = accent
+
+        playSound(accent)
+        onBeat?.(beatIndex.value, accent)
+        beatIndex.value++
+
+        nextTickAt += intervalMs.value
+        const nextDelay = Math.max(0, nextTickAt - Date.now())
+
+        timer = setTimeout(tick, nextDelay)
+    }
+
+    const start = () => {
+        if (isPlaying.value) return
+        ensureAudio()
+        isPlaying.value = true
+        beatIndex.value = 0
+        nextTickAt = Date.now()
+        tick()
+    }
+
+    const stop = () => {
+        isPlaying.value = false
+        if (timer) {
+            clearTimeout(timer)
+            timer = null
+        }
+    }
+
+    const setBpm = (val: number) => {
+        bpm.value = Math.max(bpmMin, Math.min(bpmMax, Math.round(val)))
+    }
+
+    const setAccentEvery = (n: number) => {
+        accentEveryRef.value = Math.max(1, Math.min(16, Math.round(n)))
+        beatIndex.value = 0
+    }
+
+    /**
+     * 动态更新音频源（用于切换音色）
+     */
+    const updateAudioSrc = (newClickSrc: string, newAccentSrc?: string) => {
+        const wasPlaying = isPlaying.value
+        if (wasPlaying) stop()
+
+        // 销毁旧的音频池
+        clickPool?.destroy()
+        accentPool?.destroy()
+        clickPool = null
+        accentPool = null
+
+        // 创建新的音频池（静默预热，不播放）
+        clickPool = new AudioPool(newClickSrc, poolSize)
+        if (newAccentSrc) {
+            accentPool = new AudioPool(newAccentSrc, Math.max(2, Math.ceil(poolSize / 2)))
+        }
+
+        // 播放一次预览音效（适中音量）
+        const previewCtx = uni.createInnerAudioContext()
+        previewCtx.src = newClickSrc
+        previewCtx.obeyMuteSwitch = false
+        previewCtx.volume = 0.4
+        try {
+            previewCtx.play()
+            setTimeout(() => {
+                try {
+                    previewCtx.destroy?.()
+                } catch (_) {}
+            }, 500)
+        } catch (_) {}
+
+        // 恢复播放状态
+        if (wasPlaying) start()
+    }
+
+    /**
+     * 主动预加载（推荐在页面 onShow 时调用，让用户进页面就完成预热）
+     * 同时再次设置 setInnerAudioOption,防 App.vue 全局设置失效(iOS 静音键)
+     */
+    const preload = () => {
+        // #ifdef MP-WEIXIN
+        try {
+            uni.setInnerAudioOption({
+                obeyMuteSwitch: false,
+                mixWithOther: true,
+            })
+        } catch (_) {}
+        // #endif
+        ensureAudio()
+    }
+
+    onUnmounted(() => {
+        stop()
+        clickPool?.destroy()
+        accentPool?.destroy()
+        clickPool = null
+        accentPool = null
+    })
+
+    return {
+        bpm,
+        isPlaying,
+        beatIndex,
+        isAccent,
+        intervalMs,
+        accentEvery: accentEveryRef,
+        start,
+        stop,
+        setBpm,
+        setAccentEvery,
+        updateAudioSrc,
+        preload,
+    }
+}