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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: livekit-plugins-volcenginee
-Version: 1.3.1
+Version: 1.3.3
 Summary: LiveKit Agent Plugins for Volcengine
 Author-email: linsanzhu <2287225730@qq.com>
 Keywords: audio,livekit,realtime,video,webrtc
@@ -40,6 +40,7 @@ Description-Content-Type: text/markdown
 - `volcengine.STT` 已补齐新版握手头 `X-Api-Connect-Id`
 - `volcengine.STT` 切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
 - `volcengine.TTS` 同步切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
+- `volcengine.RealtimeModel` 同步切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
 
 ## ✨ 特性
 
@@ -100,7 +101,7 @@ pip install -e .
 | `VOLCENGINE_TTS_API_KEY` | TTS 服务的 API Key（新版控制台） | [语音合成控制台](https://console.volcengine.com/speech/service/16) |
 | `VOLCENGINE_STT_API_KEY` | STT 服务的 API Key（新版控制台） | [语音识别控制台](https://console.volcengine.com/speech/service/16) |
 | `VOLCENGINE_LLM_API_KEY` | LLM 服务的 API 密钥 | [大模型控制台](https://console.volcengine.com/ark/) |
-| `VOLCENGINE_REALTIME_ACCESS_TOKEN` | 实时服务的访问令牌 | [实时语音控制台](https://console.volcengine.com/speech/service/10011) |
+| `VOLCENGINE_REALTIME_API_KEY` | 实时服务的 API Key（新版控制台） | [实时语音控制台](https://console.volcengine.com/speech/service/10011) |
 | `VOLCENGINE_TTS_RESOURCE_ID` | TTS 资源 ID，默认 `seed-tts-2.0` | [豆包语音合成接口文档](https://www.volcengine.com/docs/6561/1257584) |
 
 ### .env 文件示例
@@ -110,7 +111,7 @@ pip install -e .
 VOLCENGINE_TTS_API_KEY=your_tts_api_key_here
 VOLCENGINE_STT_API_KEY=your_stt_api_key_here
 VOLCENGINE_LLM_API_KEY=your_llm_api_key_here
-VOLCENGINE_REALTIME_ACCESS_TOKEN=your_realtime_token_here
+VOLCENGINE_REALTIME_API_KEY=your_realtime_api_key_here
 ```
 
 ## 📖 使用指南
@@ -127,8 +128,7 @@ async def entry_point(ctx: JobContext):
 
     # 使用实时语音模型
     llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="智能助手",
         model="O"  # 或 "SC"
     )
@@ -186,8 +186,7 @@ async def entry_point(ctx: JobContext):
 
     # 基础实时语音模型配置
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="豆包",  # 机器人名称
         model="O"  # 默认使用O版本，功能全面
     )
@@ -220,8 +219,7 @@ async def entry_point(ctx: JobContext):
 
     # 高级配置 - 包含网络搜索和RAG功能
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="智能助手",
         model="O",  # O版本支持联网搜索和RAG，SC版本专注角色扮演
         enable_volc_websearch=True,  # 启用联网搜索
@@ -329,8 +327,7 @@ async def entry_point(ctx: JobContext):
 
     # SC版本支持角色配置和克隆音色
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="小智",
         model="SC",  # SC版本支持character_manifest
         character_manifest='{  # JSON字符串格式的角色配置
@@ -397,16 +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,
+    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
@@ -450,8 +451,7 @@ volcengine.LLM(
 ```python
 volcengine.RealtimeModel(
     # 必需参数
-    app_id: str = None,                    # 应用ID，从环境变量 VOLCENGINE_REALTIME_APP_ID 获取
-    access_token: str = None,              # 访问令牌，从环境变量 VOLCENGINE_REALTIME_ACCESS_TOKEN 获取
+    api_key: str = None,                   # API Key（新版控制台），从环境变量 VOLCENGINE_REALTIME_API_KEY 获取
 
     # 基本配置
     bot_name: str = "豆包",                # 机器人名称
@@ -590,6 +590,7 @@ A: 根据您的应用需求选择合适的版本：
 - `volcengine.STT` 补齐 `X-Api-Connect-Id` 握手头
 - `volcengine.STT` 切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
 - `volcengine.TTS` 同步切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
+- `volcengine.RealtimeModel` 同步切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
 
 ## 🤝 贡献
 

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

@@ -18,6 +18,7 @@
 - `volcengine.STT` 已补齐新版握手头 `X-Api-Connect-Id`
 - `volcengine.STT` 切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
 - `volcengine.TTS` 同步切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
+- `volcengine.RealtimeModel` 同步切换到新版控制台鉴权，仅使用 `X-Api-Key` 头
 
 ## ✨ 特性
 
@@ -78,7 +79,7 @@ pip install -e .
 | `VOLCENGINE_TTS_API_KEY` | TTS 服务的 API Key（新版控制台） | [语音合成控制台](https://console.volcengine.com/speech/service/16) |
 | `VOLCENGINE_STT_API_KEY` | STT 服务的 API Key（新版控制台） | [语音识别控制台](https://console.volcengine.com/speech/service/16) |
 | `VOLCENGINE_LLM_API_KEY` | LLM 服务的 API 密钥 | [大模型控制台](https://console.volcengine.com/ark/) |
-| `VOLCENGINE_REALTIME_ACCESS_TOKEN` | 实时服务的访问令牌 | [实时语音控制台](https://console.volcengine.com/speech/service/10011) |
+| `VOLCENGINE_REALTIME_API_KEY` | 实时服务的 API Key（新版控制台） | [实时语音控制台](https://console.volcengine.com/speech/service/10011) |
 | `VOLCENGINE_TTS_RESOURCE_ID` | TTS 资源 ID，默认 `seed-tts-2.0` | [豆包语音合成接口文档](https://www.volcengine.com/docs/6561/1257584) |
 
 ### .env 文件示例
@@ -88,7 +89,7 @@ pip install -e .
 VOLCENGINE_TTS_API_KEY=your_tts_api_key_here
 VOLCENGINE_STT_API_KEY=your_stt_api_key_here
 VOLCENGINE_LLM_API_KEY=your_llm_api_key_here
-VOLCENGINE_REALTIME_ACCESS_TOKEN=your_realtime_token_here
+VOLCENGINE_REALTIME_API_KEY=your_realtime_api_key_here
 ```
 
 ## 📖 使用指南
@@ -105,8 +106,7 @@ async def entry_point(ctx: JobContext):
 
     # 使用实时语音模型
     llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="智能助手",
         model="O"  # 或 "SC"
     )
@@ -164,8 +164,7 @@ async def entry_point(ctx: JobContext):
 
     # 基础实时语音模型配置
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="豆包",  # 机器人名称
         model="O"  # 默认使用O版本，功能全面
     )
@@ -198,8 +197,7 @@ async def entry_point(ctx: JobContext):
 
     # 高级配置 - 包含网络搜索和RAG功能
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="智能助手",
         model="O",  # O版本支持联网搜索和RAG，SC版本专注角色扮演
         enable_volc_websearch=True,  # 启用联网搜索
@@ -307,8 +305,7 @@ async def entry_point(ctx: JobContext):
 
     # SC版本支持角色配置和克隆音色
     realtime_llm = volcengine.RealtimeModel(
-        app_id="your_app_id",
-        access_token="your_access_token",
+        api_key="your_api_key",
         bot_name="小智",
         model="SC",  # SC版本支持character_manifest
         character_manifest='{  # JSON字符串格式的角色配置
@@ -375,16 +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,
+    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
@@ -428,8 +429,7 @@ volcengine.LLM(
 ```python
 volcengine.RealtimeModel(
     # 必需参数
-    app_id: str = None,                    # 应用ID，从环境变量 VOLCENGINE_REALTIME_APP_ID 获取
-    access_token: str = None,              # 访问令牌，从环境变量 VOLCENGINE_REALTIME_ACCESS_TOKEN 获取
+    api_key: str = None,                   # API Key（新版控制台），从环境变量 VOLCENGINE_REALTIME_API_KEY 获取
 
     # 基本配置
     bot_name: str = "豆包",                # 机器人名称
@@ -568,6 +568,7 @@ A: 根据您的应用需求选择合适的版本：
 - `volcengine.STT` 补齐 `X-Api-Connect-Id` 握手头
 - `volcengine.STT` 切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
 - `volcengine.TTS` 同步切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
+- `volcengine.RealtimeModel` 同步切换到新版控制台鉴权，移除 `app_id` / `access_token`，改用单一 `api_key` 并发送 `X-Api-Key` 头
 
 ## 🤝 贡献
 

{livekit_plugins_volcenginee-1.3.1 → livekit_plugins_volcenginee-1.3.3}/livekit/plugins/volcengine/llm.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
 
 import httpx
 import openai
@@ -31,8 +31,8 @@ class _LLMOptions:
     temperature: NotGivenOr[float]
     parallel_tool_calls: NotGivenOr[bool]
     tool_choice: NotGivenOr[ToolChoice]
-    store: NotGivenOr[bool]
     metadata: NotGivenOr[dict[str, str]]
+    thinking: NotGivenOr[Literal["enabled", "disabled", "auto"] | dict[str, Any]]
 
 
 class LLM(llm.LLM):
@@ -47,8 +47,8 @@ class LLM(llm.LLM):
         temperature: NotGivenOr[float] = NOT_GIVEN,
         parallel_tool_calls: NotGivenOr[bool] = NOT_GIVEN,
         tool_choice: NotGivenOr[ToolChoice] = NOT_GIVEN,
-        store: NotGivenOr[bool] = NOT_GIVEN,
         metadata: NotGivenOr[dict[str, str]] = NOT_GIVEN,
+        thinking: NotGivenOr[Literal["enabled", "disabled", "auto"] | dict[str, Any]] = NOT_GIVEN,
         timeout: httpx.Timeout | None = None,
     ) -> None:
         """
@@ -58,6 +58,11 @@ class LLM(llm.LLM):
             model: The model to use for the LLM, end
             api_key: The API key to use for the LLM.
             base_url: The base URL to use for the LLM.
+            thinking: Controls deep thinking mode. Pass ``"disabled"`` to turn
+                it off, ``"enabled"`` to force it on, ``"auto"`` to let the
+                model decide, or a raw ``{"type": "..."}`` dict for extended
+                parameters. See the Volcengine Chat Completions API reference
+                for details. Omit to use the API default (``enabled``).
         """
         super().__init__()
         self._opts = _LLMOptions(
@@ -66,8 +71,8 @@ class LLM(llm.LLM):
             temperature=temperature,
             parallel_tool_calls=parallel_tool_calls,
             tool_choice=tool_choice,
-            store=store,
             metadata=metadata,
+            thinking=thinking,
         )
         api_key = api_key if is_given(api_key) else os.getenv("VOLCENGINE_LLM_API_KEY")
         if api_key is None:
@@ -110,6 +115,16 @@ class LLM(llm.LLM):
         if is_given(self._opts.user):
             extra["user"] = self._opts.user
 
+        if is_given(self._opts.temperature):
+            extra["temperature"] = self._opts.temperature
+
+        if is_given(self._opts.thinking):
+            extra["thinking"] = (
+                self._opts.thinking
+                if isinstance(self._opts.thinking, dict)
+                else {"type": self._opts.thinking}
+            )
+
         parallel_tool_calls = (
             parallel_tool_calls
             if is_given(parallel_tool_calls)

{livekit_plugins_volcenginee-1.3.1 → livekit_plugins_volcenginee-1.3.3}/livekit/plugins/volcengine/realtime.py

@@ -163,8 +163,7 @@ def parse_response(res):
 
 @dataclass
 class _RealtimeOptions:
-    app_id: str
-    access_token: str
+    api_key: str
     bot_name: str
     system_role: str
     max_session_duration: float | None
@@ -190,10 +189,8 @@ class _RealtimeOptions:
 
     def get_ws_headers(self) -> dict:
         headers = {
-            "X-Api-App-ID": self.app_id,
-            "X-Api-Access-Key": self.access_token,
+            "X-Api-Key": self.api_key,
             "X-Api-Resource-Id": "volc.speech.dialog",  # 固定值
-            "X-Api-App-Key": "PlgvMymc7f3tQnJ6",  # 固定值
             "X-Api-Connect-Id": str(uuid.uuid4()),
         }
         return headers
@@ -262,8 +259,7 @@ class RealtimeModel(llm.RealtimeModel):
         speaking_style: str = "你的说话风格简洁明了，语速适中，语调自然。",
         speaker: str = "zh_female_vv_jupiter_bigtts",
         opening: str | None = None,
-        app_id: str | None = None,
-        access_token: str | None = None,
+        api_key: str | None = None,
         system_role: str | None = None,
         character_manifest: str = None,
         model: Literal["O", "SC"] = "O",
@@ -299,17 +295,11 @@ class RealtimeModel(llm.RealtimeModel):
         logger.info(
             f"Volc Websearch No Result Message: {volc_websearch_no_result_message}"
         )
-        app_id = app_id or os.environ.get("VOLCENGINE_REALTIME_APP_ID")
-        if app_id is None:
-            raise ValueError("VOLCENGINE_REALTIME_APP_ID is required")
-        access_token = access_token or os.environ.get(
-            "VOLCENGINE_REALTIME_ACCESS_TOKEN"
-        )
-        if access_token is None:
-            raise ValueError("VOLCENGINE_REALTIME_ACCESS_TOKEN is required")
+        api_key = api_key or os.environ.get("VOLCENGINE_REALTIME_API_KEY")
+        if api_key is None:
+            raise ValueError("VOLCENGINE_REALTIME_API_KEY is required")
         self._opts = _RealtimeOptions(
-            app_id=app_id,
-            access_token=access_token,
+            api_key=api_key,
             bot_name=bot_name,
             system_role=system_role,
             speaker=speaker,

{livekit_plugins_volcenginee-1.3.1 → 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,6 +52,8 @@ 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)
@@ -53,6 +76,8 @@ class _TTSOptions(BaseModel):
                 "audio_params": {
                     "format": self.encoding,
                     "sample_rate": self.sample_rate,
+                    "loudness_rate": _volume_to_loudness_rate(self.volume),
+                    "speech_rate": _speed_to_speech_rate(self.speed),
                 },
                 "request_id": reqid,
             },
@@ -90,7 +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`.
-            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.
         """

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

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

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

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