yavot-py 0.1.0__tar.gz

yavot_py-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python virtual environment
+.venv/
+venv/
+ENV/
+
+# Python cache and compiled files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Distribution / Build packages
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# OS files
+.DS_Store
+Thumbs.db

yavot_py-0.1.0/AGENTS.md

@@ -0,0 +1,73 @@
+# Agent Instructions for `yavot-py` Maintenance & Development
+
+You are an AI Agent tasked with maintaining, extending, or debugging `yavot-py`, a modern, high-quality Python library for interacting with the Yandex Video Translation API.
+
+The initial port from the TypeScript `vot.js` library has been completed. These instructions outline the established architecture, technology stack, and best practices. **Always refer to these guidelines when making modifications.**
+
+---
+
+## 1. Project Overview & Tech Stack
+
+`yavot-py` is a fully typed, asynchronous Python package targeting desktop and server environments.
+
+### Established Tech Stack
+- **Python Version**: 3.10+ (Modern typing and language features).
+- **Dependency Management**: `uv` (Use `uv run`, `uv add`, etc.).
+- **HTTP Client**: `httpx` (Asynchronous and synchronous clients).
+- **Protobuf**: `protobuf` (Google's official Python implementation).
+- **Data Validation/Models**: `pydantic` (v2).
+- **Testing**: `pytest` + `pytest-asyncio`.
+- **Linting & Formatting**: `ruff`.
+- **Type Checking**: `mypy`.
+
+---
+
+## 2. Python Library Best Practices
+
+All agents contributing to `yavot-py` MUST adhere to the following Python library best practices:
+
+1. **Strict Type Hinting**: Every function signature and class must have proper type hints. Use `typing` features extensively (e.g., `Optional`, `Union`, `Literal`, or new syntax `X | Y`).
+2. **Docstrings**: Use Google-style or NumPy-style docstrings for all public modules, classes, and functions.
+3. **Async First, Sync Optional**: The core client uses `httpx.AsyncClient`. A synchronous wrapper (`VOTClientSync`) is provided.
+4. **Exception Handling**: Do not use bare `except:` clauses. Define custom exceptions (e.g., `VOTError`, `VOTAPIError`, `VideoDataError`) inheriting from Python's standard `Exception`.
+5. **Clean Imports**: Use absolute imports (`from vot.client import VOTClient`) or explicit relative imports (`from . import utils`).
+6. **No Global State**: Ensure that instances of the client do not leak state globally. Sessions and configurations should be bound to the client instance.
+
+---
+
+## 3. Project Architecture
+
+The repository is structured as a standard Python package:
+
+```text
+yavot-py/
+├── pyproject.toml         # Project metadata, dependencies, and tool configs
+├── README.md              # English documentation
+├── README.ru.md           # Russian documentation
+├── docs/                  # API documentation (English & Russian)
+├── scripts/
+│   └── generate_proto.sh  # Script to recompile protobuf bindings
+├── src/
+│   └── vot/
+│       ├── __init__.py    # Exposes main clients and models
+│       ├── cli.py         # CLI implementation & argument parsing
+│       ├── client.py      # Core clients (MinimalClient, VOTClient, VOTClientSync, VOTWorkerClient)
+│       ├── config.py      # Global configurations and constants
+│       ├── exceptions.py  # Custom exception hierarchy
+│       ├── models.py      # Pydantic data models
+│       ├── helpers/       # Domain-specific extractors (e.g., youtube.py)
+│       ├── protobuf/      # Yandex Protobuf schemas and compiled python files
+│       └── utils/         # Crypto, URL parsing, subtitles conversion, and language normalization
+├── tests/                 # Comprehensive pytest suite
+└── vot-cli                # Bash wrapper for local CLI testing
+```
+
+---
+
+## 4. Agent Workflow Rules
+
+1. **Test Before Commit**: You must successfully run `uv run pytest`, `uv run mypy src tests`, and `uv run ruff check src tests` before claiming a task is complete or committing changes.
+2. **Modifying Protobufs**: If you update `src/vot/protobuf/yandex.proto`, you MUST execute `./scripts/generate_proto.sh` to regenerate `yandex_pb2.py`.
+3. **CLI Updates**: If you add new functionality to the CLI (`src/vot/cli.py`), make sure to write corresponding tests in `tests/test_cli.py` and update the READMEs.
+4. **Small, Descriptive Commits**: Keep changes atomic and commit messages clear (e.g., `feat: add support for new video host`, `fix: resolve mypy typing error in client`).
+5. **Bilingual Documentation**: User-facing documentation (`README.md`, `docs/api.md`) must be maintained in both English and Russian (`README.ru.md`, `docs/api.ru.md`).

yavot_py-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.

yavot_py-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+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
+```

yavot_py-0.1.0/README.md

@@ -0,0 +1,240 @@
+# 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
+```