Webamp 官方示例全解析从 5 分钟接入到多曲目、多皮肤与 Milkdrop 可视化配置【免费下载链接】webampWinamp 2 reimplemented for the browser项目地址: https://gitcode.com/gh_mirrors/we/webampWebamp 是一个用浏览器重新实现 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多皮肤切换availableSkinsinitialSkinMinimal Window Layout初始窗口布局windowLayoutenableDoubleSizeModeMinimal MilkdropMilkdrop 可视化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 charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / /head body div idapp styleheight: 100vh; position: relative !-- Webamp will render as a child of this div -- /div script typemodule 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/webamp43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3, duration: 5.322286, }, ], }); webamp.renderInto(document.getElementById(app)); /script /body /html这个示例包含三个关键要素容器元素页面需要一个用于承载 Webamp 的div示例中给容器设置了height: 100vh和position: relativeWebamp 会渲染为该div的子元素。CDN 引入通过script typemodule从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数组每个元素包含metaDataartist、title、url与duration三个字段script typemodule 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/webamp43434d82cfe0e37286dbbe0666072dc3190a83bc/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 its 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 }窗口的初始像素坐标位置shadeModeboolean是否以 shade窄条模式初始显示closedboolean窗口初始是否处于关闭状态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 typemodule /** * 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/webamp43434d82cfe0e37286dbbe0666072dc3190a83bc/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 的availableSkinsinitialSkin并确保皮肤文件带 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），仅供参考