单文件HTML打造可验证渲染的Techno音画机器

单个 HTML 文件里塞进一个 techno 机器听起来像演示项目实际上它把两件事压缩到很小的体积里一是用代码实时生成音乐节奏二是让每一次视觉渲染结果可以被验证。这里的关键是 verifiable renders。很多网页动画看起来类似但同一段代码在不同时间、不同机器上跑出来的画面很难对账如果换成“给定种子、给定帧号画面就应当可复现”的设计思路那么这个 HTML 文件就从一个一次性 demo 变成了一个可测试、可对比、可给别人复现的运行单元。下面的完整实现会围绕这个思路从零写一个单文件 techno machineWeb Audio 承担声音Canvas 承担画面确定性随机数承担可复现性最后附完整代码、验证方法和排错清单。如果你平时用 HTML、CSS、JavaScript 做页面但还没有把 Web Audio API 和 Canvas 组合起来做过“生成式小作品”这篇文章非常适合当入门练习。读完以后你会得到一个可以直接双击打开的音画 demo并且能解释清楚“为什么两次渲染结果可以保持一致”。1. 先拆解“单文件 techno machine”和“可验证渲染”1.1 techno machine 在这个项目里指什么这里没有一份完整的产品规格说明书但从标题可以明确技术对象在单个 HTML 文件中实现一台 techno 机器。techno machine 可以理解为一个小型音乐生成器它循环播放 techno 风格的节奏同时用视觉动画把节拍画出来。技术栈并不神秘Web Audio API 负责实时合成鼓点、踩镲和低音贝斯。Canvas 2D API 负责绘制画面用圆环、粒子、旋转线条等元素表现节奏。一段确定性随机数算法代替Math.random()保证同一个种子下每次生成的画面可复现。真实项目里这种单文件 demo 很常见。比如在技术社区用 Show HN 形式分享作品时单个 HTML 文件是最容易传播的形态不需要安装依赖不需要构建别人把文件保存下来就能看。1.2 为什么坚持用单个 HTML 文件把 CSS、HTML、JavaScript 全部内联在一起看起来像“偷懒”实际上有几个具体好处零依赖、零构建。文件不依赖 npm 包、CDN 或网络请求保存到本地双击就能运行。分享成本低。一个.html文件就是完整项目发文件、放进压缩包、托管到任意静态页面都可以。代码可审计。所有逻辑都在同一个文件里别人能直接看到你在用什么算法、有没有联网、有没有隐藏请求。版本对比方便。你可以把某一天的版本复制成techno-20250101.html过段时间再对比行为差异。代价也很明确单文件不适合大型项目。当代码超过一千行或者需要多人协作时模块化是必须的。单文件更适合“作品级 demo”或“教学示例”这也是这个项目的合理定位。1.3 verifiable renders 到底验证什么verifiable renders 翻译过来是“可验证渲染”核心含义是相同输入条件下渲染结果应当可复现、可对比、可审计。具体到本项目输入条件包括seed 字符串用来派生调色板、粒子位置等随机参数。BPM 值决定步进速度和音符间隔。frame 编号决定当前画面处于动画时间轴的第几帧。固定画布尺寸和固定逻辑帧率。输出则是一张确定的 Canvas 画面。你可以对画面计算一个哈希值比如a1b2c3d4e5f67890把这个值和 frame 编号一起展示在页面上。两个浏览器如果得到相同的哈希说明它们在相同输入下渲染结果一致如果不一致说明存在渲染差异。这种方式比“肉眼看着差不多”更有说服力也方便做回归测试以后改了代码如果相同 seed、相同 frame 的哈希变了你知道画面行为发生了变化。1.4 适用读者和前置知识这篇文章适合下面几类读者会写基础 HTML/CSS/JavaScript想动手做一个生成式音画 demo。了解 Canvas 基本绘图但没做过音频调度。对 Web Audio API 感兴趣想要一个最小的合成器示例。想把“动画可复现”这个设计思路用到自己的项目里。前置知识不需要太多。你能读懂基本的 JavaScript 函数、事件监听和requestAnimationFrame就够了。Web Audio 和确定性随机数的细节文章会逐步解释。2. 搭建单文件骨架页面、样式、画布三件事2.1 页面结构一个 canvas 加一组控制项单文件项目也要有清晰的页面结构。本项目只做四件事一个输入框用来填写 seed。一个数字输入框用来调整 BPM。一组按钮控制开始、停止、重置、捕获哈希。一个 Canvas 画布用来渲染画面。一小块文字区域用来显示当前帧号和像素哈希。HTML 结构看起来是这样div classcontrols labelSeed input idseed typetext valuedefault-seed/label labelBPM input idbpm typenumber min80 max160 value124/label button idstartBtnStart/button button idstopBtnStop/button button idresetBtnReset/button button idcaptureBtnCapture Hash/button /div div idmetaready/div canvas idviz width960 height540/canvas注意这里把控制项放在 Canvas 上方文字显示放在中间这样在任何屏幕宽度下都不容易被遮挡。2.2 固定画布尺寸别让 CSS 随意改变内部像素Canvas 有一点很关键canvas width960 height540是画布的“内部像素尺寸”CSS 里的width: 100%只影响它显示出来的大小不会改变内部绘图分辨率。本项目选择固定960x540作为内部尺寸有三个原因可复现性好。内部像素固定getImageData拿到的像素矩阵大小固定哈希计算稳定。显示自适应。CSS 可以把画布缩放到手机屏幕不影响内部逻辑。性能可控。960x540 大约 200 万像素在普通电脑上 Canvas 2D 绘制足够流畅。在样式中设置canvas { width: 100%; max-width: 960px; height: auto; background: #000; }这样画布会按比例缩放但在内部始终以 960x540 的坐标系统绘图。2.3 脚本组织方式先定模块再写代码单文件不代表可以把代码乱写。为了后面好解释JavaScript 按模块分成几个区域工具函数字符串哈希、确定性随机数生成器、种子组合。音频模块创建 AudioContext、合成 kick/hat/bass、调度音符。视觉模块逻辑帧推进、调色板生成、Canvas 绘制。验证模块从 Canvas 像素计算哈希。事件绑定按钮点击、键盘空格、seed 变化。初始化生成种子、画第一帧、启动渲染循环。这个顺序也是文章后面的讲解顺序。2.4 最小骨架代码先给一个最小骨架完整代码在第 6 章!DOCTYPE html html langzh-CN head meta charsetutf-8 titleTechno Machine/title style /* 页面样式 */ /style /head body !-- 控制区和 canvas -- script use strict; // 分区编写 JavaScript /script /body /html这个骨架的核心意义是让所有代码都在一个文件里同时保持逻辑清晰。“内联”不等于“混乱”只要把功能边界分开单文件也可以有良好的可读性。3. 用 Web Audio API 写一个最小 techno 音序器3.1 AudioContext 的创建与恢复Web Audio API 的核心对象是AudioContext。它管理一个音频图所有声音节点都连接在这个图上。现代浏览器为了用户体验通常不允许页面加载后立刻自动播放声音必须由用户手势触发。所以项目里不在一开始创建 AudioContext而是在点击 Start 按钮时创建function createAudioGraph() { audioCtx new (window.AudioContext || window.webkitAudioContext)(); masterGain audioCtx.createGain(); masterGain.gain.value 0.7; masterGain.connect(audioCtx.destination); }创建之后还要调用audioCtx.resume()。因为某些浏览器在页面启动阶段创建 AudioContext它的状态会停留在suspended需要用户手势配合恢复。这里有一个常被忽略的细节resume()返回一个 Promise。如果你在异步回调里继续调度音符要确保 Promise 已经 resolve。3.2 三种基础音色Kick、Hi-hat、Basstechno 的基础节奏通常由 Kick、Hi-hat、Bass 组成。用 Web Audio 合成这些音色并不复杂。Kick 使用一个正弦波振荡器频率从 160Hz 快速下滑到 46Hz同时音量快速衰减。这样听起来就是“嘭”一声短促的低鼓function playKick(time) { const osc audioCtx.createOscillator(); const gain audioCtx.createGain(); osc.type sine; osc.frequency.setValueAtTime(160, time); osc.frequency.exponentialRampToValueAtTime(46, time 0.11); gain.gain.setValueAtTime(0.9, time); gain.gain.exponentialRampToValueAtTime(0.001, time 0.32); osc.connect(gain); gain.connect(masterGain); osc.start(time); osc.stop(time 0.35); }频率从高到低快速下滑是 Kick 音色的关键。如果不加频率变化只有音量衰减听起来更像一个闷响缺少打击感。Hi-hat 则使用一段噪声缓冲。