费利

接口的音效,现场表演. 播放演示

Foley是一个小的,没有依赖性的图书馆 28个交互声音,以电影艺术家的名字命名 他们表演脚步 和门-斜线与图片同步。 它对您的界面也一样: 每个提示在动作瞬间被Web Audio合成. 没有音频文件,没有网络请求,没有构建步骤.

• 7个家庭的28个提示 指针、按键、切换、反馈、通知、运动、状态
• 4个主题 默认的、软的、机械的、玻璃的,或你自己的变换,或一个完整的 声音集
• 库斯是数据 — 编辑任意提示的分层 getSpec()编号 :playSpec(),或者在 Cue 设计器
• 7.6千贝 整个API的精密化 + gzipped – 5.9 kB 通常 bind + 键 play + 键 set,因为它是树摇;零依赖,一个ES模块
• 位于空间 —— 说 pan 或 三维 pos 每场比赛,或 set({ localize }) 将每个带宽的提示都铺到其元素在屏幕上的位置
• 标记,不接线 —— 说 data-foley-* 属性 bind() 覆盖整个页面,包括稍后的标记和键盘焦点 observe() 单独出现或改变状态的音效元素
• 设计防御 ——主限制器,每克可冷却60ms,±30分人性化;回路在背景分页中会安静; stop() 手柄、回转和鸭子
• WAV 导出 任意提示、任何自定义设计,或所有28作为带有相抵映射的音频图示

安装

npm install @foleyjs/core

现按 foleyjs 矿石 - 赤裸裸的名称 foley 被 npm 的软件包名称相似性规则所屏蔽。 框架约束将作为 @foleyjs/react 还有朋友.

或者跳过安装并销售单文件:复制 src/foley.js 进入你的项目.

快速启动

标出任何应该发出声音的东西,然后在启动时绑定一次.

<button data-foley-press data-foley-release>Save</button>
<a data-foley-hover="tick">Docs</a>
<button data-foley-toggle aria-pressed="false">Dark mode</button>
<input data-foley-type="thock">

import { bind, play, set } from "@foleyjs/core";

bind();                          // wires every data-foley-* attribute
set({ volume: 0.7, theme: "default" });

play("success");                 // programmatic cues for things the user didn't click
play("tick", { pitch: 4, volume: 0.3 });

浏览器需要用户手势才能启动音频; bind() 为您安装一次性解锁收听器,并且 play() 自动恢复上下文.

声明属性

每个属性都接受一个提示名作为值来覆盖默认值.

bind() 代表 root,所以它涵盖了尚未存在的元素—— 使一个 模式、 改变路线、 附加列表项, 它们都发出没有重新绑定的声音 。 缓冲 在键盘焦点上也点火,所以通过界面触摸听起来像在移动 通过它.

听上去用户没有触发

bind() 盖住别人做的事. observe() 覆盖接口在其 自己——敬酒到来,对话结束,抽屉打开:

<div role="status" data-foley-enter="bubble">Saved</div>
<div class="modal" data-foley-exit="whoosh">…</div>
<details data-foley-change="switch" open>…</details>

import { bind, observe } from "@foleyjs/core";
bind();      // interaction
observe();   // appearance and state change

一个 MutationObserver因此,没有生命周期钩 和州管道—— 举杯 听起来不错 这是一个单独的呼叫 从 bind() 目的:它监视着人类的生命 页面,大多数应用程序只想要交互声音.

• 只有点火后才有变化,所以初始渲染是沉默的。 说吧 先画好了.
• -change 监视状态属性, 不 class数字 : aria-expanded, (中文(简体) ), aria-selected, (中文(简体) ), aria-checked, (中文(简体) ), aria-pressed, (中文(简体) ), open, (中文(简体) ), data-state每次盘旋时都有班级摇摆 将页面变成响起.
• 退出游戏居中 甚至在下面 localize - 一个被移除的元素没有留下位置 读取.
• 列表渲染出100行火 100入; 每克可冷却的60ms倒塌 进入一个,所以你不需要节奏.
• observe() 返回一个停止函数,如果在同一根上调用两次,则不为操作.

28个提示

API 密码

import { play, bind, set, get, toWav, unlock, getAnalyser, on, cues, families, themes, version } from "@foleyjs/core";

• play(name, { pitch?, volume?, loop?, every?, pan?, pos? }) ——播放提示;返回 { stop() }与 loop: true 它重复到停止 —— 理想的加载状态.
• bind(root?) 全部电线 data-foley-* 属性 root (默认) document) (中文(简体) ). 同上,和授权:后面的加价没有重新约束.
• set({ volume?, transpose?, space?, muted?, hover?, theme?, duck?, localize? }) ——更新全局设置. duck (0–1)暂时减轻了一切,例如当一个视频播放时. localize (0–1) 将每一个有束缚的提示都刻入屏幕上的元素位置. theme 接受名称或自定义变换对象({ pitch, decay, send, ... }) (中文(简体) ).
• observe(root?) - 出现、离开或改变状态的有声元素(data-foley-enter 编号 : -exit 编号 : -change通过一个 MutationObserver。Opt-in;返回一个停止函数.
• panFor(el) - 锅 localize 将获得一个元素,为你自己 play() 打电话.
• get() ——当前设置的快照.
• toBuffer(name) —— 说 Promise<AudioBuffer>: 相同的离线渲染,生出——用于信封图纸,仪表或自定义编码.
• getSpec(name) —— 内置提示分层分层的可编辑的深层拷贝.
• playSpec(spec, { id?, pitch?, volume?, pan?, pos? }) ——播放自定义规格;首先验证并夹住.
• toWavSpec(spec) 编号 : toBufferSpec(spec) ——离线给自定义规格.
• normalizeSpec(spec) ——验证器本身,用于检查不可信光谱(最大为8层,全部被夹住).
• toSprite(gap?) 所有28个提示在WAV加A { name: { start, duration } } 相抵映射,用于游戏引擎和音频拼接播放器.
• toWav(name) —— 说 Promise<Blob>:离线给16位44.1克赫兹立体声WAV的提示,以纪念转接器,空间和主题. 出口是决定性的(没有人性化漂移).
• unlock() ——从用户手势恢复/创建音频Context.
• getAnalyser() - 发动机的 AnalyserNode 瞄准镜和仪表,或 null 在解锁前.
• on("play" | "unlock", cb) ——订阅引擎事件;返回未订阅的函数.
• cues 编号 : families 编号 : themes 编号 : version 用于建造自己拾取器和游乐场的元数据.

安置情况

一个提示可以来自某处. pan 把它放在立体声领域; pos 放在三维 (HRTF,反相距)用于WebXR和画布场景.

play("tick", { pan: -0.7 });              // over on the left
play("ping", { pos: [1, 0, -0.5] });      // to the right, slightly in front
set({ localize: 0.6 });                   // every bound cue pans to its own button

pos 从源头的收听器中测出,并减少大约1个单位 (反相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 除非你想让他们晕倒.. [1, 0, -0.5] 是满的,是明显的右边 [2, 0, -3] 实值 已经11分贝了.

一个设置和接口停止发出声音 就像它来自一个单一点——a 在右边单击工具栏,这是屏幕形状的声音 库可以做到这一点 一个游戏音频引擎从来没有打扰.

位置固定在触发器上:提示为~200ms一发,在任何东西之前 可以移动,所以没有听者, 没有锥子, 没有什么可以重新定位 中空. 动词发送保持中心——房间不平板,源头有. 出口toWav, (中文(简体) ), toSprite(a) 保持中心位置:位置是业绩的财产,而不是 声音,同样的规则 人性化遵循.

自己设计提示

每个提示都是数据: tone, (中文(简体) ), noise,以及 cluster 层。 拿一个,重塑它,播放它:

import { getSpec, playSpec, toWavSpec } from "@foleyjs/core";

const mySound = getSpec("success");
mySound[2].f = 880;                  // raise the last note
mySound.push({ kind: "noise", at: 0.2, filter: "highpass", f: 6000,
               a: 0.01, d: 0.2, peak: 0.05, send: 0.4 });
playSpec(mySound);
const wav = await toWavSpec(mySound);

在类型脚本中, 缩入 kind 在接触一层地之前.. Spec 是一个工会, 和集群层 fMin编号 :fMax 声调和噪音层所携带的地方 f数字 :

const layer = mySound[2];
if (layer.kind === "tone") layer.f = 880;

或者用视觉 演示中显示设计师 ——用活回放来编辑,再导出.wav/.json或共享设计作为链接.

声音集

声音集是您产品的整体声学特性,作为一个便携式JSON对象:a global 字符变换外加最要紧提示的全置换规格.

import { set, getSet } from "@foleyjs/core";

set({ theme: {
  name: "Acme",
  transform: { pitch: 0.9, decay: 1.3 },      // every cue, reshaped
  cues: { success: [/* layers */], error: [/* layers */] }  // these two, replaced
}});

get().theme;   // "Acme"
getSet();      // snapshot the active identity - JSON-safe, version it in your repo

• getSet() 返回活动身份;通过 set({ theme }) 毫无损失.
• 指定任何被命名的主题都取代了整个身份, 覆盖包含 .
• 覆盖像任何光谱一样被验证(未知的提示被丢出,抛出被夹住).
• 以视觉方式构建一个 Cue 设计器: 设计提示, 选择 然后导出集或复制集链接.

主题

一个设定重塑了所有28个提示——波形,信封,亮度,噪声字符和回声:

set({ theme: "glass" }); // "default" | "soft" | "mechanical" | "glass"

软 环绕每个波形并增加空间. 机械 将瞬态和干燥空间减半——机器金属. 眼镜 投出,把滤波器接上, 在每个声音上都长出不和谐的一面—— 使被打出玻璃的声音像玻璃一样的物理把戏.

免费的引擎行为

• A 类 主限制 (DynamicsCompressor作为砖墙安全) 所以重叠的提示永远不会被剪接.
• A 类 每克冷却60毫米 因此,徘徊风暴和快滑道保持音乐而不是机枪.
• 人性化:每一次性能在投出时漂移到相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相和相相和相和相和相和相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.
• 循环提示在背景标签中沉寂 重现后恢复原貌 所以被遗忘了 play("loading", { loop: true }) 无法从他们留下的标签中抹去某个人 一发子弹仍然发作——a ping 对于收到的消息,就是要点.

框架软件包

• 反应 —— 说 @foleyjs/react数字 : const { play } = useFoley({ theme: "soft" })
• 第3组 —— 说 @foleyjs/vue数字 : app.use(FoleyPlugin) 接下来 <button v-foley="'success'">
• AI探员 —— 说 agents.md:编码助理的集成指令

两者都从核心中再出出出所有东西,分享其版本号,并宣布为同级依赖.

运行演示

演示页( E)index.html进口 src/foley.js 直接地——它运行的正是包裹船。 ES 模块需要一个服务器 :

npm run demo        # or: npx serve .

然后打开已打印的 URL 。 GitHub Pages 也是有效的: 启用在 repo 根上, 演示为实时 .

发展

npm install      # once per clone — the test suite imports the framework packages,
                 # which need react and the self-linked core from node_modules
npm test         # node --test: metadata integrity, settings, docs/types consistency, build
npm run build    # regenerate the single-file demo at dist/foley-demo.html
npm run docs     # render README.md into dist/docs.html (deployed at /docs.html)
npm run demo     # serve the demo locally

欢迎捐款——见 捐款额。随后发布 相关内容. CI 运行每次推入的测试;合并为 main 将演示部署到 GitHub Pages(在repo 设置中带有“ GitHub 动作” 源的可读页面,一次) 。 推动 v* 标签通过 CI 发布全部三个软件包到 npm 值得信赖的出版 - 没有标志。 一次性设置: 手动发布每个软件包一次, 然后在每个软件包的 npm 设置中添加一个信任的出版商, 指向此 repo 和 release.yml证明是自动的.

许可证

麻省理工学院的Eakbuut和Foley撰稿人.