ByteDance plugin for LiveKit Agents
Community-maintained LiveKit Agents plugin for ByteDance and Volcengine AI services.
This package is unofficial and is not currently maintained by ByteDance, Volcengine, or LiveKit.
Current Scope
livekit-plugins-bytedance is intentionally narrow today. The package name is
reserved for the broader ByteDance/Volcengine ecosystem, but version 0.1.x
only implements:
| Service | API | LiveKit class | Status |
|---|---|---|---|
| Volcengine TTS V3 bidirectional streaming | wss://openspeech.bytedance.com/api/v3/tts/bidirection |
livekit.plugins.bytedance.TTS |
Supported |
| Volcengine BigModel streaming ASR, optimized bidirectional mode | wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async |
livekit.plugins.bytedance.STT |
Supported |
The implemented clients follow these Volcengine WebSocket APIs:
- Volcengine TTS V3 bidirectional API: https://www.volcengine.com/docs/6561/1329505
- Volcengine BigModel ASR WebSocket API, optimized bidirectional streaming endpoint: https://www.volcengine.com/docs/6561/1354869
The supported WebSocket request paths are:
wss://openspeech.bytedance.com/api/v3/tts/bidirection
wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
The TTS binary protocol constants are also checked against ByteDance's
reference helper package named TTS Websocket Bidirection protocols, including
the downstream event codes for UsageResponse (154), AudioMuted (250),
TTSResponse (352), TTSEnded (359), and TTSSubtitle (364).
Explicitly Not Supported Yet
This package does not currently implement:
- Volcengine legacy TTS v1 (
/api/v1/tts/ws_binary) - Volcengine ASR batch/offline APIs
- Volcengine ASR
bigmodel_nostreamstreaming-input mode - Volcengine ASR legacy non-optimized bidirectional path
(
/api/v3/sauc/bigmodel) - Doubao/Ark LLM APIs
- Volcengine realtime dialogue APIs
- ByteDance video, image, embedding, or moderation APIs
- Non-streaming LiveKit
TTS.synthesize()
For those services, use a provider-specific package if one exists. The existing
third-party livekit-plugins-volcengine package is separate from this package
and uses the livekit.plugins.volcengine import namespace.
Supported TTS Features
- Streaming synthesis through
TTS.stream() - Volcengine TTS V3 connection/session/task binary protocol
X-Api-Keyauthentication for the current Volcengine console- Legacy console authentication through
X-Api-App-KeyandX-Api-Access-Key resource_idvalues documented for this API:seed-tts-2.0seed-icl-2.0
- Optional cloned-voice model selection:
seed-tts-2.0-standardseed-tts-2.0-expressive
speakerssmlaudio_format:pcm,mp3,ogg_opus, orwavsample_ratebit_ratespeech_rateloudness_rateenable_subtitlerequest flagdisable_markdown_filterdisable_emoji_filterenable_latex_tnlatex_parserexplicit_languageexplicit_dialectaigc_watermarkaigc_metadatacache_configpost_process- TTS 2.0
context_texts use_tag_parserX-Control-Require-Usage-Tokens-Return- Server-side sentence splitting
- LiveKit retry behavior for transient websocket failures before audio is emitted
Subtitle and usage payloads can be requested from Volcengine, but this LiveKit TTS plugin currently exposes only synthesized audio frames through the LiveKit TTS stream. Non-audio protocol events such as usage responses, muted-audio signals, sentence boundaries, subtitles, and TTS-ended markers are parsed and ignored for now rather than surfaced as LiveKit TTS events.
Supported STT Features
- Streaming recognition through
STT.stream() - Volcengine BigModel ASR WebSocket binary protocol v3
- Optimized bidirectional streaming endpoint:
wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async X-Api-Keyauthentication for the current Volcengine console- Legacy console authentication through
X-Api-App-KeyandX-Api-Access-Key X-Api-Resource-Id,X-Api-Request-Id,X-Api-Sequence, andX-Api-Connect-Idheaders- Default ASR 2.0 resource ID:
volc.seedasr.sauc.duration - PCM input at 16 kHz, 16-bit, mono
- Server-side VAD/final segmentation through
enable_nonstream=True - Interim and final LiveKit transcript events
- Word timestamps when Volcengine returns
utterances[*].words - Selected BigModel request options, including
enable_itn,enable_punc,enable_ddc,show_utterances,enable_speaker_info,ssd_version,result_type, VAD timing options, sensitive-word filtering, andcorpus - Escape hatches through
audio_optionsandrequest_optionsfor provider fields that are not first-class constructor arguments yet
The plugin does not send the ASR audio.language field by default because the
provider document scopes that field to the bigmodel_nostream endpoint, which
this package does not currently support.
The plugin sends credentials with Volcengine's V3 websocket headers:
X-Api-KeyX-Api-Resource-IdX-Api-Connect-Id
For legacy console credentials, it sends:
X-Api-App-KeyX-Api-Access-KeyX-Api-Resource-IdX-Api-Connect-Id
Installation
pip install livekit-plugins-bytedance
Credentials
Create or locate your Volcengine TTS V3 credentials in the Volcengine console, then pass them to the plugin explicitly:
from livekit.plugins import bytedance
tts = bytedance.TTS(
api_key="your-api-key",
resource_id="seed-tts-2.0",
)
If your application prefers environment variables, load them in your own config
layer and pass them to TTS. The plugin does not read environment variables by
itself.
Suggested variable names:
export VOLCENGINE_TTS_V3_API_KEY=...
export VOLCENGINE_TTS_V3_RESOURCE_ID=seed-tts-2.0
export VOLCENGINE_ASR_API_KEY=...
export VOLCENGINE_ASR_RESOURCE_ID=volc.seedasr.sauc.duration
The API also supports old-console authentication. If you still use those
credentials, pass both app_key and access_key instead of api_key.
Usage
Use the default TTS V3 model and speaker:
from livekit.plugins import bytedance
tts = bytedance.TTS(
api_key="your-api-key",
)
Use a specific Seed TTS resource and speaker:
tts = bytedance.TTS(
api_key="your-api-key",
resource_id="seed-tts-2.0",
speaker="zh_female_vv_uranus_bigtts",
)
Use TTS 2.0 style controls:
tts = bytedance.TTS(
api_key="your-api-key",
resource_id="seed-tts-2.0",
speaker="zh_female_vv_uranus_bigtts",
context_texts=["自然、专业、和善,像面试官一样说话"],
speech_rate=0,
loudness_rate=0,
)
Use the descriptive class name if you prefer:
from livekit.plugins.bytedance import VolcengineV3TTS
tts = VolcengineV3TTS(
api_key="your-api-key",
)
Use streaming ASR:
from livekit.plugins import bytedance
stt = bytedance.STT(
api_key="your-api-key",
resource_id="volc.seedasr.sauc.duration",
)
stream = stt.stream()
stream.push_frame(audio_frame)
stream.end_input()
async for event in stream:
if event.type == "final_transcript":
print(event.alternatives[0].text)
Testing
Run the default suite:
uv run pytest livekit-plugins/livekit-plugins-bytedance
The default tests are hermetic and do not require Volcengine credentials. They cover the TTS V3 binary protocol, ASR WebSocket v3 binary protocol, websocket handshake headers, retry behavior, zombie websocket handling, server error classification, partial audio drain behavior, and ASR transcript event mapping.
Real end-to-end tests should use a separate marker and require:
export VOLCENGINE_TTS_V3_API_KEY=...
export VOLCENGINE_TTS_V3_RESOURCE_ID=seed-tts-2.0
export VOLCENGINE_ASR_API_KEY=...
export VOLCENGINE_ASR_RESOURCE_ID=volc.seedasr.sauc.duration
License
Apache-2.0.
Metadata
Release files for livekit-plugins-bytedance 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| livekit_plugins_bytedance-0.1.0.tar.gz | 19.5 kB | With provenance | Details for livekit_plugins_bytedance-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| livekit_plugins_bytedance-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for livekit_plugins_bytedance-0.1.0-py3-none-any.whl |
Total release size: 42.0 kB
Release files / livekit_plugins_bytedance-0.1.0.tar.gz
| Download URL | livekit_plugins_bytedance-0.1.0.tar.gz |
|---|---|
| Size | 19.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e206250ffc858af0deac75a2f9ee3a529ff03fa73465d75c2e268dd87fdae626
|
|
BLAKE2b-256 checksum How to use checksums |
785118316d5dc4f543eba0ca4aa002ae58cc8848efcc573b32912326c632be09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logRelease files / livekit_plugins_bytedance-0.1.0-py3-none-any.whl
| Download URL | livekit_plugins_bytedance-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1057d0861a48801e091d1727363d38bee3a1dd68fed78ab145d0c7271edc1687
|
|
BLAKE2b-256 checksum How to use checksums |
74a06753b7171c3c9de9b145dc269d3786086b4ffe10d58d3cf70aeb2bc4ac09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logSecurity for livekit-plugins-bytedance 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for livekit_plugins_bytedance-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.