livekit-plugins-volcenginee 1.3.2__tar.gz → 1.3.3__tar.gz

{livekit_plugins_volcenginee-1.3.2 → livekit_plugins_volcenginee-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: livekit-plugins-volcenginee
-Version: 1.3.2
+Version: 1.3.3
 Summary: LiveKit Agent Plugins for Volcengine
 Author-email: linsanzhu <2287225730@qq.com>
 Keywords: audio,livekit,realtime,video,webrtc
@@ -394,18 +394,20 @@ if __name__ == "__main__":
 
 ```python
 volcengine.TTS(
-    api_key: str,                    # API Key（新版控制台）
-    resource_id: str | None = None,  # 默认 seed-tts-2.0
+    api_key: str,                              # API Key（新版控制台）
+    resource_id: str | None = None,            # 默认 seed-tts-2.0
     voice: str = "zh_female_xiaohe_uranus_bigtts",
-    speed: float = 1.0,              # 已废弃，保留仅用于兼容
-    volume: float = 1.0,             # 已废弃，保留仅用于兼容
-    pitch: float = 1.0,              # 已废弃，保留仅用于兼容
-    speech_rate: int = 0,            # 语速，[-50, 100]，100=2.0x，-50=0.5x
-    loudness_rate: int = 0,          # 音量，[-50, 100]，100=2.0x，-50=0.5x（mix 音色暂不支持）
+    speed: float = 1.0,                        # 语速倍率（OpenAI 规范），[0.2, 3.0]，1.0=正常
+    volume: float = 1.0,                       # 音量倍率（OpenAI 规范），(0.1, 3.0]，1.0=正常（mix 音色暂不支持）
+    pitch: float = 1.0,                        # 已废弃，保留仅用于兼容
     sample_rate: Literal[24000, 16000, 8000] = 16000,
 )
 ```
 
+> `speed` / `volume` 遵循 OpenAI 接口规范（float 倍率），请求时按
+> `speech_rate = round((speed - 1.0) * 200)`（clamp 到 `[-50, 100]`）转换为火山原生
+> `speech_rate` / `loudness_rate` 整型字段。
+
 ### TTS 资源 ID 说明
 
 - `seed-tts-2.0`：豆包语音合成模型 2.0

{livekit_plugins_volcenginee-1.3.2 → livekit_plugins_volcenginee-1.3.3}/README.md

@@ -372,18 +372,20 @@ if __name__ == "__main__":
 
 ```python
 volcengine.TTS(
-    api_key: str,                    # API Key（新版控制台）
-    resource_id: str | None = None,  # 默认 seed-tts-2.0
+    api_key: str,                              # API Key（新版控制台）
+    resource_id: str | None = None,            # 默认 seed-tts-2.0
     voice: str = "zh_female_xiaohe_uranus_bigtts",
-    speed: float = 1.0,              # 已废弃，保留仅用于兼容
-    volume: float = 1.0,             # 已废弃，保留仅用于兼容
-    pitch: float = 1.0,              # 已废弃，保留仅用于兼容
-    speech_rate: int = 0,            # 语速，[-50, 100]，100=2.0x，-50=0.5x
-    loudness_rate: int = 0,          # 音量，[-50, 100]，100=2.0x，-50=0.5x（mix 音色暂不支持）
+    speed: float = 1.0,                        # 语速倍率（OpenAI 规范），[0.2, 3.0]，1.0=正常
+    volume: float = 1.0,                       # 音量倍率（OpenAI 规范），(0.1, 3.0]，1.0=正常（mix 音色暂不支持）
+    pitch: float = 1.0,                        # 已废弃，保留仅用于兼容
     sample_rate: Literal[24000, 16000, 8000] = 16000,
 )
 ```
 
+> `speed` / `volume` 遵循 OpenAI 接口规范（float 倍率），请求时按
+> `speech_rate = round((speed - 1.0) * 200)`（clamp 到 `[-50, 100]`）转换为火山原生
+> `speech_rate` / `loudness_rate` 整型字段。
+
 ### TTS 资源 ID 说明
 
 - `seed-tts-2.0`：豆包语音合成模型 2.0

{livekit_plugins_volcenginee-1.3.2 → livekit_plugins_volcenginee-1.3.3}/livekit/plugins/volcengine/tts.py

@@ -24,6 +24,27 @@ from livekit.agents.types import DEFAULT_API_CONNECT_OPTIONS
 from .log import logger
 
 
+def _speed_to_speech_rate(speed: float) -> int:
+    """Convert OpenAI-style ``speed`` (1.0 = normal) to Volcengine ``speech_rate``.
+
+    Mapping: ``speech_rate = round((speed - 1.0) * 200)``, clamped to ``[-50, 100]``.
+
+    1.0 -> 0, 1.5 -> 100, 0.5 -> -50. Values outside the OpenAI-allowed range
+    are clamped at the same boundaries used by the underlying API.
+    """
+    rate = round((speed - 1.0) * 200)
+    return max(-50, min(100, rate))
+
+
+def _volume_to_loudness_rate(volume: float) -> int:
+    """Convert OpenAI-style ``volume`` (1.0 = normal) to Volcengine ``loudness_rate``.
+
+    Same mapping as ``_speed_to_speech_rate``.
+    """
+    rate = round((volume - 1.0) * 200)
+    return max(-50, min(100, rate))
+
+
 class _TTSOptions(BaseModel):
     api_key: str
     resource_id: str | None = None
@@ -31,11 +52,11 @@ class _TTSOptions(BaseModel):
     base_url: str = "https://openspeech.bytedance.com"
     sample_rate: Literal[24000, 16000, 8000] = 24000
     encoding: Literal["mp3", "pcm"] = "pcm"
+    # OpenAI-style primary interface; converted to Volcengine speech_rate/loudness_rate
+    # at request time (see _speed_to_speech_rate / _volume_to_loudness_rate).
     speed: float = Field(1.0, ge=0.2, le=3.0)
     volume: float = Field(1.0, gt=0.1, le=3.0)
     pitch: float = Field(1.0, ge=0.1, le=3.0)
-    speech_rate: int = Field(0, ge=-50, le=100)
-    loudness_rate: int = Field(0, ge=-50, le=100)
 
     def get_http_url(self) -> str:
         return f"{self.base_url}/api/v3/tts/unidirectional"
@@ -55,8 +76,8 @@ class _TTSOptions(BaseModel):
                 "audio_params": {
                     "format": self.encoding,
                     "sample_rate": self.sample_rate,
-                    "loudness_rate": self.loudness_rate,
-                    "speech_rate": self.speech_rate,
+                    "loudness_rate": _volume_to_loudness_rate(self.volume),
+                    "speech_rate": _speed_to_speech_rate(self.speed),
                 },
                 "request_id": reqid,
             },
@@ -85,8 +106,6 @@ class TTS(tts.TTS):
         speed: float = 1.0,
         volume: float = 1.0,
         pitch: float = 1.0,
-        speech_rate: int = 0,
-        loudness_rate: int = 0,
         sample_rate: Literal[24000, 16000, 8000] = 16000,
         http_session: aiohttp.ClientSession | None = None,
     ):
@@ -96,12 +115,10 @@ class TTS(tts.TTS):
             api_key (str): the API key of the tts, you can get it from the new console.
             resource_id (str | None, optional): VolcEngine TTS resource id. Use `seed-tts-2.0` for Doubao TTS 2.0 voices, `seed-tts-1.0` / `seed-tts-1.0-concurr` for Doubao TTS 1.0 voices, `seed-icl-2.0` for voice cloning 2.0, and `seed-icl-1.0` / `seed-icl-1.0-concurr` for voice cloning 1.0. Defaults to None.
             voice (str, optional): the voice id used by the tts request. Defaults to `zh_female_xiaohe_uranus_bigtts`.
-            speed (float, optional): kept for backwards compatibility, no longer sent to the API. Defaults to 1.0.
-            volume (float, optional): kept for backwards compatibility, no longer sent to the API. Defaults to 1.0.
-            pitch (float, optional): kept for backwards compatibility, no longer sent to the API. Defaults to 1.0.
-            speech_rate (int, optional): speech rate, range [-50, 100]. 100 = 2.0x, -50 = 0.5x. Defaults to 0 (normal).
-            loudness_rate (int, optional): volume gain, range [-50, 100]. 100 = 2.0x, -50 = 0.5x. Not supported for mix voices. Defaults to 0 (normal).
-            sample_rate (Literal[24000, 16000, 8000], optional): the sample rate of the tts. Defaults to 24000.
+            speed (float, optional): speech rate multiplier (OpenAI-style). Range [0.2, 3.0]; 1.0 = normal, 2.0 = 2x, 0.5 = 0.5x. Internally converted to the Volcengine ``speech_rate`` int. Defaults to 1.0.
+            volume (float, optional): volume multiplier (OpenAI-style). Range (0.1, 3.0]; 1.0 = normal, 2.0 = 2x, 0.5 = 0.5x. Internally converted to the Volcengine ``loudness_rate`` int. Not supported for mix voices. Defaults to 1.0.
+            pitch (float, optional): kept for backwards compatibility, not currently sent to the API. Defaults to 1.0.
+            sample_rate (Literal[24000, 16000, 8000], optional): the sample rate of the tts. Defaults to 16000.
             streaming (bool, optional): whether to use the streaming api. Defaults to True.
             http_session (aiohttp.ClientSession | None, optional): the http session to use. Defaults to None.
         """
@@ -118,8 +135,6 @@ class TTS(tts.TTS):
             speed=speed,
             volume=volume,
             pitch=pitch,
-            speech_rate=speech_rate,
-            loudness_rate=loudness_rate,
         )
         self._session = http_session
         self._streams = weakref.WeakSet[SynthesizeStream]()

livekit_plugins_volcenginee-1.3.3/livekit/plugins/volcengine/version.py

@@ -0,0 +1 @@
+__version__ = "1.3.3"

livekit_plugins_volcenginee-1.3.2/livekit/plugins/volcengine/version.py

@@ -1 +0,0 @@
-__version__ = "1.3.2"