Metadata-Version: 2.4
Name: yavot-py
Version: 0.1.0
Summary: A Python port of the vot.js library for interacting with Yandex Video Translation API
Project-URL: Homepage, https://github.com/yamixst/yavot-py
Project-URL: Repository, https://github.com/yamixst/yavot-py
Project-URL: Issues, https://github.com/yamixst/yavot-py/issues
Project-URL: Documentation, https://github.com/yamixst/yavot-py/tree/main/docs
Author: yamixst
License: MIT License
        
        Copyright (c) 2024 FOSWLY
        Copyright (c) 2026 yamixst
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: subtitles,translation,video,voiceover,vot,yandex,yavot-py
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: protobuf>=4.21.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-protobuf>=4.21.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](#installation)
2. [Quick Start](#quick-start)
   - [Async Client (Recommended)](#async-client-recommended)
   - [Sync Client](#sync-client)
3. [Key Features & Modules](#key-features--modules)
   - [Service Routing & ID Extraction](#service-routing--id-extraction)
   - [Video Translation](#video-translation)
   - [Fetching Subtitles](#fetching-subtitles)
   - [Live Streams](#live-streams)
   - [Subtitles Conversion](#subtitles-conversion)
4. [CLI Usage](#cli-usage)
5. [Development & Testing](#development--testing)

---

## Installation

To install the library in editable/local mode:

```bash
# 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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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:

```python
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:**
  ```bash
  vot <args>
  ```
- **Locally (during development, using the helper script):**
  ```bash
  ./vot-cli <args>
  ```
- **Directly via Python:**
  ```bash
  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):**
   ```bash
   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ
   ```

2. **Translate from German to Russian and download the audio locally:**
   ```bash
   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ -f de -t ru -o output.mp3
   ```

3. **Request translation and print subtitle links:**
   ```bash
   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ -s
   ```

4. **Download and convert subtitles to SRT:**
   ```bash
   vot https://www.youtube.com/watch?v=dQw4w9WgXcQ --output-subs subs.srt
   ```

---

## Development & Testing

To run tests, typecheck, or format the codebase:

```bash
# 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
```
