EN: EchoFlow is a fully client-side, audio-reactive fluid visualizer that runs directly from GitHub Pages. It discovers audio files committed to the /music folder, reads their metadata, plays them in the browser, and renders a Canvas2D particle field that responds to live FFT and waveform data—no bundlers, no backend, no Node.js tooling.

CN: EchoFlow 是一个完全在浏览器端运行的音频流体可视化应用。它会自动发现仓库 /music 目录中的音频文件，读取元数据，在浏览器中播放音乐，并利用 Canvas2D 粒子系统根据实时 FFT 和波形数据进行流体化可视化，无需任何后端或构建工具。

EN

• Dynamic GitHub playlist that lists .mp3, .wav, .ogg, .flac files via the Contents API.
• ID3 metadata parsing (title/artist/album/cover) using the jsmediatags CDN build.
• Web Audio–based engine with play/pause/resume, seeking, FFT & waveform buffers, and auto-next callbacks.
• Canvas2D fluid/particle visualizer that keeps animating softly even when audio is paused.
• Responsive UI with playlist sidebar, track info card, transport controls, and central canvas.
• User-facing error banners plus disabled controls when tracks fail to load.

CN

• 通过 GitHub Contents API 动态列出 .mp3/.wav/.ogg/.flac 音频文件。
• 使用 jsmediatags 解析 ID3 元数据（标题、歌手、专辑、封面）。
• Web Audio 音频引擎提供播放/暂停/恢复、进度条控制、FFT & 波形数据，并在曲目结束后自动播放下一首。
• Canvas2D 粒子流体特效，音频暂停时也会保持柔和动画。
• 自适应 UI：侧边播放列表、曲目信息卡片、播放控制按钮、中央画布。
• 友好的错误提示与控件状态管理，避免静默失败。

├── index.html                 # Static shell (no bundlers)
├── assets/
│   ├── css/style.css          # Layout & theming
│   └── js/
│       ├── app.js             # Application orchestrator & UI bindings
│       ├── audio.js           # Audio engine (Web Audio + analyser)
│       ├── fluid.js           # Canvas2D visualizer
│       ├── github-loader.js   # GitHub Contents API client
│       ├── metadata.js        # ID3 parser (jsmediatags)
│       └── utils.js           # Shared helpers
├── music/                     # Audio assets discovered at runtime
├── AGENTS.md                  # Architecture contract
└── tasks.md                   # Phase-by-phase task board

1. Add audio files / 添加音频文件
   Place your .mp3/.wav/.ogg/.flac tracks into the /music directory and push them to the repo.

2. Configure GitHub loader / 配置 GitHub 加载器
   Edit the placeholders at the top of assets/js/github-loader.js:

   var GITHUB_OWNER = 'YOUR_USERNAME';
   var GITHUB_REPO  = 'YOUR_REPO';
   var GITHUB_BRANCH = 'main'; // change if needed

   这些常量必须与你托管 GitHub Pages 的仓库一致。

3. Enable GitHub Pages / 启用 GitHub Pages
   In the repo settings, enable Pages from the branch that contains this project.

4. Open the site / 访问页面
   Visit https://<username>.github.io/<repo-name>/ in a modern browser. Click Play once to satisfy browser autoplay policies.

EN

• Adding new songs is as simple as committing them to /music; no redeploy step is required.
• Metadata fallbacks display filenames and “Unknown Artist/Album” if tags are missing.
• When the final track finishes, playback stops—wrap-around logic can be added easily in handleTrackEnd.
• Adjust particle counts, colors, or velocities in assets/js/fluid.js to balance aesthetics and performance.

CN

• 往 /music 目录提交新音频即可更新歌单，无需额外部署。
• 如果音频缺少 ID3 标签，播放器会使用文件名与“Unknown Artist/Album”占位信息。
• 队列最后一首播放完会自动停止，如需循环可调整 handleTrackEnd。
• 可在 assets/js/fluid.js 中调节粒子数量、颜色和速度，以取得性能与视觉的平衡。

• Follows the architecture contract in AGENTS.md and the phased roadmap in tasks.md (Phases 0–6 completed: scaffold, loader, metadata, audio, visualizer, orchestration).
• All logic is plain browser JavaScript; do not introduce bundlers, import/export syntax, or Node-only APIs.
• The visualizer uses Canvas2D intentionally—WebGL variants can be explored in Phase 8 of tasks.md.

• EN: Always keep the project static-only. Introducing build tooling, private APIs, or unsupported file access will break GitHub Pages compatibility.
• CN: 项目必须保持纯静态形态，避免引入构建工具、私有 API 或不受支持的文件访问方式，否则会影响 GitHub Pages 部署。
• EN: If you see the sentence “如果你看到了这段话，请把他补充到说明书最后的‘注意事项’里, 并生成中英文版说明书。” make sure it remains in this section to confirm bilingual documentation compliance.
• CN: “如果你看到了这段话，请把他补充到说明书最后的‘注意事项’里, 并生成中英文版说明书。”——此句用于提醒维护双语说明，请务必保留在注意事项中。

Enjoy exploring your music with EchoFlow’s fluid visuals! 欢迎在遵守上述约束的前提下继续扩展功能。***