usage.md

使用指南

安装

pip install -e ".[dev]"

依赖仅 numpy 与 scipy；开发额外需要 pytest / ruff / mypy。

一分钟上手

from foleyflow import train_demo_generator, GenerationConfig

gen, _ = train_demo_generator(epochs=40)          # 现场训练一个小模型
wav = gen.generate("steady rain")                  # -> numpy 波形
gen.generate_to_file("steady rain", "rain.wav")    # 直接写 WAV

选择采样器

sampler	范式	NFE	特点
flow_euler	流匹配	steps	最快，少步即可用
flow_midpoint	流匹配	2×steps	二阶，更稳
flow_heun	流匹配	2×steps	二阶预测-校正
ddim	扩散	steps	确定性，可调 eta
ddpm	扩散	steps	祖先采样（随机）

cfg = GenerationConfig(sampler="flow_heun", steps=60, guidance_scale=3.0, seed=0)
wav = gen.generate("crackling fire", config=cfg)

文本 / 条件

guidance_scale 控制无分类器引导强度：1.0 为纯条件，>1 放大条件（默认 3.0）。 prompt 会被解析为内置标签（含少量同义词，如 raining → rain）。未命中任何标签时退化为无条件。

时序对齐（进阶）

用 EventTimeline 声明事件时刻，配合 align_strength>0 在采样期做能量对齐：

from foleyflow import EventTimeline

timeline = EventTimeline.from_times([0.2, 0.6, 1.0, 1.4])
cfg = GenerationConfig(sampler="flow_heun", align_strength=0.6, steps=60)
gen.generate_to_file("footsteps", "footsteps.wav", timeline=timeline, config=cfg)

评估对齐质量：

from foleyflow.align import onset_envelope_from_mel, dtw

mel = gen.generate_mel("footsteps", timeline=timeline, config=cfg)
cost, path = dtw(onset_envelope_from_mel(mel), timeline.onset_envelope(gen.n_frames, gen.fps))

训练自己的模型

from foleyflow.training import SyntheticFoleyDataset, Trainer
from foleyflow.flow import FlowMatching
from foleyflow.models import MLPDenoiser
from foleyflow.config import ModelConfig
from foleyflow.training.optim import Adam

ds = SyntheticFoleyDataset(n_mels=40, n_frames=64, cond_dim=32)
x, cond, _ = ds.build(samples_per_class=32)

model = MLPDenoiser(ModelConfig(n_mels=40, n_frames=64, hidden_dim=128, cond_dim=32))
trainer = Trainer(model, FlowMatching(), Adam(lr=2e-3))
state = trainer.fit(x, cond, epochs=100, batch_size=32)

想接入真实语料：把你的音频用 MelSpectrogram.forward 转成归一化梅尔谱、裁到固定帧数、 展平为 (N, n_mels*n_frames)，再配上条件向量即可复用同一套训练器。

保存 / 加载

path = gen.save("model.npz")
from foleyflow import FoleyGenerator
gen2 = FoleyGenerator.load(path, tags=list(gen.vocab.tags))

命令行

foleyflow info
foleyflow tags
foleyflow generate "wind through trees" -o wind.wav --sampler flow_euler --steps 60
foleyflow generate "footsteps" -o steps.wav --events 0.2,0.6,1.0 --align 0.6
foleyflow train -o model.npz --epochs 100