Webamp 官方示例全解析：从 5 分钟接入到多曲目、多皮肤与 Milkdrop 可视化配置-港品优选

Webamp 官方示例全解析：从 5 分钟接入到多曲目、多皮肤与 Milkdrop 可视化配置

【免费下载链接】webampWinamp 2 reimplemented for the browser项目地址: https://gitcode.com/gh_mirrors/we/webamp

Webamp 是一个用浏览器重新实现 Winamp 2 的开源播放器项目，本指南围绕官方文档 Examples 章节及其对应的 examples 目录，带你逐个吃透仓库中开箱即用的示例：从一行<script>标签的 Minimal 接入，到多曲目播放列表、多皮肤切换、初始窗口布局以及 Milkdrop 可视化等完整配置方案。读完本文，你将能够直接复制这些示例的配置结构，在自己的页面中快速集成并深度定制 Webamp。

示例全景：examples 目录里有什么

官方文档04_examples.md将示例集中存放在仓库的 examples 目录下，每个示例都是一个可独立打开运行的 HTML 页面（多数示例甚至无需构建工具，直接用浏览器打开本地文件即可运行），并配有各自的 README 说明。目录中的示例清单如下：

示例	主题	核心配置点
Minimal	最小化接入	`script`标签 +`new Webamp()`+`renderInto()`
Multiple Tracks	多曲目播放列表	`initialTracks`数组
Multiple Skins	多皮肤切换	`availableSkins`+`initialSkin`
Minimal Window Layout	初始窗口布局	`windowLayout`+`enableDoubleSizeMode`
Minimal Milkdrop	Milkdrop 可视化	`webamp/butterchurn`入口

此外，仓库中还有两个更进阶的参考：webamp-demo 是一个功能更完整的综合示例（含桌面图标、SoundCloud 集成等），而 lazy 示例演示了按需加载（lazy-loading）的模块化用法，本文后续会一并讲解。

Minimal：用`<script>`标签完成最小化接入

Minimal 示例（examples/minimal/index.html）展示了接入 Webamp 的最小可行路径：从免费 CDN 引入 Webamp bundle，从 CDN 引入音频与皮肤文件，然后写上几行 JavaScript 即可。你甚至可以直接在浏览器中打开这个本地 HTML 文件看到 Webamp 运行（见 examples/minimal/README.md）。

其完整结构如下：

<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> </head> <body> <div id="app" style="height: 100vh; position: relative"> <!-- Webamp will render as a child of this div --> </div> <script type="module"> import Webamp from "https://unpkg.com/webamp@^2/butterchurn"; const webamp = new Webamp({ initialTracks: [ { metaData: { artist: "DJ Mike Llama", title: "Llama Whippin' Intro", }, // NOTE: Your audio file must be served from the same domain as your HTML // file, or served with permissive CORS HTTP headers: url: "https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3", duration: 5.322286, }, ], }); webamp.renderInto(document.getElementById("app")); </script> </body> </html>

这个示例包含三个关键要素：

容器元素：页面需要一个用于承载 Webamp 的div，示例中给容器设置了height: 100vh和position: relative，Webamp 会渲染为该div的子元素。
CDN 引入：通过<script type="module">从https://unpkg.com/webamp@^2/butterchurn直接以 ES Module 方式导入Webamp类。官方文档 02_install.md 也给出了对应的 NPM 安装方式：npm install --save webamp后import Webamp from "webamp/butterchurn"。注意这里使用的webamp/butterchurn入口自 2.2.0 起附带 Butterchurn 库（Milkdrop 可视化），如果你不需要 Milkdrop，也可以改用webamp@^2基础入口。
renderInto()：将 Webamp 渲染到指定 DOM 节点，返回一个 Promise，表示加载完成状态。

示例中 URL 注释给出的 CORS 提示非常关键：音频文件必须与 HTML 文件同域，或由服务器返回宽松的 CORS 响应头，否则浏览器会拦截跨域音频读取。更详细的说明见仓库文档 01_cors.md。

Multiple Tracks：用 initialTracks 构建多曲目播放列表

Multiple Tracks 示例演示如何一次性配置多首曲目。核心是initialTracks数组，每个元素包含metaData（artist、title）、url与duration三个字段：

<script type="module"> import Webamp from "https://unpkg.com/webamp@^2"; const webamp = new Webamp({ /** * Here we list three tracks. Note that the `metaData` fields and * duration are required to populate the playlist. If any of those * fields are omitted, Webamp will download at least part of each file * on initial page load in order to determine the missing information. */ initialTracks: [ { metaData: { artist: "DJ Mike Llama", title: "Llama Whippin' Intro" }, url: "https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3", duration: 5.322286, }, { metaData: { title: "Heroines", artist: "Diablo Swing Orchestra" }, url: "https://raw.githubusercontent.com/captbaritone/webamp-music/4b556fbf/Diablo_Swing_Orchestra_-_01_-_Heroines.mp3", duration: 322.612245, }, { metaData: { title: "We Are Going To Eclecfunk Your Ass", artist: "Eclectek", }, url: "https://raw.githubusercontent.com/captbaritone/webamp-music/4b556fbf/Eclectek_-_02_-_We_Are_Going_To_Eclecfunk_Your_Ass.mp3", duration: 190.093061, }, ], }); // Returns a promise indicating when it's done loading. webamp.renderInto(document.getElementById("app")); </script>

示例代码中的注释揭示了metaData与duration的作用机制：这两个字段用于在初次渲染时就填充播放列表；如果省略其中任意字段，Webamp 会在页面初始加载时下载音频文件的至少一部分，以便探测缺失的元数据与时长。因此，从性能和体验角度考虑，在你已知曲目信息的前提下，尽量把artist、title、duration都提供完整，可以避免初始加载时的额外网络请求。

Multiple Skins：用 availableSkins 实现皮肤切换菜单

Multiple Skins 示例演示了多皮肤配置，关键配置项为availableSkins（可用的皮肤列表，会出现在 Options 菜单的 "Skins" 子菜单中）与initialSkin（启动时加载的默认皮肤）：

const webamp = new Webamp({ // Optional. An array of objects representing skins. // These will appear in the "Options" menu under "Skins". // NOTE: These URLs must be served with the correct CORs headers. availableSkins: [ { url: "https://archive.org/cors/winampskin_Zelda_Amp/Zelda-Amp.wsz", name: "Zelda Amp", }, { url: "https://archive.org/cors/winampskin_Green-Dimension-V2/Green-Dimension-V2.wsz", name: "Green Dimension V2", }, { url: "https://archive.org/cors/winampskin_mac_os_x_1_5-aqua/mac_os_x_1_5-aqua.wsz", name: "Mac OSX v1.5 (Aqua)", }, ], initialSkin: { url: "https://archive.org/cors/winampskin_Zelda_Amp/Zelda-Amp.wsz", }, initialTracks: [/* ...同 Minimal 的曲目配置 */], });

要点说明：

availableSkins中的每个皮肤对象包含url（.wsz皮肤文件的地址）与name（菜单中显示的名称）。示例中的皮肤文件托管在 Internet Archive 的/cors/路径下，该路径会返回带 CORS 头的响应，这是示例能够跨域加载皮肤的前提。
initialSkin指定页面打开时默认使用的皮肤，示例中指向availableSkins的第一项 Zelda Amp。
与音频同理，皮肤 URL 同样必须带有正确的 CORS 响应头才能跨域加载（注释中明确给出了https://docs.webamp.org/docs/guides/cors的指引，对应仓库文档 01_cors.md）。

作为补充，你可以在仓库中找到若干真实的.wsz皮肤文件用于本地测试，例如 webamp-demo/skins 目录下的Zelda-Amp同类皮肤（如Green-Dimension-V2.wsz、MacOSXAqua1-5.wsz、TopazAmp1-2.wsz等），或 webamp/assets/skins/base-2.91.wsz 中的基础皮肤。

Minimal Window Layout：定制窗口的初始位置、尺寸与模式

Minimal Window Layout 示例演示了如何通过windowLayout配置三个核心窗口（主窗口 main、均衡器 equalizer、播放列表 playlist）的初始布局：

const webamp = new Webamp({ windowLayout: { main: { position: { top: 0, left: 0 }, shadeMode: true, // 以"窄条"（shade）模式显示 closed: false, // 初始是否关闭窗口 }, equalizer: { position: { top: 230, left: 0 }, shadeMode: true, closed: false, }, playlist: { position: { top: 28, left: 0 }, shadeMode: false, size: { extraHeight: 3, extraWidth: 11 }, // 在默认尺寸基础上额外扩展的宽高 closed: false, }, }, enableDoubleSizeMode: true, // 允许双倍尺寸模式 });

每个窗口配置项的含义：

配置项	类型	说明
`position`	`{ top, left }`	窗口的初始像素坐标位置
`shadeMode`	`boolean`	是否以 shade（窄条）模式初始显示
`closed`	`boolean`	窗口初始是否处于关闭状态
`size`	`{ extraHeight, extraWidth }`	在窗口默认尺寸基础上额外扩展的像素宽高

示例将主窗口放在(0, 0)并启用 shade 模式、均衡器放在其下方(0, 230)也启用 shade 模式、播放列表放在(0, 28)且扩展了extraHeight: 3, extraWidth: 11。enableDoubleSizeMode: true则开启双倍尺寸支持，用户可通过右键菜单切换 1x/2x 显示。类似地，lazy 示例中还演示了包含 milkdrop 窗口的四窗口布局，并将四个窗口按纵向 116px 间距排布，可作为布局定制的进阶参考。

Minimal Milkdrop：开启 Butterchurn 可视化

Minimal Milkdrop 示例展示了如何启用 Milkdrop 可视化。其与 Minimal 的唯一区别在于导入入口——使用带 Butterchurn 的webamp/butterchurn入口（从 2.2.0 版本开始提供），该入口已内置 Butterchurn 库：

<script type="module"> /** * Starting in version 2.2.0, Webamp includes a `webamp/butterchurn` * entrypoint which includes the Butterchurn library to enable the * Milkdrop visualizer. */ import Webamp from "https://unpkg.com/webamp@^2/butterchurn"; const webamp = new Webamp({ initialTracks: [ { metaData: { artist: "DJ Mike Llama", title: "Llama Whippin' Intro" }, url: "https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3", duration: 5.322286, }, ], }); webamp.renderInto(document.getElementById("app")); </script>

启用 Milkdrop 后，用户即可通过 Webamp 的 Milkdrop 窗口观看基于音频实时生成的视觉特效。如果希望控制 Milkdrop 的更多行为（例如默认打开、自定义预设），可以参考 lazy 示例中的__butterchurnOptions配置，它展示了如何通过动态import()按需加载butterchurn与butterchurn-presets并自定义预设列表。

进阶参考：lazy 入口与 webamp-demo 综合示例

除上述 5 个官方文档列举的示例外，仓库还有两个值得关注的进阶参考：

1. lazy 示例：演示了webamp/lazy入口与按需加载。它通过requireJSZip、requireMusicMetadata两个回调动态加载jszip与music-metadata，并通过__butterchurnOptions.importButterchurn与getPresets按需加载 Butterchurn 与预设，从而减小首屏 bundle 体积。该示例使用 Vite + TypeScript 构建（见 examples/lazy/package.json 与 tsconfig.json）。关于减小 bundle 的更多思路，可参考官方文档 03_bundle-size.md。

2. webamp-demo：一个功能更完整的综合示例，集成了桌面图标（DesktopIcon）、SoundCloud 接入（SoundCloud.ts）、多皮肤选择（availableSkins.ts）以及 Butterchurn 配置（butterchurnOptions.ts），适合作为生产级集成的参考蓝图。

总结：如何选择适合自己的示例

想最快看到效果：直接打开 Minimal，一个<script>标签加几行 JS 即可。
需要多首曲目：参考 Multiple Tracks 的initialTracks数组，注意补齐metaData与duration以避免初始探测下载。
需要皮肤切换能力：参考 Multiple Skins 的availableSkins+initialSkin，并确保皮肤文件带 CORS 头。
需要控制窗口初始布局：参考 Minimal Window Layout 的windowLayout与enableDoubleSizeMode。
需要 Milkdrop 可视化：改用webamp/butterchurn入口（见 Minimal Milkdrop）。
需要工程化集成：参考 lazy 示例（按需加载）与 webamp-demo（综合功能）。

以上所有示例的源码均可在当前仓库的 examples 目录下找到，每个示例目录内都有独立的 README 与可直接运行的index.html。

【免费下载链接】webampWinamp 2 reimplemented for the browser项目地址: https://gitcode.com/gh_mirrors/we/webamp

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析