StemLab — timing and loops for Shorts

StemLab

作者：Kieran Simkin · DanceFlow 生态系统 · 矢量标志和使用指南。

用于本地分析分轨、节奏时序、节拍、和声、歌词、MIDI 和适合 Shorts 的可循环片段。https://kieransimkin.co.uk/

规范歌曲示例 — Star Lights Glow (Mystery Liquid Kick)

examples/star-lights-glow-mystery-liquid-kick/ 保存了 Bass Ben & Friends 的 Star Lights Glow (Mystery Liquid Kick)，作为经验证的 192 kbps CBR MP3 试听／分析参考，其中包含原始提供的正面封面 JPEG 和 ID3 元数据。原始无损 WAV 仍是规范源母带，其 SHA-256 标识记录在 evidence.json 中， 而不会作为第二个大型二进制文件再次分发。该混音与 Star Lights Glow (Anthem) 不同；BPM、相位、 发行日期和 ISRC 尚未确认。请使用 python scripts/verify_star_lights_reference.py 验证，并参阅示例的 README。MIT 代码 许可证不涵盖音乐或美术作品。

独立节拍检测与计数（实验性）

节奏精度更新： 经典自相关和梳状滤波器的延迟峰值 现在会保留原始的 100 Hz 整数频点 BPM，同时报告有界的亚帧估计值。 局部节奏窗口也使用相同的细化方法；节奏族会提供整段源音频中观测到的起音路径覆盖率， 作为审核诊断指标，而非经校准的置信度或自动批准 BPM 的依据。预测节拍、 观测到的起音候选和推断出的序数间隔仍各自独立。请参阅 节拍证据文档。

stemlab compare-beats 现在可以比较无模型音频、N 维 DanceRudiments 录音、设备采集内容以及经验证的动作包重音。 五种互补的经典节奏解码器会生成可供审核的 BPM、节拍数、 相位、重音周期和局部节奏假设。它还可以导入现有的 Beat This!/BeatNet/Beat Transformer/All-In-One 模型结果 JSON，无需 重新运行模型；不会下载模型权重。跨来源相位评分需要明确的时钟偏移量。 任何推断的强拍或预测网格都不会被静默地视为真实检测结果或规范时间线。请参阅 用法和证据架构以及 模型与实现研究路线图。

审核流程现在会将半速／双倍速节奏族分组，而非对相关算法进行多数投票， 会评估 DP 对原始源音频的覆盖率，并使用稳健的残差／漂移保护机制拟合 原始保存的模型时间戳。可选参数 --annotation NAME=FILE 仅会根据匹配且经过人工审核、绑定 SHA 的标注评估节拍时序； 单独留出的可靠性校准在独立标注歌曲数量不足时会选择弃权。 非破坏性的 scripts/benchmark_example_beats.py 适用于 Arcadians、The Truth is a Virus， 以及单独固定版本的 Star Lights Glow (Mystery Liquid Kick) 衍生文件。 任何估算器都不会批准第 1 拍、更改音频母带或替代规范节拍映射。请参阅节拍证据。

骨骼网格节奏与循环证据

可选的 stemlab analyze-rig-motion 命令可分析带时间戳的 DanceRudiments 骨骼捕获数据，或来自动画 FBX/BVH/glTF/BLEND Actions 的已验证纯时间运动包。它会估算运动学动作重音和 BPM 候选值，发现重复姿势周期，并通过速度和根节点漂移检查，建议可供审核的循环接缝。它可以为现有 DanceRudiments 64-pip 编译器导出明确标记为未经验证的源节拍图。这不代表已验证的音乐第 1 拍、音频同步或自动循环／网格接缝修复。此过程不涉及模型下载或原生采样器。可选的 DanceRudiments 创作加载器会验证所有运动包分块哈希。请参阅骨骼运动分析。

真实歌曲参考时间线会逐字节保留明确固定哈希的公开检测器 JSON，包括换行符，兼容 Windows 和 Linux。通用导出仍会移除私有路径。容器模型权重和特定模型缓存存放在所属项目被忽略的 /opt/stemlab/models/ 目录下；它们不会纳入构建上下文以及源代码／软件包工件。

StemLab，由 Kieran Simkin 开发 · My Songs 作品集 · Arcadians EPK · 源代码

**打包标识：**规范项目名称为 StemLab。StemLab 是 Dance Flow 项目的一部分。PyPI 发行包命名为 danceflow-stemlab，仅仅是因为 Python 软件包注册表中的名称必须全局唯一。Python 导入名称、CLI、GitHub 仓库和容器映像仍为 stemlab。

每次开始新工作流前

开始前，请检查最新的官方稳定版发布版本以及实际安装／导入的版本；不要根据目录名称或开发检出版本推断其是否为最新版本。请阅读当前发行说明、带标签的功能文档以及相关的潜在问题。请使用 DanceFlow 发布前检查和完整功能参考。

人员和 Agent 应考虑整个生态系统，使用所有能实质性服务于任务的功能，组合使用受支持的文件／API，并改进规范工具中已证实且可复用的功能缺口。如果最终认为没有值得进行的更改，应记录原因。保持各工具的独立标识、兼容性、源时钟、隐私、模型／下载成本以及发布／部署权限不变。将权重和特定模型缓存存放在所属项目被忽略的 models/ 目录中。

选择路径

概要 · 安装 · CLI · 输出布局 · 执行的分析 · 精选默认模型集（2026 年 9 月） · 语音转录 · 全面的音色、和声、节奏与语义分析 · 从各个分轨中查找 DanceRudiments 匹配候选项

概述

StemLab 是一套本地、以证据为导向的音乐分析工具包，可将母带录音转化为可检查的分离音轨、时间信息、结构、和声、歌词和声音证据，然后为 Shorts 及其他短视频找到可循环播放的完整小节片段。

它结合了彼此独立的分离和音乐信息检索路径，而不把任何单一模型视为最终答案。分析结果可通过源文件哈希、清单、JSON/TSV/NPZ 产物、可移植的 Sonic Visualiser 会话，以及用于播放和比较的共享 React 时间线进行追溯。StemLab 可作为 CLI、Python 库、Web 服务、容器或本地 Codex MCP 插件运行。它是 Kieran Simkin 的 DanceFlow 工作流中的音乐理解层，也可为 WordPress DanceMoves 插件等下游动作系统提供支持，同时也可独立使用。

本项目不会重新分发模型权重。 首次使用时会从上游注册表/发布页获取这些权重。这样可避免在不知情的情况下重新发布许可可能不同于源代码许可的检查点，并可在适用时使用上游完整性元数据。

安装

推荐使用 Python 3.11，以兼容种类广泛的可选模型生态。beats 和 all 额外依赖会安装 Beat This! 以及兼容的 madmom-prebuilt 解码器。BeatNet 1.1.3 本身仍发布过时的 NumPy/Numba 依赖固定版本，因此 StemLab 会单独下载其官方纯 Python wheel，验证已公布的 SHA-256，并且只从缓存中提供 BeatNet 代码和随附模型权重。此方式支持 Python 3.11-3.13；不能将 BeatNet 结果缺失误认为检测器已成功运行。

从 PyPI 安装已发布的 StemLab 发行版：

pip install danceflow-stemlab

已安装的 Python 包和命令仍为 stemlab。如需从源代码检出版本进行开发：

python -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[all]"

SCNet 和 Beat Transformer 是研究代码仓库，而非稳定的 pip 推理 API。它们会按需隔离/下载。要预先准备所有内容：

stemlab bootstrap all

仅安装 BeatNet：

pip install "danceflow-stemlab[beats]"
stemlab bootstrap beatnet
stemlab doctor

只有在能找到常规包或经过验证的 StemLab 缓存时，stemlab doctor 才会将 BeatNet 报告为就绪。analyze --no-bootstrap 不会下载 BeatNet，而是记录该后端不可用。

仅安装 Vamp 分析栈：

stemlab bootstrap vamp

bootstrap vamp 会下载固定版本的 Sonic Annotator 运行时，并启动官方 Vamp Plugin Pack 安装程序。完成一次安装后，如有需要，请重新运行该命令，以验证所请求的插件输出是否可见。

CLI

完整的所需分析：

stemlab analyze master.wav --output ./analysis-master --profile full --device auto

其他实用选项：

# Skip the 53-stem model for a materially lighter run
stemlab analyze master.wav -o ./analysis-master --profile practical

# Run only selected separators
stemlab analyze master.wav -o ./analysis-master \
  --model bs_roformer_sw --model scnet_xl_ihf --model openunmix_umxhq

# Fail immediately rather than recording a backend failure and continuing
stemlab analyze master.wav -o ./analysis-master --strict

# Skip Vamp if the plugin pack is intentionally not installed
stemlab analyze master.wav -o ./analysis-master --no-vamp

stemlab models
stemlab doctor

默认情况下，模型权重和外部研究代码会缓存到输出文件夹之外；所有生成的分析产物和数据集都会写入输出文件夹。母带副本也会放在 input/ 中，使 Sonic Visualiser 会话能够以单个目录的形式移植。

输出目录结构

analysis-master/
  input/master.wav
  stems/
    bs_roformer_sw/*.wav
    mvsep_mega53/*.wav
    scnet_xl_ihf/*.wav
    htdemucs_ft/*.wav
    openunmix_umxhq/*.wav
  spectrograms/
    master.png
    master.npz
    <model>/<stem>.png
    <model>/<stem>.npz
    speech/spoken_word.png
    speech/spoken_word.npz
  speech/
    spoken_word.wav
    speech_regions.json
    whisper.json
    transcript.txt
    transcript.srt
    words.tsv
  beats/
    beatnet.json / beatnet.tsv
    beat_this.json / beat_this.tsv
    beat_transformer.json / beat_transformer.tsv
    beat_transformer_activations.npz
  vamp/
    report.json
    transforms/*.n3
    raw/*.csv
    data/*.json
    data/*.npz
    plots/*.png
  deep/
    sonic/
    rhythm/
    harmony/
    structure/
    lyrics/
    semantic_text/
    song_map/
    rudiments/             # optional native DanceRudiments candidate report
      report.json
      index.html
      overview.png
    summary.json
  sonic_visualiser/
    session.sv
    session.xml
    open_sonic_visualiser.bat
    open_sonic_visualiser.sh
  analysis.json
  manifest.json

session.sv 是真正的 Sonic Visualiser bzip2 压缩会话 XML。它包含一个母带窗格，其中有节拍/强拍/Whisper 瞬时层，以及每条分离音轨各自的同步波形 + Sonic Visualiser 频谱图窗格。未压缩的 session.xml 会保留，供检查/调试使用。Windows .bat 会在 PATH 和常见的 Program Files 位置中查找。

执行的分析

对于每个成功运行的分离器，它输出的每个 WAV 文件都会予以保留。Stem 名称通过文件动态发现，而不是截断为硬编码的四 Stem 架构；这对 MVSep Mega 53 尤为重要。对于母带和每个 Stem，StemLab 都会生成 PNG 频谱图和压缩的 .npz 频谱数据（时间轴、频率轴、dB 矩阵、FFT 元数据）。

完整分辨率的频谱数据保存在 .npz 中；PNG 渲染器的时间帧数上限为 8,192，避免长音轨生成数 GB 的 Matplotlib RGBA 缓冲区。如果旧版运行保留了 NPZ，但绘制 PNG 时失败，可直接修复，无需重新运行模型：

stemlab repair-spectrograms "path\to\analysis-results"

节拍网格比较还会保留一个显式的推断索引假设，用于处理已保存的检测结果跳过了整拍的情况。它会复用带整数间隔的恒定网格拟合器，保留每个已观测到的时间戳以及原始的半速／双倍速节奏。只有当首拍锚定的间隔拟合优于顺序拟合，且误差在现有范围限制内时，才会替换后者；两种拟合都会保留在比较报告中。缺失的检测结果并不代表新检测到的节拍，也不构成规范认可。

精选默认模型集（2026 年 9 月）

StemLab id	角色	输出	纳入原因
bs_roformer_sw	高容量	vocals、drums、bass、guitar、piano、other（另含上游 instrumental）	当前面向生产环境的 BS-RoFormer 推理包推荐使用这个六 Stem 检查点。
mvsep_mega53	高容量／广泛分类	53 个原始 Stem（动态发现）	单个检查点即可提供极其广泛的 Stem 清单，供后续评估。上游警告称该模型对内存要求较高，建议至少配备 16 GB VRAM。
scnet_xl_ihf	高容量	vocals、drums、bass、other	MSST 发布的检查点表显示，该模型在 MUSDB 测试集上的平均 SDR 为 10.08 dB，在 Multisong 上的平均 SDR 为 9.92 dB。
htdemucs_ft	已成熟的高容量基线	drums、bass、other、vocals	微调后的 HTDemucs 仍是有用的独立架构／基线，而非另一个 RoFormer 变体。
openunmix_umxhq	紧凑型／低延迟候选	vocals、drums、bass、other	紧凑型 PyTorch／Open-Unmix 基线。StemLab 将 niter=0，以优先降低延迟。“实时”表现取决于硬件和缓冲区；请在目标设备上进行基准测试。

另有可选模型 htdemucs_6s，已注册用于吉他／钢琴对比，但不属于默认前四模型组。

相关上游项目：

• https://github.com/openmirlab/bs-roformer-infer
• https://github.com/ZFTurbo/Music-Source-Separation-Training
• https://github.com/adefossez/demucs
• https://github.com/sigsep/open-unmix-pytorch

语音转录

首选人声分轨会经过 faster-whisper 内置的 Silero VAD 实现处理。系统会使用语音区域生成保留时间线的 spoken_word.wav（将非语音部分置零，而非拼接），然后运行 Whisper 并获取词级时间戳。输出包括 whisper.json、speech_regions.json、transcript.txt、transcript.srt 和 words.tsv。

对于演唱，如果语音掩码移除了音乐中的人声短句，请使用 --whisper-vad-mode full 进行比较。该模式会使用 faster-whisper 自带的 PyAV 解码器，将每个输入采样保存在单独的归一化 16 kHz 单声道 transcription_input.wav 中；这条完整音频路径无需导入 Torch。它不会拼接区域，也不会更改源时间戳。默认模式仍为 speech。如果已知语言，可以选择设置 --whisper-language en。保存的证据会记录模式、是否应用了掩码以及请求的语言。公开 Python API isolate_and_transcribe(..., vad_mode="full", language="en") 也接受精确的母带混音或已保存的人声分轨，以及本地模型目录路径。

这些是使用同一个固定版本的 large-v3 模型测得的词语对齐分数，不代表声学准确度或听感认可度。规范措辞保持锁定；70% 阈值和已观测锚点要求仍然适用。没有已观测时间信息的歌词行仍须暂缓处理。图表背景信息和哈希值。

规范词语对齐允许已观测的词语带有边缘标点，因此 Go, 可以匹配规范词语 Go，而不会更改任一文本或时间信息。它不会将一个多词 ASR 时间戳拆分成凭空生成的逐词时间戳。

默认情况下，Whisper 以防重复模式运行（condition_on_previous_text=False），以防某个窗口中的重复音节污染后续窗口。whisper.json 会记录此设置，并包含重复词元诊断信息。仅在明确进行对比运行时使用 --whisper-condition-on-previous-text；被标记的转录仍只是证据，需要按片段恢复或进行听辨质检，不能作为可信的歌词来源。

节拍分析使用：

• 通过 StemLab 的校验和验证运行时引导程序，以离线／DBN 模式运行 BeatNet。StemLab 使用维护中的 madmom-prebuilt wheel，仅绕过 BeatNet 1.1.3 过时的 NumPy／Numba 软件包元数据。
• 使用 final0 检查点和精简后处理器运行 Beat This!。
• 使用原版发布的模型代码／检查点运行 Beat Transformer。该模型使用五路解混梅尔频谱流进行训练，因此 StemLab 会将 BS-RoFormer-SW 映射为人声、鼓、贝斯、钢琴和 other + guitar，按照原始的 44.1 kHz／4096 FFT／1024-hop 设置生成 128 个频带的梅尔功率频谱图，并默认对发布的全部八个折叠检查点取平均。如果 madmom 可导入，则使用其原版 DBN 解码器；否则使用有文档说明的 SciPy 峰值检测回退方案。

节拍输出以 JSON、TSV 格式保存；对于 Beat Transformer，还会保存 activation NPZ 数据。

StemLab 还支持官方的 Vamp Plugin Pack，并通过 Sonic Annotator 运行。精心筛选的 Vamp 流程侧重于有助于音乐分析的输出：Chordino 和弦转录与和声变化可能性；NNLS 色度和贝斯色度；Queen Mary 调性与调性变化检测；音乐会音高调音；在首选分离人声分轨上进行 pYIN 旋律／F0 和单声部音符转录；Silvet 多声部音符转录；Segmentino 歌曲结构分段；以及 Queen Mary Vamp 节拍／小节追踪器。原始 CSV、固定版本的变换文件、JSON、NPZ 和绘图会保存在 vamp/ 下；最实用的旋律／和声层也会嵌入 Sonic Visualiser 会话中。

全面的音色、和声、节奏与语义分析

StemLab 1.0 整合了更高层级的证据融合流程，同时保留所有现有的底层输出。默认的深度分析现在包括：

操作	证据 / 模型	主要输出
音色特征	pyloudnorm BS.1770 + librosa DSP	LUFS、动态范围、真峰值估算、音色与立体声
律动 / 拍号	所有成功的节拍网格 + 起音分析	速度稳定性、拍号、摇摆感、弱拍能量与量化误差
速度区段	节拍网格 BIC 模型 + 固定网格残差	稳定区段、渐变、突变、相同 BPM 下的相位跳变，以及各区段的精度
和声	Chordino + NNLS 色度 + QM 调性 / 音高校准	和弦进行、和声节奏、调性证据与调性变化
功能结构	All-In-One-Infer 3.1	BPM、节拍 / 强拍，以及前奏 / 主歌 / 副歌 / 桥段 / 尾奏风格的区段
押韵 / 韵律	CMU 发音词典 + 时间信息	押韵方案、内部押韵、音节、重复与演唱速度
歌词语义	SentenceTransformers	主题相似度、连贯性与无监督歌词行聚类
歌曲图谱	StemLab 证据融合	同一时间轴上的区段级音色 / 节奏 / 和弦 / 歌词摘要

可选操作包括对分离出的乐器音轨使用 Basic Pitch 进行多声部 MIDI / 音符转录，以及使用 MuQ-MuLan 进行零样本音频 / 文本语义分析。MuQ-MuLan 发布的权重采用 CC-BY-NC 4.0 许可，因此该功能默认不启用，且其许可证信息会嵌入每项结果中。嵌入相似度标记为相似度，而非概率。

使用以下命令检查可用功能及其依赖项：

stemlab analysis-actions

常用开关包括 --no-structure、--no-text-semantics、--audio-semantics、 --basic-pitch 和 --all-in-one-embeddings。

派生文件位于 deep/ 目录下（sonic/、rhythm/、harmony/、structure/、 lyrics/、semantic_text/、可选的 semantic_audio/ 和 basic_pitch/，以及 song_map/song_map.json 和 summary.json）。

从每条音轨中查找匹配 DanceRudiments 的候选动作

使用 python -m pip install -e ".[rudiments]" 安装单独维护的可选原生程序包。StemLab 会直接调用 dancerudiments.catalogue() and dancerudiments.sample()，不会克隆动作函数或捆绑动作目录。它会提取每条音轨的 RMS 攻击峰值，将其映射到检测出的节拍上，再根据实际原生动作样本的位置 / 速度 / 加速度显著性，对 16 拍窗口进行排序。 评分表示比较相似度，并非概率，也不保证动作效果良好。

# Match the mix plus every saved stem without running separation again.
stemlab rudiments ./analysis-master --top 20
# Limit an existing analysis to two stems, or choose one of six official collections.
stemlab rudiments ./analysis-master --stem drums --stem bass --collection club
# Include matching as an opt-in part of a new full analysis.
stemlab analyze master.wav --output ./analysis-master --rudiments
# The bundled Arcadians MP3 has a documented BPM but no pre-separated stems.
stemlab rudiments 'examples/arcadians/Arcadians - 320kbps.mp3' \
  --bpm 145 --collection initial --top 28 --output ./arcadians-rudiments

Arcadians 实测基准测试

仅混音离线基准测试在 DanceRudiments 初始集合中真实存在的 28 种模式里，发现了 1,821 个能量上升峰值，以及 15 个相似度 ≥0.68 的候选模式，排名靠前的是 groove_b_played（0.739）、groove_b_grid（0.737）和 lfo_morph（0.724）。基准测试通过离线适配器读取 DanceRudiments 官方编译的样本表；原生 C++ 扩展测试是独立测试，若未安装该可选软件包则会跳过。BPM 网格从零开始，节拍相位未经验证。未声称进行了音轨分离。

以下是实测本地 HTML 报告的真实 Chromium 截图，并非示意图，也不是主 React 时间线的截图。

分析会生成 deep/rudiments/report.json、index.html 和 overview.png。请参阅**方法、评分注意事项、来源、示例和截图复现**。

**原生 CI 覆盖：**主 GitHub Actions CI 工作流现已包含专门的 Python 3.10/3.11 任务，该任务会安装官方 DanceRudiments 二进制 wheel，要求使用实际的 C++ 模块，并运行禁用跳过机制的 Arcadians 测试。少于 12 个真实音频匹配项会导致 CI 失败；通过的运行会将 JSON、HTML 和实测叠加 PNG 作为可下载的 CI 工件发布。请参阅原生 CI 验证说明。

与 BPM 同步的录音、测试框架和批量生成

以 每拍 64 个脉冲导出任意数量、独立路由的主维度／分轨维度，使用单独维护的 DanceRudiments float64 录音格式。每个导出的 DanceRudiments 维度都会先映射到相同的双极性 -1 至 +1 运动范围，再输出为 JSON、旧版包或测试框架格式。归一化选项用于选择振幅参考值（PCM 满刻度、共享峰值或逐轴峰值），不再改变输出坐标范围。静音轴保持在 0，应用双极性映射后再应用有符号增益。

必须提供 BPM 估值或已确认的 BPM 值；原始音频使用 --bpm，保存的分析数据则可提供当前拍点证据。--bpm-confirmed 会记录明确确认的 BPM，与估算／未验证的拍相位分别保存。

# Bass on X, treble on Y; generate JSON plus the actual DanceRudiments visualizer.
stemlab record-rudiment master.wav --bpm 145 \
  --axis x=master --low-pass x=180 \
  --axis y=master --high-pass y=3000 --output ./bass-treble
# Explore filtered/unfiltered master and every saved stem, including N-D combinations.
stemlab generate-batch ./analysis --bpm 145 \
  --dimensions 2 --dimensions 3 --dimensions 6 \
  --max-candidates 96 --seed 17 --include-audio --output ./movement-batch
# Fourier analysis: 32 frequency buckets become exactly 32 recording dimensions.
stemlab record-rudiment master.wav --bpm 145 --frequency-bands 32 \
  --fft-size 2048 --normalize global --output ./frequency-32
# Reuse a saved stem instead of analysing the master spectrum.
stemlab record-rudiment ./analysis --frequency-bands 32 \
  --frequency-source htdemucs_6s/drums --normalize global --output ./drum-frequency-32

--frequency-bands N 会将升序排列的频带映射到 band_000 至 band_N-1，每个脉冲使用一次周期 Hann 实数 FFT，并计算经过窗函数校正的 RMS 频带电平。默认将直流至源奈奎斯特频率划分为等宽频带；--frequency-min、--frequency-max 和 --frequency-scale linear|log 可选择不同的范围／间距。对数间距要求最小值为正数。--fft-size 控制频率／时间分辨率；无法解析的空频带会报错。对各声道功率取平均，不会因反相立体声而相互抵消。此功能沿用现有时钟、双极性映射、增益、归一化、JSON 和原生测试框架路由。生成的是频带电平运动，不是分离后的音频文件或乐器分轨。请参阅傅里叶选项、校准和边界。

打开输出中的 index.html，即可查看可搜索的运动卡片、现有的四卡片对比、共享音频传输、审核选项／备注，以及用于选择任意已存储维度的 X/Y/Z 选择器。原生 C++/WASM 播放和可视化工具资源仍由 DanceRudiments 提供，StemLab 不会复制引擎或仿制页面。录音会在结束时停止，保留所有维度，也不会悄悄变成循环播放。

选择逐轴峰值／平均绝对振幅窗口，以及低通／高通／带通路由。批处理模式会处理每个来源、探索带种子的组合，并复用缓存的滤波结果／去重列，而不是生成无界的笛卡尔积。只有使用 --include-audio 才会复制源音频；不会运行推理或下载模型。输出目录必须是新目录。这需要配套更新 DanceRudiments 的录音／测试框架；较旧的已发布软件包缺少此 API。现有匹配和 XYZ 格式仍保持兼容（--legacy 会显式导出有界的 XYZ 循环）。

请参阅 安装、所有选项、限制、时序、演示和验证。

这是对附带的合成音频批处理进行的真实 Chromium 截图，不涉及 Arcadians 模型推理。受限环境下的 QA 使用内存加载；此截图不代表正常文件加载或可听回放。

将母带或分轨导出为有符号波形 Rudiment

现有的 record-rudiment 导出器也支持 --mode waveform。 它会使用零相位抗混叠滤波和脉冲中心采样，将实际有符号 PCM 降采样到 DanceRudiments 的 每拍 64 个脉冲录制时钟。 与整流后的峰值、平均值和傅里叶包络不同，负波形值仍为负，静音仍为零。源采样率下的低通／高通／带通滤波会在抗混叠降采样之前应用。

# Master, with optional low-pass before downsampling.
stemlab record-rudiment master.wav --bpm 145 --mode waveform \
  --axis x=master --low-pass x=35 --output ./master-waveform
# A saved stem from an existing analysis, reusing its BPM evidence.
stemlab record-rudiment ./analysis --mode waveform \
  --axis x=htdemucs_6s/bass --high-pass x=12 --output ./bass-waveform

使用 --axis-mode x=waveform，可在同一录音中混合有符号 PCM 和包络轴。高音频频率无法在真正降采样至约 100–200 Hz 的运动时钟后保留下来；若要表示乐器的能量，请改用 --mode peak 或 average。有符号立体声通道会取平均值（反相可能相互抵消）；并沿用原生 DanceRudiments 录音 JSON、WASM 查看器、源哈希、归一化和现有事务式导出。 请参阅有符号波形重采样。

校正节拍并导出可变速度同步数据

时间线现已包含节拍校正编辑器，并会自动在所有精确的共识节拍采样帧处生成初始节拍。你可以在母带／分轨波形上逐个拖动节拍，以单采样精度微调，插入缺失的节拍，编辑局部 BPM 包络，查看相位 CV 曲线，移动全局相位，并明确选择第 1 拍的锚点。原始检测器输出永远不会被修改。校正数据单独保存在 timing/beat-timeline.json 中，并支持撤销／重做和安全保存修订。

导出第 1 拍 + 完整节拍时间线 JSON会下载一个包含所有校正后节拍、局部变化的 BPM 区间、原始母带／共识哈希、beat_1_start_seconds、beat_1_start_pips 和有符号的 sync_phase_offset_pips（以及 DanceMoves 16 刻度转换）的版本化 stemlab.beat-timeline.v1 对象。查看器还支持复制整个 JSON 值、导入先前编辑的版本，以及恢复原始共识锚点。导出会保留不规则节奏；不会用恒定速度近似值替代。

DanceMoves 兼容性：现有的 WordPress beat-alignment.v1 导入器仅支持恒定 BPM，并会拒绝此架构。若要在 DanceMoves 中驱动可变节奏，请先添加相应的 beat-timeline.v1 导入／调度支持（包括 WordPress 精确音频哈希检查），再粘贴／使用该数据。 对于真正的恒定 BPM 歌曲，仍可使用旧的节拍偏移交接方式。

请阅读可编辑节拍时间线、架构及使用方要求。 应用源代码更改后，请根据未修改的已发布 React 时间线依赖，重新构建 src/stemlab/web/app.js 和 timeline.css： npm ci && npm run build:web；请将这两个输出文件与源代码一并提交。

首拍对齐与速度族

以规范 BPM 和组合 BPM，对比已保存的共识数据与每个单独的检测器／来源，并使用精确的有符号 64 脉冲偏移，将检测到的第一个节拍映射到脉冲 0。半速和双速都是常见的解读方式：保留观测到的节拍，同时显示 ×½／×1／×2 对比，并明确估算恒定网格拟合。实际时间线会显示蓝色虚线原始网格和琥珀色实线偏移网格，并提供独立的 BPM 和检测器选择器。

stemlab beat-offset path/to/results --audio path/to/exact-master.mp3 --output new-offset-report

《The Truth is a Virus》参考页面 使用实际保存的 BeatThis／BeatNet 检测结果和共识数据。拟合后的速度为 109.0013 BPM；95% 的共识时间戳与该网格的偏差在 17.627 ms 以内。由于以首拍为锚点计算的末尾漂移为 67.114 ms，保护性评级仍为宽松级别。原始中位速度和未经确认的规范 BPM 仍会显示。 阅读精确映射、工作流和限制。

可编辑歌曲时间轴：固定／可变 BPM、歌词、歌词字词和提示段落

Stemlab 浏览器工作区提供 歌词时间试听与修正 和 节拍修正。时间轨道默认显示所有字词，也可切换到选中行视图以便精细编辑。时间轴上的 试听歌词 控件会显示已批准的封面图，并渲染与源文件绑定的字幕。播放、暂停、跳转、循环和声道选择仍由同一个时间轴传输控件管理。

歌词试听指南中的实际截图和静音演示视频展示了已发布的共享控件在桌面和移动端布局下的效果，且无需重新分发发行母带。

固定节拍时间还会标记连续歌词字词起点间隔少于五个 DanceMoves 节拍刻度的情况；少于三个刻度则为严重问题。编辑器会为这些目标字词添加轮廓，列出每条标记及其秒数和刻度距离，并允许审核者跳转到其所属歌词行。标记不会自动更改时间戳，因为快速的和声或连读短语可能是正确的。

它使用共享的 react-timeline-sequence 0.6+ 时间轨道，而非第二个播放头或定制渲染器。它的三个可编辑轨道分别是逐行歌词块、所有字词或选中行中的字词，以及提示段落边界。三个轨道共用同一原始母带音频、传输控件和缩放设置。

时间基准可以是明确指定的 固定 BPM + 第 1 拍偏移量，也可以是当前与 SHA 绑定的 已修正可变 BPM 时间轴。可变映射会按现有共识／修正采样帧的精确位置进行积分，绝不会在缺失区段插入虚构节拍。切换时钟模式不会移动提示段落、歌词行或字词的时间戳。可选的 150 毫秒吸附容差（可编辑）仅应用于用户执行的编辑；默认禁用。时间提示会显示标记与实际节拍或固定网格节拍的偏差，以及带正负号的毫秒数。保存绑定到可变映射的时间编辑前，必须先保存更改后的节拍映射。

可编辑的字词起点／终点必须位于选定歌词行范围内。拖动整行会带动其中的字词；更改行边界绝不会在不提示的情况下截断字词。编辑器包含在播放头位置添加、删除、重命名段落、编辑行／字词文本、导入、艺人审核状态以及保存／重新加载控件。 提示段落只能重命名为 [TYPE: STANDARD SECTION]：支持的类型包括 SECTION、ENTRY、DROP、BREAK。名称使用可识别的 INTRO、VERSE、PRE-CHORUS、CHORUS、BUILD、DROP、FINAL DROP、BREAKDOWN、OUTRO 等，并可带编号。示例：

[00:00.125][SECTION: INTRO]
[00:57.460][SECTION: VERSE 1]
[01:25.000][ENTRY: VOCAL INTRO]
[01:44.010][DROP: CHORUS 1]
[02:34.440][BREAK: SPOKEN BREAKDOWN]

编辑文档单独存储为 timing/song-timing-edits.json，其架构为 stemlab.timing-edits.v1：包含源 SHA-256、采样率／帧数、fixed_clock、时钟模式、固定修订版本的节拍映射、以整数原始源帧表示的行／字词／提示段落，以及艺人审核状态。**原始音频、canonical.json、ASR 证据、源 LRC 和节拍检测器结果均保持不变。**Web 服务支持：

• GET/PUT /api/{sha256}/song-timing（乐观修订版本检查），
• POST /api/{sha256}/song-timing/import（LRC 歌词行、LRC/TSV/JSON 字词、规范提示段落 LRC；若现有字词所属的歌词行将被导入，则拒绝导入），
• POST /api/{sha256}/song-timing/preview（严格校验并导出，不保存）。 导出 DanceMoves timing bundle会提供 JSON 源身份信息，以及固定或完整的可变 BPM 映射，同时包含逐行 LRC、逐词 TSV 和 JSON，以及提示点 LRC 内容。对于 DanceMoves 单独的完整节拍映射字段，请使用原始 Beat correction editor 的 stemlab.beat-timeline.v1 导出（或 bundle 中嵌套的 clock.beat_timeline），而不是外层的歌曲计时 bundle JSON。逐词时间保留在原始源秒数中；LRC/TSV 表示会四舍五入到兼容的小数位置，而 JSON 保留精确的原生帧。DanceMoves 会独立验证上传的逐词文件和提示点文件；不支持将完整的可变时间线粘贴到旧的固定节拍对齐字段中。用户必须将每个文件分配给相匹配且已验证的歌曲。

选择所需格式，然后使用 Download selected format。StemLab 会报告确切的文件名和字节数，并在编辑器中保留一个 Download ready 链接。如果浏览器阻止或隐藏了自动下载，请使用该链接；它指向同一份内存中的导出内容，不会保存计时变更。

对于全新检出，请先发布 react-timeline-sequence v0.4+。Stemlab 只使用最新的已发布稳定共享组件，不会使用未打标签的源码副本。发布后运行 python scripts/configure_viewer_build.py（该命令会更新官方查看器收据和编译后的资源），然后运行：

python -m pytest tests/test_timing_edits.py tests/test_beat_map.py
node --test tests/web/timing-workflow.test.mjs tests/web/beat-map.test.mjs
python scripts/check_viewer_build.py --latest
npm ci && npm run build:web
python scripts/check_viewer_build.py

将已发布的 npm/lock/version 收据、生成的 src/stemlab/web/app.js 和 timeline.css、源码、文档及测试一并提交；切勿提交补丁载荷、 模型权重或本地开发依赖覆盖项。

循环发现与播放

StemLab 现在会尝试为每个已识别的主歌和副歌段落找到至少一个完整小节的循环。它会检查节拍网格、人声清晰的剪切邻域，以及每个音频声道的波形接缝。对于不安全或不受支持的部分，会报告问题，而不会强行处理。默认情况下，起始/结束采样帧、质量诊断和来源信息会写入 deep/loops/loops.json 和 loops.tsv。

# New analysis: loop metadata is included in the default deep pass.
stemlab analyze master.wav -o analysis-master --profile practical

# Also save exact native-rate WAV slices.
stemlab analyze master.wav -o analysis-master --profile practical --export-loops

# Reuse existing separation, structure and beat results; no models rerun.
stemlab loops analysis-master --export-loops

# Keep all candidates within a chosen short-video edit budget, in seconds.
stemlab loops analysis-master --max-seconds 30 --per-section 3

# Audition possible new cut pairs anywhere in the song, even where the passage
# does not already repeat. These near-misses are NOT accepted seamless loops.
stemlab loops analysis-master --mode exploratory --search-scope whole_song \
  --max-seconds 30 --per-section 20 --exploratory-algorithm spectral_context

在现有分析前端中，选择一个高亮循环区域或 Loop 选择器，勾选 Enable loop，然后按 Play。仍可使用相同的播放头、寻位、缩放和频谱图时间线。预览循环不需要导出的 WAV，也不会写入任何文件。Zoom to loop 会聚焦共享时间线。

请参阅完整的循环工作流，了解安装两个补丁、采样索引、阈值、限制和可复现的截图示例。

如果目标是获得音乐上令人满意的重新开始点，请使用能覆盖完整乐句的替代方案：stemlab phrase-loops analysis-master --feedback artist-ratings.json --export-audio。此可选搜索会比较两个剪切点附近的音乐语境，保留规范的歌词段落，使用明确的艺术家反馈，并选择多样化的片段。建议结果与严格接受的循环分开。请参阅乐句循环方法、反馈格式和合成示例。 对于较长的片段，添加 --min-seconds 20 --max-seconds 30；还可选用 --max-bar-phase-error 0.125 筛除测得小节位置不匹配的片段。 这些筛选项用于提供试听建议，并不能证明片段无缝或适合聆听。

恢复短片或视频的源时间位置

stemlab match-clip master.wav published-original.mp4 --output new-match.json 可定位连续的配乐片段，无需运行模型或下载任何内容。它会保留两份原始哈希、时间精度、可能的源位置以及独立窗口检查结果。匹配报告会提供源偏移量、配乐时长和播放器起始位置，供需要同步的使用方使用。它能容忍短暂淡入淡出和压缩；重复片段存在歧义、剪辑跳变、录音不同以及速率变化等情况仍无法判定。若已知确切的配乐区间，请使用 --clip-start / --clip-end。解码视频需要 FFmpeg。 有关限制和合成示例，请参阅片段匹配。

音频转 MIDI 模型比较

MIDI 提取是可选的独立模型处理流程。除 Spotify Basic Pitch 外，它还加入了 Transkun V2 和高分辨率钢琴音符／踏板转录，以及 MR-MT3 和 YourMT3 多乐器转录。自动源选择会为钢琴专用模型使用钢琴／键盘分轨，为 Basic Pitch 使用有音高的分轨，并为 MT3 系列模型使用混音。缺少的分轨会明确报告，绝不会悄悄替换。旧版 --basic-pitch 命令仍受支持。

# Install the chosen runtime; the standard profiles do not install MIDI models.
python -m pip install -e ".[midi-transkun]"
stemlab midi-models

# Use an existing separated piano, without rerunning any earlier analysis.
stemlab midi analysis-master --model transkun

# Or transcribe a directly supplied piano recording to a new folder.
stemlab midi piano.wav -o midi-piano --model transkun

# Full mix comparison requires the separately installed midi-mt3 extra.
# Both requested checkpoints need explicit first-use download consent.
stemlab midi mix.wav -o midi-comparison --model mr_mt3 --model yourmt3 --allow-model-downloads

每种模型／来源都会生成原始 .mid、考虑速度的 notes.json 和 notes.csv、可选的真实音符 piano-roll.png、来源／检查点哈希、软件包版本以及工作进程日志。原生 MIDI 控制器、弯音、速度变化和鼓组都会保留。音符采样编号是原始采样率下的估算值，并不表示转录结果是采样级精确的真实标注。 不会使用 MIDI 时钟覆盖 StemLab 测得的节拍网格。

新的分析可通过重复使用 --midi-model 开关和 --midi-allow-downloads 来启用此功能。更新 Python 安装并重启会话后，现有 Codex 安装会获得工作区范围的 stemlab_start_midi_scan 作业工具。模型仍为可选项，且不会自动安装 Python 依赖项。不兼容的研究运行时可使用独立的 --backend-python MODEL=PATH 解释器。

有关所有模型、安装选项、检查点与许可注意事项、已保存分轨的目标选择、Codex 用法、精确输出语义、真实推理冒烟测试命令和测试限制，请参阅 MIDI 指南。React 时间线仍是分析检查器；此补丁不会添加 MIDI 合成器或新的交互式钢琴卷帘轨道。静态音符图并非前端截图。

将定时音乐提示对齐到检测到的节拍

使用已保存的分析结果吸附 LRC 提示文件，无需重新运行模型或编辑音频：

stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review
stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review-100ms --tolerance-ms 100
stemlab generate-cues analysis-master -o generated-cues --title "Song title"

只有时间戳会改变：[DROP: CHORUS 1] 等方括号标签、元数据、编码和行布局都会保留。若某条提示在 ±150 ms 内没有检测到的节拍，则会标记为 REVIEW，显示与最近节拍的间隔，并默认保持不变。--force-snap 也会移动相距较远的提示，但仍会保留警告。--downbeats 会将目标限制为报告的每小节起始拍；--beat-model 用于选择特定的检测器。检测间隙不会用恒定速度的节拍填补。

每个新输出文件夹都包含重写后的 .beat-snapped.lrc、report.json、彩色标注的 review.html 和 review.txt。精确模式会保留已存储的节拍时间戳；显式的毫秒／厘秒兼容模式会报告舍入情况。已知采样率时，也会包含源采样率下的采样帧估算值。使用 --fail-on-review 可写入结果，并在需要审核时以状态码 2 退出。

生成的段落提示文件会使用针对标题且兼容 WordPress 的文件名，因此可以上传多个发行版本并映射它们，而不会出现含糊的重复名称。对于保留的 2026 年 10 月 3 日未来发行批次，scripts/run-upcoming-full-cues.ps1 会在不覆盖未完成目录的情况下续跑完整分析；scripts/summarize-upcoming-cues.ps1 会读取每个已关闭的清单／报告，为每个发行版本生成一行可复现的哈希值、提示操作和错误计数汇总。若生成的 LRC 缺失或有歧义，汇总脚本会拒绝继续。

对于新分析，添加 --snap-cues "musical cues.lrc"，并可选添加 --cue-tolerance-ms 100。提示对齐会使用该次运行检测到的事件，并显示在 analysis.json 中。精度、偏移量、所有开关、安全规则和警告解读的详情，请参阅提示对齐指南。

互补证据模型

StemLab 现在提供可选的证据模型层，用于接入能够提供不同类型音乐证据、而非重复常规分离或 MIDI 后端功能的模型。常规配置文件不会启用此层中的任何内容。

stemlab evidence-models

# Singing/speech/music activity + continuous pitch on saved vocals.
stemlab evidence analysis-master -o evidence-vocals \
  --model firered_aed --model swift_f0 \
  --model-path firered_aed=/models/FireRedVAD/AED

# Align approved lyrics without replacing them.
stemlab evidence analysis-master -o evidence-align \
  --model qwen_forced_aligner --canonical-text lyrics.txt --allow-model-downloads

# Independent harmony evidence.
stemlab evidence analysis-master -o evidence-chords --model lv_chordia

内置注册表涵盖 FireRed AED、HeartTranscriptor、Qwen3 ForcedAligner、SwiftF0、SongFormer、lv-chordia 和 ADTOF PyTorch。它还提供 GAME、SheetSage2、MOSS-Music 和 AudioSep 的显式外部运行时桥接，因此大型或受限的研究依赖项不会被悄然打包进 StemLab。各项输出彼此独立：歌唱活动、强制对齐、音高、结构、和弦和鼓点都是供审核的证据，而非隐藏的综合真值评分。

已保存的分析会自动将人声模型路由到优先选用的完整人声 stem，将鼓点转录路由到鼓 stem，将连续音高路由到有音高的 stem，并将结构／和声模型路由到母带。缺少专用 stem 时会报告相应情况。对于相互冲突的研究环境，使用 --backend-python MODEL=/path/to/python。

有关模型术语、路由、外部桥接和解读规则，请参阅证据模型指南。scripts/benchmark_evidence_corpus.py 会对经授权的评估语料库进行探测，而不会将音频复制到仓库中。

Arcadians：完整分析时间线与四个动作演示

每次新版本发布都会构建一个包含五个可运行示例的公共网站，这些示例都涵盖完整的 Arcadians 原曲：

• 分析时间线： 真实的 StemLab React 查看器、原始音频、六个真实的 HTDemucs 分离音轨、 波形图／频谱图、母带／打击乐节拍估计及共识结果、Whisper 词语、全部 13 项精选 Vamp 分析、功能结构、音色／节奏／和声／歌词分析、文本 语义、歌曲地图和循环发现。

• 动作对比： 现有的 48 个 DanceRudiments 动作，包含 2D/3D/6D 滤波／未滤波母带 路径、145 BPM、每拍 64 个采样点和 float64 录音。此示例仍以母带为基础；它并未声称 动作使用了分离音轨。

• 音轨对比： 60 个二维录音，每个录音的 X 轴和 Y 轴由不同的实际音轨驱动。

• 振幅模式对比： 30 组固定的输入／滤波组合，每组包含峰值、平均值和四种移动平均 窗口：共 180 个录音，并采用共享的归一化参考值。

• 傅里叶频段： 选择从完整原始母带导出的 4、8、16、32、64 或 128 个维度。 每个等宽频段通过居中 Hann 2048 点 rFFT 和经窗口校正的频段 RMS 提供一个 维度。全局归一化会保留每种分辨率内的相对频段强度；它不会校准不同分辨率之间的 数值。可选择任意 X/Y/Z 轴，也可在共享的 Bars 视图中查看所有频段。

根首页链接到全部五个示例。这些是部署目标；仅有补丁 或绿色构建，并不能证明新页面已上线。

同一次 CI 发布还保留了独立的 The Truth is a Virus 节拍 参考。其冻结的检测结果已公开说明；当前 CI 会生成其拟合结果、 偏移量和实际时间线，而不会声称重新运行了学习模型。

时间线的 arcadians-core-v3 配方会在完整且经校验和验证的 MP3 上 运行所有选定的核心系列。它不是包含五个分离器的 full 对比配置文件，也不包含所有可选证据／NC 模型。它还会在五个带音高的音轨（贝斯、吉他、钢琴、人声和其他）上运行 Basic Pitch，显示推断出的音符轨道，并提供每个未经修改的原生 MIDI 文件供下载。 鼓声音频已分离；此配方并未声称能够进行鼓类别 MIDI 转录。 覆盖范围、依赖项 版本和源代码／导出版本修订信息均已公开说明。缺少音轨、节拍结果、 Vamp 插件、MIDI 转录或必需的深度分析证据都会导致构建失败；不会使用 合成回退结果。艺术家确认的 145 BPM、歌词、手动编辑的歌词时间 和艺术家划分的段落，与机器估计结果保持区分。已完成的循环扫描 可能确实返回零个接受的循环，并说明尚未解决的段落。

实际本地实现截图：保留的 v1.8.0 公共核心证据，加上基于已公开说明的 PCM24 FLAC 音轨进行的 新 Basic Pitch 推断。这并不表示 CI 已完成全新运行，或 v3 部署已完成。 视频、推断音符图、工作流覆盖范围和验证限制。

构建并发布全部五个示例

启动 Actions → Arcadians release demo → Run workflow → main。该工作流会先在 StemLab 现有的 Docker 环境中运行完整的 CPU 分析，然后导出时间轴并在浏览器中测试。它还会构建并测试原始的动作示例和两个新的对比页面，复用完全相同的分离浮点 WAV，以及全部六种完整母带傅里叶分辨率，并将全部五个示例合并为一个经过验证的 Pages 制品。模型分析的计算量远高于母带峰值提取；上游模型下载和推理必须成功。新的带标签版本会调用同一个组合工作流。

全部五个示例都支持音频播放，且不会自动播放。时间轴不需要实时 StemLab API、Socket.IO 连接或 CDN：原始 React 渲染器会加载预先计算的本地数据、波形包络和频谱图条带。它支持播放／暂停、点击标尺跳转并播放、空格键控制播放、适配 1,024× 的精确缩放／适配，以及在存在循环时试听已保存的循环。精确范围可让较短的逐词边界占据足够的屏幕宽度，以便精确放置。原始 MP3 保持不变；公开的音轨音频使用完整时长的 PCM24 FLAC 试听衍生文件，并公开说明其转换方式。原始浮点 WAV 和原始结果、原生 MIDI 及音符表会保存在单独的、保留七天的 Actions 分析制品中。每张 MIDI 音符表都会与其原生 MIDI 及其实际分离输入的哈希值进行核对。MIDI 速度不是新的源 BPM。Basic Pitch 捆绑的模型会暂存到配置的项目本地 StemLab 模型缓存中，并进行校验和检查；已安装的原始模型会予以保留。

请保持 Pages Source = GitHub Actions 和 STEMLAB_PAGES_ENABLED=true，以便在手动演示成功或发布带标签的版本后自动发布。保留 github-pages 环境审批，并允许相关的 main／标签引用。或者，Publish Arcadians demo to Pages → Run workflow → main 可发布选定的、成功构建的组合演示（运行 ID 留空时会选择最新版本），不会重新运行模型，也不会创建软件包版本。缺少全部三个新增图库和时间轴的旧制品会被拒绝，以免覆盖完整的五示例站点。独立的 Arcadians complete analysis timeline 作业仅用于构建，不会单独部署到 Pages。

发布程序会验证所有查看器的来源信息、制品校验和以及成功的 HTTP 浏览器报告，然后探测实际的公开页面、时间轴资源／数据和部分 MP3 响应。失败的 QA 或仅存在于内存中的 QA 不能授权发布。QA 文件、私有文件夹、模型缓存和运行时日志都不会包含在公开上传内容中。全部五个示例都包含在 StemLab-Arcadians-visualizer.zip 中，并附有文件哈希和构建来源信息。原生录音下载会无损压缩为 .json.gz；使用原生录音 API 加载前，请先解压。不会丢弃或量化任何采样点。每种分辨率都必须通过原生／条形图／浏览器／音频 QA。构建不完整时，绝不会替换线上站点。

将现有分析导出为静态时间轴

# Install the server extra for shared export helpers; do not start a server.
stemlab export-timeline ./analysis-arcadians \
  --include-audio --output ./arcadians-timeline-site

输出必须是分析目录之外的新目录。请通过静态 HTTP(S) 托管，而不要使用 file://。是否包含音频／歌词需明确指定。通用导出会展示已保存的证据，但不会声称已运行完整的 Arcadians 配方。

请参阅**完整配方、工作流、静态导出、时间信息和验证以及动作／音频详情和 Pages 配置**。

时间线分析图库

浏览器工作区旨在让分析结果可供检查，而不只是供下载。下方插图使用与前端相同的共享时间线术语，介绍主要分析类别：统一时钟、播放指针、可缩放轨道，以及频谱图、节拍、歌词和深度分析图层之间一致的分段对齐方式。

**插图，并非前端截图。**这些 SVG 由 scripts/render_readme_analysis_gallery.py 生成；该脚本不会执行 React 时间线组件、解码音频、运行分离或进行神经网络推理。 只有 Arcadians 分段标签、歌词文本和时间，以及参考 BPM 来自 随附的艺术家创作元数据。其他绘制的模式和示例和弦标签都明确为示意，并非 Arcadians 的测量结果。尤其是，这些图片不能作为无演唱片段、测得的速度稳定性、和弦／调性估算或响度值的证据。实际前端截图仍待补充。

1. 分离、频谱图、节拍和分段

这是核心检查视图。它展示 StemLab 如何对齐以下内容：

• AI／参考分段图（deep/structure/ 和 deep/song_map/），
• BeatNet、Beat This! 和 Beat Transformer 生成的节拍和小节网格（beats/*.json、beats/*.tsv），
• 母带频谱图，以及
• 写入 spectrograms/ 的每个分轨频谱图。

实际使用时，在检查分离器、节拍模型或分段模型的输出在音乐上是否可信时，你会首先查看此视图。

2. 歌词、语音区域和转录 QA

StemLab 让歌词和语音分析与音频使用同一时钟：

• 来自已知正确 LRC 或 JSON 源的参考歌词时间，
• 来自首选人声分轨的Whisper 词语时间，
• 语音区域／VAD 证据，用于显示检测到的语音活动；仅凭此项无法确认不存在演唱，
• 衍生的 spoken_word.wav 时间线保真语音分离音轨，以及
• speech/ 和 deep/lyrics/ 下游的押韵、韵律和重复安全诊断。

重要的是，你可以将模型听到的内容与艺术家提供的内容进行比较，然后立即关联到循环边界、编舞提示或歌词表 QA。

3. 和声、旋律和歌曲地图融合

StemLab 的和声与结构分析不只是一条和弦轨道。和声／歌曲地图类别汇集了：

• 来自精选 Vamp 流程的和弦与和声变化证据，
• 调性、调性变化和调音输出，
• 根据人声分析得出的旋律／F0 风格轨道，
• 分段级歌曲地图，将结构、节奏、和声和歌词证据融合为一份易读的叙述。

这些输出主要位于 vamp/、deep/harmony/ 和 deep/song_map/ 下；这一图层让原始低层 DSP 输出更容易从音乐角度理解。

4. 音色特征、节奏形态与语义

更高层级的深度分析还会追踪歌曲随时间的听感变化：

• 音色特征摘要（响度、峰值、动态、音色和立体声表现），
• 律动／节奏指标，例如摇摆倾向、弱拍能量和量化误差，
• 速度形态检测，用于识别稳定段、渐变和突变，
• 来自歌词／文本分析，以及可选的零样本音频语义分析的语义摘要。

这类分析让 StemLab 从简单的 BPM 和分轨工具，升级为更丰富的音乐理解层，供 DanceFlow 和下游动作响应系统使用。

5. 循环片段的作用

循环片段发现补丁并非取代先前的分析，而是依赖它们。循环片段选择会使用：

• 段落标签，查找候选主歌和副歌片段，
• 节拍网格，将剪切点对齐到完整小节，
• 完整人声分轨和可用的计时证据，以避开检测到的人声；仅靠 VAD 并不足够，
• 以及波形接缝检查，以减少不连续；接受的接缝仍需试听检查。

因此，循环片段功能最好理解为对 StemLab 中现有结构、节奏和人声分析的应用式综合。

时间轴叠加层和动作显示模式

主音轨／分轨音频会按音源分别显示为一个通道，左侧标题中提供 Waveform / Spectrogram / Both。Both 会将波形叠加到时间对齐的频谱上。每个通道都有高度滑块和重置功能：滚轮平移时间，Ctrl/Command + 滚轮缩放时间，Alt + 滚轮调整悬停通道的大小，Shift + 滚轮在通道之间滚动。这些操作只会改变显示效果。

共享的 DanceRudiments Movement view 选择器可在现有的 X–Y 轨迹和 Bar graph 之间切换；后者会为存储的每个维度显示一条带标签的有符号条形。它保留原有的原生采样器、音频时钟和审核状态。分离后，BeatNet/BeatThis 仍会分析主音轨以及每个人声／打击乐分轨；主音轨分析不会被取代。

请参阅**查看器控件和已发布查看器工作流**。请先发布两个配套软件包；StemLab 会解析最新的稳定官方 npm/PyPI 版本，并从这些发行包重新构建。开发版本固定依赖和本地供应商归档不是生产依赖。现有导出页面必须重新生成。

Web 服务

实时和静态时间轴查看器使用已发布的 React Timeline Sequence 控件启用试听歌词。带时间戳的字幕会显示在歌曲封面上，并随播放／暂停、跳转、循环片段和所选的音频通道同步。选择主音轨或时长完整的分轨；切换通道会暂停播放并重置播放头。未保存的歌词行编辑会立即更新字幕，即使隐藏了计时编辑器也是如此。冻结导出内容仍为只读。

播放实际的静音查看器演示。 请参阅试听指南，了解两个示例、计时依据、封面导出、本地预览命令和验证限制。

StemLab 包含上传／时间轴 Web UI，以及用于内容寻址分析任务的 HTTP 和 Socket.IO API。请参阅 docs/web.md，了解启动器、端点、事件和 Arcadians 参考工作流。

Python API

from pathlib import Path
from stemlab.models import FULL_PROFILE
from stemlab.pipeline import run_pipeline
from stemlab.types import PipelineConfig

result = run_pipeline(PipelineConfig(
    input_wav=Path("master.wav"),
    output_dir=Path("analysis-master"),
    models=FULL_PROFILE,
    device="auto",
))

Codex 插件和 MCP 服务

首先通过真实的 React 时间轴进行检查。 Codex 插件现在提供 stemlab_open_timeline，用于在 StemLab 捆绑的 react-timeline-sequence 前端中呈现已保存的结果。使用可用的本地浏览器对比 波形、频谱图、节拍和段落轨道，选择／启用循环、缩放并试听重复播放。 精确的 JSON 报告可支持数值结论；无法访问浏览器时，可将已保存的 PNG 作为备用。 截图必须来自渲染后的组件，不能重新绘制。stemlab_close_timeline 会关闭私有的只读查看器，且不会更改结果。请参阅检查工作流。

通过 Codex 使用 StemLab 来分析节奏、检查真实证据，并查找／导出适用于 Shorts 视频的可循环音乐片段。它是一个本地 stdio MCP 服务和可安装的技能包，并非远程音频上传服务或视频编辑器。它会复用现有管线，并保留之前的结果文件夹。

# From this patched checkout, in an activated environment:
python -m pip install -e ".[codex]"
stemlab-codex configure --workspace "/absolute/path/to/music-workspace"
stemlab-codex doctor
codex plugin marketplace add .

在受支持的 Codex 主机上，从本地插件目录安装 StemLab；若仅使用 CLI，可直接注册 MCP 命令。请参阅设置和工具，了解 Windows 路径、模型扩展、同意、轮询和精确的样本约定。

发布构建会验证 MCP 集成，并将带版本号的插件 ZIP、校验和及 MCP Registry 元数据附加到 GitHub 发布版本。仅用于发布的 codex-plugins 分支会在发布到 PyPI 后提供市场渠道。 这不会自动提交到 OpenAI 的公开插件目录。 发行和可选的 MCP Registry 发布 介绍了不同渠道及审批要求。

Codex 技能

该仓库包含一项可复用的 Codex 技能，位于 skills/use-and-improve-stemlab。 它会将 StemLab 设为默认分析引擎，选择适当的配置，保留证据边界，并通过测试将可复用能力的缺口反馈给 StemLab，而不是创建未记录的平行技术栈。

DanceFlow 和 DanceMoves

DanceFlow 是更广泛的 BPM 与动作响应工作流。StemLab 是其音乐理解层；WordPress DanceMoves 插件是相关的下游动作响应组件。StemLab 不依赖 WordPress，并通过常规分析产物和服务 API 进行通信，因此可独立使用且结果可复现。

请参阅 docs/danceflow.md 了解组件边界。

StemLab 的浏览器工作区导入可复用的 react-timeline-sequence 控件，用于音频播放、共享播放头、定位、缩放和通用序列轨道。StemLab 保留上传和分析专用适配器。

文档

• DanceFlow 工作流及与 DanceMoves 的关系
• Web 服务
• 容器
• 发布和版本发行
• BeatNet 兼容性
• 变更日志

外部运行时／缓存详情

BS-RoFormer 适配器使用 bs-roformer-infer，由它管理自身的检查点注册表和 SHA-256 验证。SCNet 固定使用 v1.0.15 SCNet XL IHF 发布资源 URL；StemLab 会在下载后记录计算出的哈希值。Beat Transformer 从其原始上游仓库克隆，并使用该仓库发布的 fold 检查点。设置 STEMLAB_CACHE=/some/path 可更改 StemLab 外部缓存的位置。

完整运行的计算开销很高。Mega-53 是 VRAM／存储开销最大的处理阶段，而数十个音轨意味着会产生数十个额外的频谱图文件和 Sonic Visualiser 窗格。迭代时使用 --profile practical，进行全面分析时使用 --profile full。

发布

版本标签会在验证后将 StemLab 发布到 GitHub Releases、PyPI（danceflow-stemlab）、 GHCR 和 Docker Hub。有关发布约定和 Trusted Publishing 设置，请参阅 docs/publishing.md。

协调发布与依赖最新版本

将 DanceRudiments、react-timeline-sequence 和 stemlab 保持为同级 检出目录。发布顺序为 React Timeline Sequence → DanceRudiments → StemLab：先发布并验证配套项目，再更新使用它们的应用。 StemLab 必须使用它们最新的稳定正式版本，而不是未发布的 提交、同级源代码包或打包进项目的 npm 归档。解析最新版本后，每次构建都会记录精确的 已发布版本、提交和完整性信息，使所有作业使用相同的文件；如果该快照已过期，CI 会明确失败。

在父文件夹中，先预览，再明确执行：

.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot .
.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot . -Execute

首次迁移时，提取完整工具包后，使用相同命令并指定 .\release-kit\Release-DanceFlow.ps1。该脚本会应用三个仓库补丁、更新版本、执行限定范围的提交 并正常推送，等待精确提交对应的 CI 完成，然后创建新的发布标签。StemLab 的 CLI、两个插件清单和 MCP 注册表元数据会一并进行版本管理。 现有 GitHub Actions 工作流负责发布软件包；不会更改保护规则、 凭据、旧标签或资源。初始预期的下一个次要版本仅为预览建议，绝不表示这些版本已发布。

使用 Node.js 24、Python 3.11+、PowerShell 5.1+、Git 和已认证的 GitHub CLI。 必需的主仓库、注册表和 Pages 作业必须通过；缺少审批和部分发布都属于阻碍项，而非成功。 默认情况下，脚本会发布全部三个项目；必须通过 -Execute 显式启用，并支持通过 -Resume 恢复已保存的精确源代码会话。检出目录发生更改或提交前构建失败时，需要人工检查， 而不是自动暂存/重置或猜测恢复方式。

StemLab 的辅助脚本会一并更新 npm 清单/锁文件、可选的原生依赖最低版本、 发布/构建元数据，以及实际重新构建的 JS/CSS。其每日发布更新工作流会通过 PR 提议后续更新，但不会自动合并。 带标签的 StemLab 发布会生成全部五个 Arcadians 页面，并验证实际的 Pages 部署、线上 HTML 和可定位播放的音频。不要在该带标签构建期间启动重复的手动 Arcadians 分析。运行前请阅读 完整的发布、恢复、验证和故障排查指南。 未来更改时，请保持此 README 与 AGENTS.md 同步。

独立 Linux CLI 发布门槛

Linux 单文件 stemlab-linux-x86_64 可执行文件是必需的发布 产物，而非尽力提供的额外内容。它使用 PyInstaller 打包，因此会捆绑常规 Python/原生模块，而不是将整个 ML 技术栈转换为 C。专用的 Standalone CLI 工作流使用 Python 3.11，以兼容维护中的 madmom-prebuilt 解码器和 StemLab 经校验和验证的 BeatNet 1.1.3 运行时。构建会引导安装 官方 BeatNet wheel，验证其 SHA-256，并嵌入 BeatNet 代码、模型权重以及所需的软件包数据/元数据， 然后使用空的外部 StemLab 缓存对实际可执行文件进行冒烟测试。--help、models 和 doctor 必须能够运行，且 doctor 必须报告内嵌的 BeatNet 已就绪。

主分支发布协调要求先通过 binary.yml，然后才能打标签。 带标签的发布会调用同一可复用工作流，且不得发布备用的 STEMLAB-BINARY-NOTE.txt；可执行文件缺失或构建失败都会导致发布失败。

Windows pytest 临时目录权限

StemLab 会在 %LOCALAPPDATA%\StemLab\pytest\<checkout-fingerprint> 下配置专用的、不参与同步的 Windows 测试文件夹，而不是使用全局的 %TEMP%\pytest-of-<username> 文件夹或 OneDrive 内的 .pytest-tmp/。这样可以避免因全局临时目录权限过期以及云同步锁定测试目录而反复出现 Windows PermissionError: [WinError 5] 故障。每个检出版本都有独立、简短且稳定的基础路径；pytest 仍会创建单独编号的运行文件夹，以确保隔离。无需管理员权限、修改注册表或删除旧临时文件夹。

在 Linux 和 macOS 上，pytest 仍使用 StemLab 被忽略的 .pytest-tmp/ 目录。显式设置的 --basetemp=PATH 或 PYTEST_DEBUG_TEMPROOT 始终优先。请避免在并发运行之间共用显式的 --basetemp，因为 pytest 会在启动时清空该路径。

beat-map 合成音频测试夹具还会在创建以哈希命名的分析文件夹之前，从内存中已关闭的 WAV 流计算 WAV SHA-256。它不再重命名已填充内容的目录，因为 OneDrive 或防病毒软件可能会在 Windows 上暂时锁定该目录。这只影响测试设置，不影响节拍分析逻辑或源音频验证约定。

无需特殊环境设置即可运行回归测试：

python -m pytest tests/test_pytest_temp_root.py tests/test_beat_map.py tests/test_timing_edits.py

临时文件是本地测试数据，不是仓库产物或发布的音乐。

可复现性与许可

analysis.json 记录模型／后端元数据和错误；manifest.json 会为每个输出产物生成哈希。模型检查点、研究代码和数据集遵循各自的上游条款。特别是，不要假设 MIT 许可的推理包装器会自动授予其可下载的所有检查点的再分发权。

Arcadians 时间线 CI 解码器和产物检查

当前查看器快照使用已发布的 React Timeline Sequence 0.8.0 和 DanceRudiments 0.3.0。真实重建的捆绑包保留了现有的传输控制、节拍网格控件和五条 MIDI 音符轨道。封面字幕、精确的活动词高亮以及主音轨／分轨选择器都使用同一套源时钟传输。

完整的 Arcadians 演示会在耗时较长的分析之前检查 lint。其 Docker 运行环境包含固定版本的 TorchCodec，并执行合成 MP3 解码器冒烟测试；时间线构建器还会在模型推理之前检查原始 Arcadians MP3。解码器缺失时会尽早失败，既不会更改源音频，也不会放宽完整分析／发布门槛。Docker 退出后，工作流会恢复专用输出文件夹的运行器所有权，以便浏览器验证和诊断产物上传能够读取私有模式的 JSON 文件，包括分析失败的运行。请参阅 Docker 检查和时间线工作流。

要部署新的时间线与动作组合版本，请在 main 上运行 Arcadians release demo。它会在内部调用 Arcadians complete analysis timeline；单独启动该工作流会导致分析重复，而且不会自行发布组合的 Pages 网站。

Docker 构建还会在全新的离线进程中检查音频优先的歌词语义导入：它会先测试 resampy 的两种 Kaiser 滤波器，再解析实际的 Transformers 和 SentenceTransformer 类。这可以在整首歌曲推理之前捕获延迟加载故障。容器运行环境会临时固定 resampy==0.4.2 和 setuptools==81.0.0，因为 Basic Pitch 0.4.0 排除了更新的 resampy 版本，而该版本不再需要 pkg_resources。这些只是容器专用的兼容性固定，并非降级常规的软件包构建工具。此冒烟测试不会下载权重，也不代表执行了语义推理；仍需通过完整分析和浏览器／发布门槛。

分离音轨的动作批次与可控平滑

stemlab generate-stem-batch 会对原始歌曲进行一次分离（默认使用 htdemucs_6s），或复用已保存的分析结果，然后生成 X 和 Y 轴使用不同音轨的 2D DanceRudiments。它涵盖原始有序音轨对，以及带种子的低通／高通／带通变体；默认候选数量上限为 120 个。处理原始音频时，请提供 BPM 估算值或已确认的 BPM 值。使用 --analysis-output 可保存处理好的音轨以供复用。

stemlab generate-stem-batch song.wav --bpm 145 --bpm-confirmed \
  --analysis-output ./song-stems --include-audio --output ./stem-pairs
stemlab generate-average-comparison ./song-stems --bpm 145 --max-pairs 32 \
  --window-beats .125 --window-beats .25 --window-beats .5 --window-beats 1 \
  --include-audio --output ./average-comparisons

第二条命令会固定每对音轨的来源、滤波器、方向和振幅缩放，同时比较峰值、每个脉冲的平均值和移动平均值设置。移动平均值是在整流后的振幅包络上进行的独立居中平滑窗口，可按拍数配置；它不会对有符号音频取平均，也不会改变每拍 64 个脉冲／float64 录制格式。record-rudiment 和 generate-batch 也可通过 --mode moving-average 和 --moving-average-beats 使用此功能；单个轴可使用 --axis-window-beats NAME=BEATS 配置。

Arcadians 工作流现在会汇集五个示例：现有的 arcadians/ 动作和 timeline/arcadians/ 分析结果，以及 arcadians-stems/（60 个分离音轨动作）和 arcadians-averages/（30 对 × 六种设置）。它会直接使用时间线分析中的真实 float 音轨，无需重新分离，并附上原始歌曲以支持同步播放。两个新增图库在报告成功前都必须通过原生端／浏览器／音频检查及公开 URL 验证。Fourier 页面新增六种完整主音轨分辨率，无需重新分离。所有页面仍部署在同一个 Pages 部署中。请参阅设置、边界、预算和示例。

分离后的节拍检测：主音轨与打击乐假设

启用节拍分析后，流程会先完成分离，然后对每个成功选用的分离器所产生的主音轨和每条带标签的鼓／打击乐音轨运行 BeatNet 和 BeatThis。每项结果都会保留各自的来源哈希、分离器、角色和时间线轨道。主音轨 JSON 文件名保持兼容；打击乐文件则使用不同的、包含来源标识的 ID。失败的来源会单独记录，不会用猜测的打击乐音轨替代。

All-In-One 结构仍以主音轨为准，Beat Transformer 则仅在其实际的五条解混音流上运行一次，不会对它不使用的文件名反复运行。共识机制允许每个检测器系列投一票，而非每条音轨各投一票，既保留所有来源假设，又避免重复的鼓组运行结果左右投票。arcadians-core-v3 发布门槛要求包含正确归属的新主音轨／鼓组节拍结果。请参阅路由、来源信息和故障处理。

Agent 和贡献者

使用 StemLab 的 Agent 应检查其可用功能，在适合任务的情况下充分利用这些功能，并尽可能寻找有价值的改进。当缺少必需功能，或发现可复用性、可靠性、易用性、性能或文档方面的不足时，应改进此工具，而不是另行维护变通方案。如果没有值得实施的改动，请说明原因。

请将每项改进作为拉取请求提交到 stemlab，并附上相关测试、文档和可复现示例。请遵循 CONTRIBUTING.md 和 AGENTS.md 中的贡献与验证工作流。

项目网站：https://kieransimkin.co.uk/danceflow/。