React Guitar 声音合成指南：useSound Hook 如何让吉他组件在浏览器中 3 行代码弹出真声

React Guitar 声音合成指南：useSound Hook 如何让吉他组件在浏览器中 3 行代码弹出真声

【免费下载链接】react-guitarA beautiful and accessible guitar component for React. ⚛️ 🎸项目地址: https://gitcode.com/gh_mirrors/re/react-guitar

React Guitar是一款漂亮且可访问的 React 吉他组件。本篇指南带你快速掌握它的useSound Hook 声音合成方案：只需 3 行代码，就能让吉他在浏览器中弹出真实的琴声，并支持 9 种乐器音色切换、一键扫弦与静音控制，无需音频后端、无需服务器，纯浏览器发声。

3 行代码上手：让吉他组件在浏览器发声

先安装 3 个包：

npm i react-guitar react-guitar-sound react-guitar-tunings

核心代码只有 3 行：

import Guitar from 'react-guitar' import { standard } from 'react-guitar-tunings' import useSound from 'react-guitar-sound' function GuitarWithSound() { const strings = [0, 1, 2, 2, 0, -1] // A 小和弦 const { play, strum } = useSound({ fretting: strings, tuning: standard }) // ① 创建播放器 return <Guitar strings={strings} onPlay={play} /> // ② 拨弦即发声，想扫弦就调 strum() }

关键点对接：

• fretting：当前按弦数组，每个数字是一根弦的品格（0= 空弦，-1= 静音），必须与传给<Guitar>的strings一致；
• tuning：每根弦的 MIDI 音高数组，standard即标准吉他 E2 A2 D3 G3 B3 E4，完整音阶表在 packages/react-guitar-tunings/src/index.ts，收录了吉他、贝斯、尤克里里、班卓琴等 40+ 种调弦；
• onPlay={play}：把组件的"拨弦"事件绑给播放器，用户拨哪根、响哪根。

useSound返回 4 个属性（源码见 packages/react-guitar-sound/src/index.ts）：

属性	说明
play(string, when)	弹奏第string根弦（0-5），when为秒级延迟
strum(up?)	以 50ms 间隔一键扫过 6 根弦，传true为自高向低扫
playing	每根弦当前是否正在鸣响的布尔数组
loading	音源是否仍在加载

两种换音色方法：withSoundFont 与 withSamples

默认音色是尼龙弦木吉他，想换声音？react-guitar-sound内置两个"乐器工厂"（模块目录：packages/react-guitar-sound/）：

方法一：withSoundFont，一个名字换音色

import useSound, { withSoundFont } from 'react-guitar-sound' const electricGuitar = withSoundFont('electric_guitar_clean')

底层基于开源 soundfont-player，直接传乐器名即可：acoustic_guitar_steel（钢弦木吉他）、electric_guitar_jazz（爵士电吉他）、banjo（班卓琴）、sitar（西塔琴）、acoustic_bass（木贝斯）……几十种音色随取随用，还支持 mp3/ogg 格式选择（实现见 packages/react-guitar-sound/src/instruments/sound-font.ts）。

方法二：withSamples，真实采样最逼真

import useSound, { withSamples } from 'react-guitar-sound' const flamenco = withSamples({ E2: '/samples/E2.mp3', D3: '/samples/D3.mp3', G3: '/samples/G3.mp3', E4: '/samples/E4.mp3', })

提供几个真实录音文件即可，内部用 Tone.js 的 Sampler 把每个品位映射到最近的采样来播放（实现见 packages/react-guitar-sound/src/instruments/samples.ts），官方演示站默认的"Flamenco Guitar"音色就是这样做出的，音色最接近真实吉他。

拨弦、扫弦、静音 3 个实用技巧

• 悬停即发声：给<Guitar>传playOnHover，鼠标划过琴弦即刻发声，做演示站就像真琴；
• 静音：给useSound传muted: true，play调用会被忽略——官方演示在弹出和弦选择器时就用它临时静音（参考 site/components/Demo.tsx）；
• 键盘扫弦：官方演示把1-6键绑定 6 根弦、w/s键绑定上/下扫弦（实现见 site/hooks/sound.ts）。

文件路径速查

模块	路径
吉他组件（外观与交互）	packages/react-guitar/src/index.tsx
useSound Hook	packages/react-guitar-sound/src/index.ts
声音合成播放器	packages/react-guitar-sound/src/util/player.ts
音字体乐器	packages/react-guitar-sound/src/instruments/sound-font.ts
采样乐器	packages/react-guitar-sound/src/instruments/samples.ts
演示站	site/components/Demo.tsx

想本地跑起来看真声：

git clone https://gitcode.com/gh_mirrors/re/react-guitar cd react-guitar && yarn build && yarn start

常见问题

问：为什么刚加载时play没声音？答：音源加载期间loading为true，等其变false再播即可；另外浏览器要求用户交互（如点击）后才允许激活音频上下文，这是浏览器安全策略，属正常现象。

问：换调弦后音高会错吗？答：不会。tuning变化时 Hook 会自动重建播放器，声音与视觉始终同步；调弦表里还内置 Drop D、Open G 等 20 余种常用调弦。

问：左手吉他怎么办？答：给<Guitar>传lefty即可，视觉镜像后声音依旧跟着指法走。

以上就是React Guitar useSound 声音合成的完整指南：3 行代码让浏览器弹出真吉他声，两种工厂换音色，拨弦/扫弦/静音随手控制，复制即用。

【免费下载链接】react-guitarA beautiful and accessible guitar component for React. ⚛️ 🎸项目地址: https://gitcode.com/gh_mirrors/re/react-guitar