xiaoxia-saas/packages/domain/preset_voices.py

"""预置音色配置 — Phase 3 CosyVoice 集成.

定义系统预置的 CosyVoice 音色列表，不存数据库，以配置方式提供。
音色 ID 对应阿里云 CosyVoice 模型中的真实音色名。

参考: https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
"""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class PresetVoice:
    """预置音色定义。

    Attributes:
        voice_id: CosyVoice 模型音色名（如 longxiaochun_v3）
        name: 中文展示名
        description: 音色描述
        gender: 性别（male/female）
        language: 语言代码（如 zh-CN）
        preview_url: 预览音频 URL（可选）
        tags: 标签列表
    """

    voice_id: str
    name: str
    description: str
    gender: str
    language: str = "zh-CN"
    preview_url: str = ""
    tags: list[str] | None = None

    def to_dict(self) -> dict:
        """序列化为字典。"""
        return {
            "voice_id": self.voice_id,
            "name": self.name,
            "description": self.description,
            "gender": self.gender,
            "language": self.language,
            "preview_url": self.preview_url,
            "tags": self.tags or [],
        }


# 预置音色列表（阿里云 CosyVoice v3-flash 真实可用音色）
# 参考: https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
PRESET_VOICES: list[PresetVoice] = [
    PresetVoice(
        voice_id="longxiaochun_v3",
        name="龙小淳",
        description="知性积极女声，适合语音助手",
        gender="female",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/a8fb29a2-7d44-9f16-9dab-f17fa806cf3d.mp3?Expires=1785716123&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=c74kFX%2BcDpmuBny2dPBkvak01oY%3D",
        tags=["知性", "女声", "助手"],
    ),
    PresetVoice(
        voice_id="longxiaoxia_v3",
        name="龙小夏",
        description="沉稳权威女声，适合新闻播报",
        gender="female",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/d065a6da-de0d-9ad2-b64a-00aaf9aa3dea.mp3?Expires=1785716203&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=9hRh7xbmS8eDdiBDDFUatvad1jg%3D",
        tags=["沉稳", "女声", "播报"],
    ),
    PresetVoice(
        voice_id="longsanshu_v3",
        name="龙三叔",
        description="沉稳质感男声，适合有声书",
        gender="male",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/b139d925-4669-979d-89db-2dc16945b577.mp3?Expires=1785730686&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=X2p%2FA7Dm%2BTNfeFilW%2FQO9VoYPLQ%3D",
        tags=["沉稳", "男声", "有声书"],
    ),
    PresetVoice(
        voice_id="longyue_v3",
        name="龙悦",
        description="温暖磁性女声，适合广告配音",
        gender="female",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/1ea86db3-4dc9-927e-9b76-c83d89f6788c.mp3?Expires=1785716207&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=Vg0ckgSgPzgNQ%2FNdeJzrE%3D",
        tags=["温暖", "女声", "广告"],
    ),
    PresetVoice(
        voice_id="longshu_v3",
        name="龙书",
        description="沉稳青年男声，适合教育讲解",
        gender="male",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/6b47a5ce-ae21-995a-ac8b-5e55ed04ec45.mp3?Expires=1785716209&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=zm6WGmthpwTjf8PzgNQ%2FNdeJzrE%3D",
        tags=["沉稳", "男声", "教育"],
    ),
    PresetVoice(
        voice_id="longyingjing_v3",
        name="龙应静",
        description="低调冷静女声，适合纪录片解说",
        gender="female",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/13bf9f6a-72a9-949c-a896-ec3e6b46338b.mp3?Expires=1785730692&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=pxrP2rYmOumc4dw9TD8TZf%2B27gk%3D",
        tags=["冷静", "女声", "纪录片"],
    ),
    PresetVoice(
        voice_id="longshuo_v3",
        name="龙硕",
        description="博才干练男声，适合科技类内容",
        gender="male",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/5e69f0c1-45fa-92ca-ae5c-38272f231efb.mp3?Expires=1785730692&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=uREIiIUFrN7CpJ7avXKWCo04A6I%3D",
        tags=["干练", "男声", "科技"],
    ),
    PresetVoice(
        voice_id="longtian_v3",
        name="龙甜",
        description="活泼女声，适合短视频配音",
        gender="female",
        language="zh-CN",
        preview_url="http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/cosyvoice-v3-flash/20260802/1320180660510733/a38e4c05-25bf-9640-92d6-0b4a14555cdb.mp3?Expires=1785716215&OSSAccessKeyId=LTAI5tGzqbGcEmE58b221XQy&Signature=WtbsqqfR4A6OhpL%2B%2Fe0lh7YBMWM%3D",
        tags=["活泼", "女声", "短视频"],
    ),
]


def get_preset_voices() -> list[PresetVoice]:
    """获取所有预置音色。"""
    return PRESET_VOICES


def get_preset_voice_by_id(voice_id: str) -> PresetVoice | None:
    """根据 voice_id 获取预置音色。"""
    for voice in PRESET_VOICES:
        if voice.voice_id == voice_id:
            return voice
    return None


def is_preset_voice(voice_id: str) -> bool:
    """判断是否为预置音色。"""
    return get_preset_voice_by_id(voice_id) is not None