运行：在本目录执行 python server.py（或双击 start.bat），浏览器/iPad 打开 http://服务器IP:3000。

顶栏「添加音频」：网络音频 / 本地导入 / 云端导入 / 上传云端 / 清空缓存 已移到顶部操作区，左侧栏只放控制项。

上传云端：弹窗里顶部就是「上传」按钮，点一下即把当前工程存到云端（云端已有同名工程则覆盖，否则新建）。下方会自动列出云端已有工程，每条右侧都有「覆盖上传」，可用当前工程替换该条。

云端导入（下载）：弹窗打开后自动列出云端工程，每条右侧的「下载」按钮即把该工程取回本机（点「刷新」可重新读取）。勾选下方「同时把音频下载到本机」，可一并把音频存进本机缓存，之后断网也能播放。

顶部工具条：左侧为品牌与工程名，「网络音频 / 本地导入 / 云端导入 / 上传云端 / 清空缓存」，接着是「淡入淡出总控」，最后是锁定、帮助；最右侧是「正在播放」实时列表（红色小圆标，正在发声的曲目，多首混音时并排显示，过多时可在该行内横向滑动）。

左侧控制栏：最上方是时钟与计时器，往下依次为分组、播放模式（同步混音／切歌独奏）、循环、切歌淡出、切歌交叉淡变、淡入/淡出时长、卡片尺寸、总音量与左右声道(L/R)。

左栏自适应：左栏控制项是一张张圆角卡片（时间 / 分组 / 播放模式 / 卡片尺寸 / 总音量），列内自上而下等距排列。屏幕高度不够时（内容看不全），左栏会自动改为两列：两根独立的纵向列各自从上往下排，并按每块的真实高度挑选最平衡的分法（最多两列，避免挤占右侧卡片区）；「总音量」独占整行。两列时两列的底边会自动对齐（较矮那列的分块按自身高度比例均摊余量，不会出现一长一短）；「总音量」独占整行。两列仍放不下时，会自动缩小左栏的字体、图标与按钮。窗口变高后自动恢复原大小与单列。窗口变高后自动恢复原大小与单列。窗口过窄（放不下两列）时保持单列并缩小。

整屏自适应：页面不会出现滚动条——时钟、计时、dB 竖条等高度会随窗口高度自动缩放；内容超出时仍可滚动/滑动，只是不显示滚动条。

总音量：左侧竖条是总输出 dB 电平表，右侧「主」为横向主音量滑块（含百分比），下方 L / R 为左右声道；点 🔊 总静音、停止全部。

总音量 L/R：同域、缓存、云端以及经服务器转发的远程音频都走 Web Audio 总线，可真正左右声道独立控制；只有在「服务器取不到该地址」、回退为浏览器直连的跨域音频时，才受浏览器限制回退为单声道（主音量仍生效）。

淡入 / 淡出：卡片上的「淡入」「淡出」是按钮，点亮即激活，时长统一在左栏「播放模式」里设置。点击播放后，若淡入已激活，卡片边框会在设定时长内由白色渐变到红色；停止时若淡出已激活，则由红色渐变回白色。按钮是常驻开关：点亮后一直保持，下次播放依然是淡入/淡出，只有再点一次按钮才取消。播放/停止若有淡变，播放按钮上会显示「淡入 N 秒 / 淡出 N 秒」倒计时并有一条由左向右生长的进度条，进度条走满后才真正变成红色「停止」按钮（淡出走满才回到「播放」）。

顶栏「淡入淡出总控」：顶部工具条上有一组总控，「全部淡入 / 全部淡出」可一键把当前所有分组的全部卡片打开或关闭对应开关（按钮显示橙色＝全部都开、暗橙＝部分开启、灰色＝全关）；「清除」= 全部关闭。后面的「淡入 / 淡出」两个滑块就是全局时长，与左栏「播放模式」里的两个滑块是同一个设置，双向同步。

卡片：点卡片任意空白处（非滑块区域）即播放，多张可同时播放，激活后边框变红（同步模式多个红框）。每张卡带合并的音量条与实时 dB 指示。右上角显示淡入/淡出状态。卡片标题下方有一排颜色预设色块，点一下整套换色：背景色 + 字体色 + 强调色，其中强调色会同时驱动播放按钮底色与卡片内滑块（进度条填充、音量圆钮描边），不再一律是橙色。（播放/停止中的红色为状态色，不跟随预设。）

背包网格：卡片按格子序号一格一格排列（像游戏背包）。没有卡片的格子显示虚线轮廓「未使用」（高度与卡片一致），铺满整页；拖卡片到「未使用」格子上该格高亮，松手即落到此格。

卡片尺寸：左栏「卡片尺寸」滑块调节卡片大小（160–360），拖到最大列数更少、卡片更大。卡片变小时，卡内的文字、按钮、滑块、内边距也会一起等比缩小，不会出现排版错乱。

分组：每页最多显示 5 个分组，超过用「‹ / ›」翻页切换。

静音 / 停止 / 播放器：点 🔊 切换总静音；「停止全部」一次性停掉所有正在播放的音频（已激活淡出的会先走完淡出），点击时按钮上也有一条进度条生长反馈。左栏「播放模式」区内的播放器模式是总开关（右侧 × 仅在设置了「首次播放位置」时出现，点它即取消该起点、恢复从列表第一首开始）。打包工程下方是随机播放开关：开启 = 随机播放，关闭 = 按列表顺序播放（播放器模式未开启时该开关变灰不可用）。播放器模式关闭时：随机播放开关变灰、上一首 ⏮ 直接隐藏，「播放 ▶」不可用，只剩「切换」可手动放单首；卡片上的 ⏭ 按钮每次只能选一张卡作为「下一首播放」目标（点亮的卡背景持续高亮闪烁，再点取消），底部「切换」按钮即跳到这张选中的卡播放——若没有选任何卡，「切换」呈灰、不可点；「播放」按钮也变灰，只能用「切换」手动放单首、用「播放」按钮暂停 / 继续。播放器模式开启时：右侧卡片区自动变成音频列表（单列逐行，行首是播放序号；每行只显示名称、播放按钮、音量条、电平与时间，iPad 窄屏下名字过长自动省略、dB 数值自动隐藏，淡入淡出 / 静音 / 循环 / 下一首 / 进度条等控件在列表模式下全部收起，需要改动请关掉播放器模式回到卡片网格），点「播放」即从列表第一首开始自上而下连播（若用卡片「下一首」或长按拖拽设了「首次播放位置」，则从那一行开始）；开启随机播放则随机连播（每曲终重新随机下一首），⏮ / ⏭ 也都随机播放任意一个已有音频。顺序模式下 ⏮ / ⏭ 按列表顺序上 / 下一首，随机模式下 ⏮ / ⏭ 都随机播放任意一个已有音频；「播放」按钮呈红色「暂停」时表示正在播放，点它即暂停 / 继续（暂停不重置进度）。长按「播放」按钮：顺序模式下会拉起一个白色发光源，拖到任意卡片松手即把该卡设为播放起点（白色边框常驻，再点「播放」从它开始；此时播放器模式行右侧会出现 ×，点击即取消该起点、恢复从第一首开始）；非顺序模式、或长按后直接松手，则停止全部。

拖动（iPad 适配）：电脑上按住卡片空白处拖动即可；触屏请长按约 0.35 秒进入拖拽（卡片变半透明即已激活），移动手指到目标格松手即交换；滑块、按钮、输入框上不触发拖动。轻点卡片＝播放/停止。播放器模式下右侧为音频列表，列表行不支持拖动排序（行顺序即分组内音频顺序，可在编辑模式下用卡片网格拖动调整）。

循环播放：左栏「循环播放」是总开关（对所有卡片生效）。卡片上静音图标右侧的 🔁 按钮是单卡循环：优先级最高——开启后这一张卡始终循环，不受总开关与播放模式影响，也不影响其它卡片；关闭后才跟随总开关。播放中切换会立刻生效，不用重播。🔁 右侧的 ⏭ 按钮是「下一首播放」：点亮后图标背景会在橙 / 深橙之间持续闪烁（不再叠加外发光），当前曲播完即优先播放此卡（再次点击取消）；配合连播使用时，被点亮的卡片会插队到下一首；且无论当前曲是否开启了循环，点亮下一首后当前曲都会强制播完即切到该卡。

静音：卡片上的 🔊 图标即静音开关，与淡入/淡出在同一行。

锁定：点顶部「🔓 解锁/🔒 锁定」可锁定界面——锁定后卡片不再支持拖拽、改名、配色预设、删除（这些控件直接消失），但播放/停止、静音、淡入淡出按钮、音量与进度滑块仍然可用；且锁定状态下点卡片任意位置即可播放/停止（点滑块本身仍是调节音量/进度）。

全锁定：点顶部「🔓 全锁定/🔒 全锁定」（红色）进入最严格锁定——卡片区域一切按钮、滑块、改名、拖拽全部失效，仅保留页面滚动。适合演出进行中防止误触；想恢复操作再点一次解锁即可。

远程音频（🌐 标记）：用「+ 网络音频」加进来的外链，卡片上会显示 🌐 远程 标记和一个缓存状态标签：未缓存（灰，点一下即开始下载）／缓存 x%（下载中）／已缓存（绿，已完整下载到本机）／缓存失败（红，点一下重试，鼠标悬停看原因）。远程音频会经本机服务器转发并落盘缓存后再给浏览器，因此不受跨域限制，左右声道 L/R 也能正常生效。

顶栏「远程缓存」：显示 已缓存 / 总数。点开面板可以看到每个远程音频的来源、服务器缓存状态、本机占用大小与状态，支持全部下载（逐个下载，逐个校验）、校验缓存（检查标记为已缓存的是否真的还在本机）、清空服务器缓存。全部显示「已缓存」即代表所有远程文件都已下载完成。

播放失败提示：若浏览器拦截了播放（iPad/Safari 的自动播放策略）或音频读不到，页面右下角会弹出原因提示（同一原因 6 秒内只提示一次，不再刷屏），卡片不会停在「正在播放」的假状态上——电平条只在真正出声时才跳动。

「源失效 / 文件丢失」标签：音频加载失败时，卡片标题下会出现标签。源失效＝地址读不到或元素已失效，点它即换新元素重试；文件丢失＝本地导入的文件缓存没了（换过浏览器或清理过浏览数据），点它重新选择该文件即可恢复，卡片位置、音量、分组设置都保留。远程地址到底能不能取到，可在顶栏「远程缓存」面板点诊断让服务器实测（会显示 HTTP 状态、类型、大小或具体错误）。

拖拽导入音频：把音频文件（mp3 / wav / m4a / aac / ogg / flac 等）从文件管理器直接拖进卡片区即可导入——拖到空白处会新建一个个新卡片；拖到某张卡片上（卡片亮蓝色框）则替换这张卡的音频，卡片名称、位置、音量、配色、淡入淡出等设置全部保留（会先弹一次确认）。支持一次拖多个文件。锁定状态下不导入。

云端上传 / 下载（音频智能匹配）：上传用工程副本进行，本机卡片不会被改成远程地址（本机仍按本地文件播放）。下载时会先按内容指纹与本机已有音频比对：内容一致就直接复用本机文件——不重复下载、也不会变成「🌐 远程 / 待缓存」；只有不一致的才会下载，下载完自动记下指纹，下次再下载就能直接命中。云端音频一律经本机服务器代理取用，不再受跨域限制（此前跨域直连被浏览器拦截，表现就是「缓存失败」）。云端文件按内容寻址存放，中文名不再互相撞名，相同内容只存一份。

本地导入 / 云端：「本地导入」选本机音频；「云端导入」列工程并导入；「上传云端」保存工程（可勾选把音频一并存到服务器）。

提示：工程自动存浏览器本地。dB 指示条为增益/VU 指示。