yavot-py 0.1.0

A Python port of the vot.js library for interacting with Yandex Video Translation API

yavot-py

yavot-py is a modern, fast, and fully type-safe Python library for interacting with the Yandex Video Translation API. This library is a Python port of the popular TypeScript library vot.js.

It allows you to request video translations, poll processing status, obtain translated voice-over audio URLs, fetch original and translated subtitles, download and convert subtitle formats, and translate live streams in real time.

---

Table of Contents

1. Installation
2. Quick Start
   • Async Client (Recommended)
   • Sync Client
3. Key Features & Modules
   • Service Routing & ID Extraction
   • Video Translation
   • Fetching Subtitles
   • Live Streams
   • Subtitles Conversion
4. CLI Usage
5. Development & Testing

---

Installation

To install the library in editable/local mode:

# Using pip
pip install -e .

# Or using uv (recommended)
uv pip install -e .

The package automatically registers the vot executable command in your path.

---

Quick Start

Async Client (Recommended)

The core client uses httpx.AsyncClient underneath.

import asyncio
import httpx
from vot import VOTClient, get_video_data

async def main():
    # Initialize HTTP client
    async with httpx.AsyncClient() as http_client:
        # Initialize VOTClient
        client = VOTClient(client=http_client)
        
        # Resolve video URL (automatically detects service, extracts video ID & metadata)
        url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        video_data = await get_video_data(url, client=http_client)
        
        print(f"Service: {video_data.host}, Video ID: {video_data.video_id}")
        
        # Request video translation
        response = await client.translate_video(video_data)
        
        if response.translated:
            print(f"Translation finished! Audio URL: {response.url}")
        else:
            print(f"Translation in progress. Retry in {response.remaining_time}s. (Status: {response.status})")

if __name__ == "__main__":
    asyncio.run(main())

Sync Client

If your application uses synchronous code, you can use VOTClientSync, which handles the event loop automatically.

from vot import VOTClientSync, get_video_data
import httpx

# VOTClientSync supports the context manager protocol
with VOTClientSync() as client:
    # Resolving video data still requires an HTTP client
    with httpx.Client() as http_client:
        # Since get_video_data is async, we run it using the client's loop runner helper
        video_data = client._run(get_video_data("https://www.youtube.com/watch?v=dQw4w9WgXcQ"))
        
    # Request translation synchronously
    response = client.translate_video(video_data)
    if response.translated:
        print(f"Voiceover Audio URL: {response.url}")

---

Key Features & Modules

Service Routing & ID Extraction

get_video_data parses a video page URL, matches it against a registry of supported hosting sites (YouTube, Vimeo, Twitch, VK, TikTok, custom direct links, etc.), extracts the identifier, and returns a structured VideoData object.

from vot import get_video_data

# YouTube support includes watch links, shorts, live streams, embed links, and share URLs
video_data = await get_video_data("https://youtu.be/dQw4w9WgXcQ")
print(video_data.video_id)  # "dQw4w9WgXcQ"
print(video_data.host)      # "youtube"

Video Translation

translate_video serializes a Protobuf payload and sends a signed request to Yandex API.

• Translation Settings:
  • request_lang: Source video language (e.g. "en", "de", "zh", or "auto").
  • response_lang: Target translation language (e.g. "ru", "en", "kk").
• Initial YouTube Videos Upload: For brand new YouTube videos that have never been translated by Yandex before, Yandex requires uploading a mock audio player error report (fail-audio-js). This library performs that upload automatically if should_send_failed_audio=True (default).

Fetching Subtitles

get_subtitles retrieves a list of available subtitles, containing links to the original subtitles as well as machine-translated subtitles generated by Yandex.

subs_response = await client.get_subtitles(video_data)
for sub in subs_response.subtitles:
    print(f"Original Language: {sub.language} -> URL: {sub.url}")
    if sub.translated_url:
        print(f"Translated to: {sub.translated_language} -> URL: {sub.translated_url}")

Live Streams

The library supports translating ongoing live broadcasts.

1. translate_stream — Initiates stream translation and returns an M3U8 translated playlist URL.
2. ping_stream — Sends periodic keep-alive requests to keep the translation session alive.

stream_res = await client.translate_stream(video_data)
if stream_res.translated:
    print(f"Translated stream M3U8: {stream_res.result.url}")
    # Run ping loop in the background to maintain session
    await client.ping_stream(stream_res.ping_id)

Subtitles Conversion

convert_subs allows converting between JSON (Yandex's internal format), SRT, and VTT formats:

from vot import convert_subs

# Convert VTT format to SRT
vtt_data = "WEBVTT\n\n00:00:01.000 --> 00:00:03.000\nHello, world!"
srt_data = convert_subs(vtt_data, output="srt")
print(srt_data)
# Output:
# 1
# 00:00:01,000 --> 00:00:03,000
# Hello, world!

# Convert VTT to Yandex JSON format
json_data = convert_subs(vtt_data, output="json")

---

CLI Usage

The library includes a CLI tool that prints response URLs, polls translation status, and downloads audio or subtitles.

Running the CLI

Depending on your installation, you can run the CLI in one of the following ways:

• If installed:

  vot <args>
  

• Locally (during development, using the helper script):

  ./vot-cli <args>
  

• Directly via Python:

  python -m vot.cli <args>
  # Or via uv:
  uv run python -m vot.cli <args>
  

CLI Arguments

Option	Shorthand	Description	Default
url	Positioned	URL of the video to translate (e.g. YouTube, Vimeo, Twitch, VK, TikTok)	Required
--lang-from	-f	Source language of the video (e.g., en, de, zh, or auto)	en
--lang-to	-t	Target language of the translation (e.g., ru, en, kk)	ru
--output	-o	Save the translated audio file to this local path	None
--subtitles	-s	Fetch and print available subtitle links	False
--output-subs		Save the translated subtitles file to this local path (supports .srt, .vtt, .json)	None

Examples

1. Get translation audio link (with status polling):

   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ
   

2. Translate from German to Russian and download the audio locally:

   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ -f de -t ru -o output.mp3
   

3. Request translation and print subtitle links:

   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ -s
   

4. Download and convert subtitles to SRT:

   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ --output-subs subs.srt
   

---

Development & Testing

To run tests, typecheck, or format the codebase:

# Run test suite (mocked)
uv run pytest

# Check static types
uv run mypy src tests

# Run linter and formatting checks
uv run ruff check src tests
uv run ruff format --check src tests