usage.md

使用指南

特征提取

import numpy as np
from voxmorph.config import FeatureConfig
from voxmorph.features.mel import melspectrogram
from voxmorph.features.mfcc import mfcc
from voxmorph.datasets import synth_speaker

cfg = FeatureConfig(sample_rate=16_000, n_fft=400, hop_length=160, n_mels=80)
wav = synth_speaker("carol", content_seed=3, duration=1.0)

mel = melspectrogram(wav, cfg)   # (帧数, 80)
mf = mfcc(wav, cfg)              # (帧数, n_mfcc)

FeatureConfig 是不可变 dataclass，构造时会校验参数（例如 win_length 不得超过 n_fft、fmax 会被裁剪到 Nyquist）。

说话人嵌入与相似度

from voxmorph.disentangle.speaker import SpeakerEncoder
from voxmorph.evaluation.similarity import cosine_similarity

enc = SpeakerEncoder()
e1 = enc.embed(synth_speaker("alice", content_seed=1))
e2 = enc.embed(synth_speaker("alice", content_seed=2))
print(cosine_similarity(e1, e2))   # 同一说话人 → 相似度较高

语音转换

from voxmorph import VoiceConverter
from voxmorph.config import ConversionConfig

converter = VoiceConverter(
    conversion_config=ConversionConfig(griffin_lim_iters=80, preserve_energy=True),
)
converted = converter.convert(source, target)

如果要把同一个目标音色应用到多段源语音，可以先算好目标统计量再复用：

stats = converter.speaker_stats(target)
outs = [converter.convert_with_stats(src, stats) for src in sources]

转换质量评价

from voxmorph.evaluation.quality import (
    mel_cepstral_distortion, signal_to_noise_ratio, log_spectral_distance,
)

print("MCD:", mel_cepstral_distortion(reference, converted))
print("LSD:", log_spectral_distance(reference, converted))
print("SNR:", signal_to_noise_ratio(reference, converted))

选择计算后端

from voxmorph.features.stft import stft

S_numpy = stft(wav)                    # 默认 NumPy
S_torch = stft(wav, backend="torch")   # 需要安装 voxmorph[torch]

命令行

所有命令都接受 WAV / .npy 文件，便于离线批处理，详见 voxmorph --help。