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

livekit_plugins_volcenginee-1.3.4/.gitignore

@@ -0,0 +1,6 @@
+.vscode/
+.venv/
+.pytest_cache/
+__pycache__/
+.env
+.env.*

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: livekit-plugins-volcenginee
-Version: 1.3.2
+Version: 1.3.4
 Summary: LiveKit Agent Plugins for Volcengine
 Author-email: linsanzhu <2287225730@qq.com>
 Keywords: audio,livekit,realtime,video,webrtc
@@ -18,6 +18,11 @@ Requires-Dist: numpy
 Requires-Dist: openai>=1.80.0
 Requires-Dist: osc-data~=0.3.1
 Requires-Dist: pydantic
+Provides-Extra: test
+Requires-Dist: aiohttp>=3.9; extra == 'test'
+Requires-Dist: pyaudio>=0.2.14; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 # livekit-plugins-volcengine
@@ -394,18 +399,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.4}/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.4}/livekit/plugins/volcengine/llm.py

@@ -32,7 +32,18 @@ class _LLMOptions:
     parallel_tool_calls: NotGivenOr[bool]
     tool_choice: NotGivenOr[ToolChoice]
     metadata: NotGivenOr[dict[str, str]]
-    thinking: NotGivenOr[Literal["enabled", "disabled", "auto"] | dict[str, Any]]
+    reasoning_effort: NotGivenOr[Literal["minimal", "low", "medium", "high", "max"]]
+
+    def __post_init__(self) -> None:
+        if is_given(self.reasoning_effort):
+            if self.reasoning_effort not in (
+                "minimal", "low", "medium", "high", "max",
+            ):
+                raise ValueError(
+                    f"reasoning_effort must be one of "
+                    f"'minimal', 'low', 'medium', 'high', 'max'; "
+                    f"got {self.reasoning_effort!r}"
+                )
 
 
 class LLM(llm.LLM):
@@ -48,7 +59,9 @@ class LLM(llm.LLM):
         parallel_tool_calls: NotGivenOr[bool] = NOT_GIVEN,
         tool_choice: NotGivenOr[ToolChoice] = NOT_GIVEN,
         metadata: NotGivenOr[dict[str, str]] = NOT_GIVEN,
-        thinking: NotGivenOr[Literal["enabled", "disabled", "auto"] | dict[str, Any]] = NOT_GIVEN,
+        reasoning_effort: NotGivenOr[
+            Literal["minimal", "low", "medium", "high", "max"]
+        ] = NOT_GIVEN,
         timeout: httpx.Timeout | None = None,
     ) -> None:
         """
@@ -58,11 +71,14 @@ 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``).
+            reasoning_effort: Constrains the effort the model spends on
+                reasoning before producing a final answer. One of
+                ``"minimal"``, ``"low"``, ``"medium"``, ``"high"``, ``"max"``.
+                Mapped to Volcengine Ark's ``reasoning_effort`` field; also
+                accepted by the OpenAI Python SDK as a standard Chat
+                Completions kwarg (same name, same semantics) so it is
+                forwarded at the top level of the request body. Omit to use
+                the API default (``medium``).
         """
         super().__init__()
         self._opts = _LLMOptions(
@@ -72,7 +88,7 @@ class LLM(llm.LLM):
             parallel_tool_calls=parallel_tool_calls,
             tool_choice=tool_choice,
             metadata=metadata,
-            thinking=thinking,
+            reasoning_effort=reasoning_effort,
         )
         api_key = api_key if is_given(api_key) else os.getenv("VOLCENGINE_LLM_API_KEY")
         if api_key is None:
@@ -118,12 +134,13 @@ class LLM(llm.LLM):
         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}
-            )
+        if is_given(self._opts.reasoning_effort):
+            # ``reasoning_effort`` is part of the OpenAI Chat Completions
+            # signature (added for the o1 series; the OpenAI Python SDK
+            # accepts it at the top level). Volcengine Ark also accepts the
+            # same field name on its OpenAI-compatible endpoint, so we can
+            # forward it as a normal kwarg without ``extra_body``.
+            extra["reasoning_effort"] = self._opts.reasoning_effort
 
         parallel_tool_calls = (
             parallel_tool_calls

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

@@ -10,7 +10,7 @@ from collections.abc import ByteString
 from typing import Literal, Tuple
 
 import aiohttp
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 from osc_data.text_stream import TextStreamSentencizer
 
 from livekit.agents import (
@@ -24,18 +24,43 @@ 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):
+    # Reject unknown fields so the legacy ``speech_rate`` / ``loudness_rate``
+    # kwargs that were removed from the public API surface immediately.
+    model_config = ConfigDict(extra="forbid")
+
     api_key: str
     resource_id: str | None = None
     voice: str = "zh_female_xiaohe_uranus_bigtts"
     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 +80,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 +110,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 +119,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 +139,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.4/livekit/plugins/volcengine/version.py

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

{livekit_plugins_volcenginee-1.3.2 → livekit_plugins_volcenginee-1.3.4}/pyproject.toml

@@ -27,6 +27,13 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
 ]
 
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "aiohttp>=3.9",
+    "pyaudio>=0.2.14",
+]
 
 
 [build-system]
@@ -41,3 +48,16 @@ packages = ["livekit"]
 
 [tool.hatch.build.targets.sdist]
 include = ["/livekit"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+log_cli = true
+log_cli_level = "INFO"
+log_cli_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+log_cli_date_format = "%H:%M:%S"
+markers = [
+    "integration: marks tests that require real Volcengine API credentials (skipped automatically when keys are not set in the environment)",
+    "llm: marks LLM integration tests (require VOLCENGINE_LLM_API_KEY)",
+    "tts: marks TTS integration tests (require VOLCENGINE_TTS_API_KEY)",
+]

livekit_plugins_volcenginee-1.3.2/.gitignore

@@ -1,183 +0,0 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
-.pdm.toml
-.pdm-python
-.pdm-build/
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
-# tests
-test.py
-
-.python-version
-
-*.ipynb
-config.yaml
-uv.lock

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

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