nex_animation/backend/app/services/timbre.py

486 lines
24 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""音色自检:用基频(F0)客观判断一段音频实际是男声还是女声。
为什么需要这一层:IndexTTS2 这类 zero-shot 克隆模型**只认参考音频**,
表单里的「性别 / 音色描述」对模型来说是纯元数据。于是出现过很荒唐的一幕——
用户在平台资产库里把声线性别填成「男声」,因为没上传参考音频,
生成时回退到模型配置里的那一段默认参考(女声),出来的试听样本是女声,
界面却全绿、什么都不说。
这里做两件事:
1. ``resolve_reference()``:生成前按性别挑一段**真正能决定音色**的参考音频,
挑不到就明确报错,绝不静默用默认嗓;
2. ``check_voice()``:生成后量一次中位基频,与设定性别比对,
结果写进素材 metadata,界面能直接看到「音色与设定不符」。
"""
from __future__ import annotations
import os
import re
import shutil
import subprocess
import tempfile
from pathlib import Path
from sqlalchemy import select
from sqlalchemy.orm import Session
from app.services import storage
# 成人基频经验区间:男声 85–155 Hz、女声 165–300 Hz,中间留一段不妄下结论。
MALE_F0_MAX = 155.0
FEMALE_F0_MIN = 175.0
_SAMPLE_RATE = 8000
_FRAME = 400 # 50 ms,够容纳 70 Hz 的两个周期
_HOP = 200 # 25 ms
_LAG_LO = int(_SAMPLE_RATE / 350) # 最高 350 Hz
_LAG_HI = int(_SAMPLE_RATE / 70) # 最低 70 Hz
_MAX_FRAMES = 260 # 纯 Python 逐帧算,长音频均匀抽样即可
# 折子谐波时「算真谷」的容差:谷深至少要比无周期水平低到全局最深谷的 45% 以内才认。
_FOLD_TOLERANCE = 0.45
GENDER_LABELS = {"male": "男声", "female": "女声", "neutral": "中性声"}
#: 声线绑定指向 AI 试听样本时的统一开场白:解释为什么「有声音文件」不等于「有音色」。
_AI_BOUND_NOTE = "声线现在绑的是 AI 生成的试听样本,它不能反过来当克隆参考(否则错音色会自我强化);"
def _decode(path: Path) -> list[int]:
"""把任意音频解成 8 kHz 单声道 PCM 整数序列(不引入 numpy 依赖)。"""
# 必须走项目的 ffmpeg 解析器:本机 ffmpeg 常常不在 PATH 上(配置指定 /
# 静态构建装在非标准目录)。直接 shutil.which 会静默返回空 → 音色自检
# 永远「测不出基频」,这个保护就变成了摆设还没人发现。
from app.services import ffmpeg as ff
ffmpeg = ff.FFMPEG if ff.available() else (shutil.which("ffmpeg") or "")
if not ffmpeg:
return []
with tempfile.TemporaryDirectory() as tmp:
raw = Path(tmp) / "pcm.raw"
try:
subprocess.run([ffmpeg, "-y", "-v", "error", "-i", str(path), "-ac", "1",
"-ar", str(_SAMPLE_RATE), "-f", "s16le", str(raw)],
check=True, capture_output=True, timeout=120)
except (subprocess.SubprocessError, OSError):
return []
if not raw.exists():
return []
import array
samples = array.array("h")
samples.frombytes(raw.read_bytes())
return samples.tolist()
def estimate_f0(path: str | Path) -> float | None:
"""中位基频(Hz)。取不出可靠音帧时返回 None,而不是猜一个。"""
produced = Path(path)
if not produced.exists():
return None
samples = _decode(produced)
if len(samples) < _FRAME * 4:
return None
# 先用整段能量的分位数定音门限,避免把静音/呼吸当音高。
energies: list[tuple[int, float]] = []
for start in range(0, len(samples) - _FRAME, _HOP):
frame = samples[start:start + _FRAME]
energies.append((start, sum(value * value for value in frame) / _FRAME))
if not energies:
return None
ordered = sorted(energy for _, energy in energies)
loud = ordered[int(len(ordered) * 0.95)] if len(ordered) > 20 else ordered[-1]
threshold = max(1500.0, loud * 0.06)
voiced = [(start, energy) for start, energy in energies if energy >= threshold]
if len(voiced) < 4:
return None
step = max(1, len(voiced) // _MAX_FRAMES)
voiced = voiced[::step]
pitches: list[float] = []
for start, _energy in voiced:
frame = samples[start:start + _FRAME]
# 平均幅度差函数(AMDF):比自相关省一半算力,对浊音同样稳定。
# 必须**按参与项数取平均**:lag 越大参与相减的样本越少,直接比总和会让
# 2 倍 / 3 倍周期的谷“看起来更深”,把 250 Hz 的女声读成 83 Hz 的“男声”。
amdf: list[float] = []
for lag in range(_LAG_LO, _LAG_HI):
total = 0
terms = 0
for index in range(0, _FRAME - lag, 2):
total += abs(frame[index] - frame[index + lag])
terms += 1
amdf.append(total / max(terms, 1))
if len(amdf) < 4:
continue
# flat = 这段“没有周期可比”时的平均水平,best = 最深的那个谷。
# 两者一起用来判音:谷不够深说明这帧是清音/噪声,直接丢。
flat = sum(amdf) / len(amdf)
index = min(range(len(amdf)), key=lambda i: amdf[i])
best = amdf[index]
if not flat or best >= flat * 0.72:
continue
period = _fold_submultiple(amdf, _refine(amdf, index), best, flat)
pitches.append(_SAMPLE_RATE / period)
if len(pitches) < 4:
return None
pitches.sort()
return round(pitches[len(pitches) // 2], 1)
def _amdf_at(amdf: list[float], period: float) -> float:
"""在**非整数周期**上取 AMDF 值(线性插值)。
基频几乎不会正好落在整数采样点上(300 Hz @ 8 kHz = 26.67 点),
只能在相邻两个 lag 之间插,否则永远量不到真正的谷,八度错误就是这么来的。
"""
if period < _LAG_LO:
return float("inf")
# amdf[0] 对应 lag=_LAG_LO,所以要减掉偏移再取;越界一律贴边而不是抛错。
last = len(amdf) - 1
low = min(int(period) - _LAG_LO, last)
ratio = min(max(period - _LAG_LO - low, 0.0), 1.0) # 落在最后一点时只剩左侧可用
left = amdf[low]
right = amdf[low + 1] if low + 1 <= last else left
return left + (right - left) * ratio
def _fold_submultiple(amdf: list[float], lag: float, best: float, flat: float) -> float:
"""把「整数倍周期」的谷折回真正的基频周期。
周期不是整数个采样点时(300 Hz @ 8 kHz = 26.67 点),3 倍周期恰好落在整数 lag=80 上,
AMDF 的全局最低谷会出现在 80 而不是 26.67 —— 音高直接低一个八度以上,
女声被读成男声(实测 300 Hz 被判成 100 Hz),音色自检就白做了。
判据:如果最短周期的 1/2、1/3、1/4 处本身也是一个**货真价实的深谷**
(深度接近全局最深谷、且是局部极小),说明现在这个谷只是它的整数倍。
用「相对谷深」而不是归一化互相关阈值:真男声在半周期处是**峰**(波形不对称),
根本过不了这条线,所以不会反过来把男声折成女声。
"""
folded = float(lag)
for _round in range(3): # 折一次后可能还能再折,迭代收敛
improved = False
for divisor in (2, 3, 4):
candidate = folded / divisor
if candidate < _LAG_LO:
continue
depth = _amdf_at(amdf, candidate)
if depth >= best + _FOLD_TOLERANCE * (flat - best):
continue # 这里不够深:不是真周期,别折
# 还得是局部极小,否则只是在两个采样点里挑了个顺眼的
if any(_amdf_at(amdf, candidate + delta) < depth - 1e-9
for delta in (-1.0, 1.0)):
continue
folded = candidate
improved = True
break
if not improved:
break
return folded
def _refine(amdf: list[float], index: int) -> float:
"""对最深谷做抛物线插值,把周期量到亚采样点精度。
8 kHz 下 250 Hz 的周期是 32 点、247.5 Hz 是 32.32 点,两者整数 lag 都是 32;
不插值就只能报 250.0,边界性别(155/175 Hz 附近)会判得不稳。
"""
if index <= 0 or index >= len(amdf) - 1:
return float(index + _LAG_LO)
# 抛物线的极值点必须留在相邻三点之间,否则噪声帧会把它甩出整个 lag 区间
left, middle, right = amdf[index - 1], amdf[index], amdf[index + 1]
denominator = left - 2 * middle + right
if denominator <= 1e-9:
return float(index + _LAG_LO)
shift = 0.5 * (left - right) / denominator
shift = max(-1.0, min(1.0, shift))
return float(index + _LAG_LO + shift)
def gender_of(f0: float | None) -> str:
if not f0:
return ""
if f0 <= MALE_F0_MAX:
return "male"
if f0 >= FEMALE_F0_MIN:
return "female"
return "neutral" # 落在男女交界区,不硬判
def check_voice(path: str | Path, declared_gender: str = "") -> dict:
"""量一次音色并和设定比对。返回可直接进 metadata / 前端的结构。"""
f0 = estimate_f0(path)
actual = gender_of(f0)
declared = str(declared_gender or "").strip()
result: dict = {"f0_hz": f0, "timbre_gender": actual,
"timbre_gender_label": GENDER_LABELS.get(actual, "未判定"),
"declared_gender": declared,
"declared_gender_label": GENDER_LABELS.get(declared, "未指定"),
"matched": None, "note": ""}
if f0 is None:
result["note"] = "未能从试听样本中提取稳定基频,无法自动判定音色性别"
return result
if declared in ("", "neutral"):
result["note"] = f"中位基频 {f0} Hz,听感接近{result['timbre_gender_label'] or '未判定'};设定未限定性别"
return result
if actual == "neutral":
result["note"] = f"中位基频 {f0} Hz,处于男女声交界区,建议试听确认"
return result
result["matched"] = actual == declared
result["note"] = (f"中位基频 {f0} Hz,判定为{result['timbre_gender_label']},"
f"与设定「{result['declared_gender_label']}」一致" if result["matched"] else
f"中位基频 {f0} Hz,实际是{result['timbre_gender_label']},"
f"与设定「{result['declared_gender_label']}」不符:请换一段{result['declared_gender_label']}"
f"参考音频重新生成")
return result
def clone_model(spec) -> bool:
"""这个 TTS 是否靠参考音频决定音色。
IndexTTS2(``comfyui_tts``)是 zero-shot 克隆:给它什么参考就是什么嗓子,
表单里的性别/描述完全不影响。云端音色库反过来——音色由 provider_voice_id 选定,
本地参考音频可有可无。两种模型不能共用一套「缺参考就报错」的规则。
"""
if spec is None:
return False
if str(getattr(spec, "adapter", "") or "") == "comfyui_tts":
return True
return bool((getattr(spec, "config_json", None) or {}).get("clone_reference"))
def audio_path_or_empty(value: str | None) -> str:
"""声线记录里的 provider_voice_id 可能是显示名(如「低沉男声」),只有真音频路径才算数。"""
from app.services.audio import AUDIO_SUFFIXES
candidate = str(value or "").strip()
if not candidate or Path(candidate).suffix.lower() not in AUDIO_SUFFIXES:
return ""
absolute = Path(storage.to_absolute(candidate))
return str(absolute) if absolute.exists() else ""
def _owner_media_rows(db: Session, owner) -> list:
"""本声线名下的参考/音色素材(平台母版走 PlatformMedia,项目声线走 Asset)。"""
from app.models import Asset, PlatformMedia, PlatformVoice
if isinstance(owner, PlatformVoice):
return list(db.scalars(
select(PlatformMedia).where(PlatformMedia.owner_type == "voice",
PlatformMedia.owner_id == owner.id,
PlatformMedia.kind.in_(("reference", "voice_sample")))
).all())
return list(db.scalars(
select(Asset).where(Asset.owner_type == "voice", Asset.owner_id == owner.id,
Asset.kind.in_(("reference", "voice_sample")))
).all())
#: 模型产出的素材都带这两个记号之一:显示名里的「· AI 音色样本」,或落盘文件名里的 ``-ai`` 段
#: (``voice-3-voice_sample-ai_89ecda6f.wav``)。用来兜住引入/上架时没带走 generated 标记的老数据。
#: 刻意不匹配「sample.wav」这种普通上传名:判错的方向虽然保守,但让用户看着自己上传的
#: 参考音频被告知「没有音色可用」,比错音色自我强化更难解释。
_AI_DISPLAY_NAME = re.compile(r"(?:·|\|)\s*AI\s|\bAI\s+音色")
_AI_FILE_NAME = re.compile(r"(?:^|[-_])ai(?:[-_.]|$)", re.IGNORECASE)
def _is_generated(media) -> bool:
"""这段音频是不是模型生成的,而不是真人录的。
先看元数据;老数据(引入/上架时没带走 ``generated``)再按命名兜底。
判成「模型生成」是保守方向:宁可让用户补一次参考音频,
也不能让 AI 的嗓门被当成真人参考、继续克隆它自己的输出。
"""
meta = getattr(media, "metadata_json", None) or {}
if meta.get("generated"):
return True
if _AI_DISPLAY_NAME.search(str(getattr(media, "name", "") or "")):
return True
files = (str(meta.get("original_name") or ""), Path(str(getattr(media, "path", "") or "")).name)
return any(_AI_FILE_NAME.search(name) for name in files)
def provenance_of(media) -> dict:
"""引入 / 上架时一起带走的音色出身信息。
复制素材时丢掉 ``generated`` 标记,等于把「AI 生成的试听样本」洗白成
「真人参考音频」:下一次生成就会克隆它自己的输出,错音色从此自我强化、再也翻不出来。
"""
if not _is_generated(media):
return {}
meta = getattr(media, "metadata_json", None) or {}
return {"generated": True, "generated_model": meta.get("model") or "",
"generated_provider": meta.get("provider") or ""}
def _identity(path: str) -> str:
"""同一个文件的相对/绝对/软链写法归一,比对绑定字段时才认得出是同一个嗓子。"""
try:
return os.path.realpath(path)
except OSError:
return str(path)
def generated_audio_index(db: Session, owner) -> dict[str, object]:
"""本声线名下所有「模型生成」的音频文件 → 素材行。"""
index: dict[str, object] = {}
for media in _owner_media_rows(db, owner):
if not _is_generated(media):
continue
candidates = [getattr(media, "path", "")]
candidates += [row.path for row in (getattr(media, "versions", None) or [])]
for candidate in candidates:
absolute = audio_path_or_empty(candidate)
if absolute:
index[_identity(absolute)] = media
return index
def own_reference(db: Session, owner, *, detail: dict | None = None) -> str:
"""这个声线自己能不能决定音色:先看绑定字段,再看它名下的音色素材。
**AI 生成的试听样本不能反过来当参考音频。** 生成样本的音色本来就是这次要定的结论,
再拿它当输入就成了自我强化的循环:一旦某次因为缺参考出了个女声,
下一次生成会把这个女声样本当「本声线自己的嗓子」继续克隆,怎么重试都是女声。
用户上传的样本不在其列——那本来就是真人录音,可以正当当参考。
``detail`` 传字典时会记下「声线当前绑着的其实就是 AI 样本」,
界面才能解释「我明明有声音文件,为什么说我没有音色」。
"""
generated = generated_audio_index(db, owner)
bound = str(getattr(owner, "provider_voice_id", "") or "").strip()
direct = audio_path_or_empty(bound)
# 「绑的是不是 AI 样本」跟文件此刻还在不在无关:样本被删了也要照样说清楚,
# 否则界面只显示「没有任何音色」,用户看不懂自己挂上去的那段声音去哪了。
bound_is_ai = bool(bound) and (_identity(bound) in generated
or bool(_AI_FILE_NAME.search(Path(bound).name)))
if bound_is_ai:
if detail is not None:
detail["bound_generated"] = True
elif direct:
return direct
rows = sorted(_owner_media_rows(db, owner), key=lambda row: row.id, reverse=True)
for media in rows: # 先认真正的参考音频
if _is_generated(media):
continue
path = audio_path_or_empty(getattr(media, "path", ""))
if path:
return path
return ""
def _imported_master(db: Session, owner):
"""项目声线是从平台母版引入的时,返回那条母版;否则 None。
引入过程可能只带走了设定、没带走参考音频。这种情况下最像这个角色的是**它自己的母版**,
而不是随便借一个同性别的路人嗓子。
"""
from app.models import PlatformVoice as _PV
source_id = getattr(owner, "platform_source_id", None)
if (source_id and getattr(owner, "platform_source_type", "") == "voice"
and not isinstance(owner, _PV)):
return db.get(_PV, source_id)
return None
def _same_gender_voices(db: Session, owner, gender: str) -> list:
"""库里同性别、且真的带着参考音频的其他声线:先项目内,再平台母版。"""
from app.models import PlatformVoice as _PV
from app.models import VoiceAsset as _VA
peers: list = []
project_id = getattr(owner, "project_id", None)
if project_id and not isinstance(owner, _PV):
peers += list(db.scalars(
select(_VA).where(_VA.project_id == project_id, _VA.id != owner.id,
_VA.gender == gender)
).all())
peers += [row for row in db.scalars(
select(_PV).where(_PV.gender == gender, _PV.is_active.is_(True))
).all() if not isinstance(owner, _PV) or row.id != owner.id]
return sorted(peers, key=lambda row: (not getattr(row, "is_default", False), -row.id))
def resolve_reference(db: Session, owner, *, explicit: str = "", clone: bool = True) -> dict:
"""挑一段真正能决定音色的参考音频,并说明它是谁。
优先级:人工指定 → 本声线自己的参考 → 引入自的平台母版 → **同性别的其他声线** → 模型默认。
关键在倒数第二级:设定了性别却没有任何同性别参考时,必须报错,
不能让「男声」悄悄用上默认女声底模(这正是平台上「男性声音生成成女声」的成因)。
``clone=False`` 表示这个 TTS 走云端音色库(provider_voice_id 是音色 ID,不是参考音频),
此时没有本地参考音频不算问题,交回供应商音色 ID 处理。
"""
chosen = audio_path_or_empty(explicit)
if not clone:
# 云端音色库靠 provider_voice_id 选音色,本地参考**不能**顶替它:
# 把 WAV 路径当音色 ID 发过去,macos_say 之类会直接拿到一个不存在的嗓门。
# 但用户手动挂上来的参考仍然记进 attached,供素材元数据回溯用了哪段音频。
return {"path": "", "attached": chosen, "source": "provider_voice",
"note": ("该模型用供应商音色 ID 选音色,本地参考音频只作记录、不决定音色"
if chosen else "该模型用供应商音色 ID 选音色,不依赖本地参考音频")}
if chosen:
return {"path": chosen, "attached": chosen, "source": "manual",
"note": "使用你在生成表单里选定的参考音频"}
detail: dict = {}
own = own_reference(db, owner, detail=detail)
if own:
return {"path": own, "source": "self", "bound_generated": False,
"note": "使用本声线已绑定的参考音频"}
bound_generated = bool(detail.get("bound_generated"))
master = _imported_master(db, owner)
if master is not None:
master_path = own_reference(db, master)
if master_path:
return {"path": master_path, "source": "platform_master",
"voice_name": master.name, "bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE + f"本次沿用它的平台母版「{master.name}」的音色"
if bound_generated else
"本声线还没有带自己的参考音频,本次沿用它的平台母版"
f"「{master.name}」的音色")}
gender = str(getattr(owner, "gender", "") or "").strip()
if gender in GENDER_LABELS and gender != "neutral":
for sibling in _same_gender_voices(db, owner, gender):
path = own_reference(db, sibling)
if path:
return {"path": path, "source": "gender_sibling", "voice_name": sibling.name,
"bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE +
f"本次以同性别声线「{sibling.name}」的音色为底生成;"
f"想固定成自己的嗓子,请上传一段{GENDER_LABELS[gender]}真人参考音频"
if bound_generated else
f"本声线还没有参考音频,本次以同性别声线「{sibling.name}」的音色为底生成;"
f"想固定成自己的嗓子,请上传一段{GENDER_LABELS[gender]}参考音频")}
return {"path": "", "source": "none", "bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE + f"库里也没有任何{GENDER_LABELS[gender]}参考音频可用:"
f"请上传一段{GENDER_LABELS[gender]}真人参考音频再生成"
if bound_generated else
f"库里没有任何{GENDER_LABELS[gender]}参考音频可用:"
f"请上传一段{GENDER_LABELS[gender]}参考音频再生成,"
f"否则会拿到与设定不符的音色")}
return {"path": "", "source": "model_default", "bound_generated": bound_generated,
"note": (_AI_BOUND_NOTE + "本次使用模型配置的默认参考音频(音色不受表单控制)"
if bound_generated else
"声线未限定性别,本次使用模型配置的默认参考音频(音色不受表单控制)")}
def reference_status(db: Session, owner, *, clone: bool = True) -> dict:
"""给界面用的预告:现在点「生成」会拿到谁的嗓子,值不值得先传参考音频。"""
resolved = resolve_reference(db, owner, clone=clone)
gender = str(getattr(owner, "gender", "") or "").strip()
return {
"gender": gender,
"gender_label": GENDER_LABELS.get(gender, "未设定"),
"source": resolved["source"],
"note": resolved["note"],
"borrowed": resolved["source"] in ("gender_sibling", "platform_master"),
# 用户视角的「我明明传过声音」:绑定的是 AI 样本时界面必须说清楚为什么不算
"bound_generated": bool(resolved.get("bound_generated")),
"ready": (bool(resolved["path"]) or resolved["source"] in ("model_default", "provider_voice")),
}