Skip to content

README-EN.md

Latest commit

 

History

History
334 lines (243 loc) · 9.84 KB

README-EN.md

File metadata and controls

334 lines (243 loc) · 9.84 KB
Raw

vot-cli

Tool for translating videos or downloading subtitles using vot.js

GitHub Actions en ru

promo gif

This script lets you:

  • Download a video translation or get a link to it
  • Download video subtitles in SRT, VTT or JSON format or get a link to them
  • Get a link to the finished file without downloading (preview mode)
  • Use lively voices for translation (en -> ru)
  • Output results in JSON or as plain links (without progress)
  • Process multiple links in one run

Warning

This script is created solely for research purposes and is not intended for commercial use. All rights to the original software belong to their respective owners.

Parameters

Click to expand
  • -h, --help: show help
  • -v, --version: show script version
  • -o, --out, --outdir=(path): set output directory
  • --outfile=(name): set output filename
  • --lang=(lang): set source video language (see wiki for supported languages). Default: en
  • --reslang=(lang): set audio track or subtitle language (see wiki for supported languages). Default: ru
  • --proxy=(url): set HTTP or HTTPS proxy in format [<PROTOCOL>://]<USERNAME>:<PASSWORD>@<HOST>[:<port>]
  • --worker-host=(url): set your own vot-worker in format [<PROTOCOL>://]<HOST>[:<port>][/<PREFIX>]
  • --cookies=(path): set the cookies file for yt-dlp (Netscape format)
  • --cookies-from-browser=(browser): load cookies for yt-dlp from the browser (e.g. firefox or chrome:Profile 1). Required for age-restricted videos
  • --subs: get subtitles instead of audio, if available
  • --subs-format=(format): set subtitle format (json, srt, vtt. Does not work with --preview)
  • --preview: get a download link without downloading
  • --lively-voice: use lively voices for available videos (only en -> ru)
  • --api-token: set Yandex OAuth API token for using lively voices. You can get a token via the debug link
  • --no-visual: output result to stdout/stderr without progress info (1 line = 1 link)
  • --json: output result to stdout/stderr as JSON without progress info
  • --no-title: use video ID as filename, without attempting to get the video title

Usage examples

Click to expand
  • vot-cli [options] <link> [link2] [link3] ... - general example
  • vot-cli <link> - get audio translation from a link
  • vot-cli --help - show help
  • vot-cli --version - show version
  • vot-cli --json [options] <link> - get result as JSON
  • vot-cli --outdir=<path> <link> - get audio translation and save it to the specified path
  • vot-cli --outdir=<path> --reslang=en <link> - get audio translation in English and save it to the specified path
  • vot-cli --subs --outdir=<path> --reslang=en <link> - get English subtitles and save them to the specified path
  • vot-cli --outdir="." "https://www.youtube.com/watch?v=X98VPQCE_WI" "https://www.youtube.com/watch?v=djr8j-4fS3A&t=900s" - real data example

JSON output examples

All examples in this README have been formatted separately for readability. In real output, JSON will be a single line, and some lists may be longer. Failed results include an error message. Argument and setup failures use {"ok":false,"error":"..."}. Successful or mixed batch results go to stdout; all-failed batches and top-level errors go to stderr. Any failure exits with code 1. --no-visual keeps its URL/FAILED lines; help and version output are unchanged.

Successful execution 
vot-cli --json ...
{
  "ok": true,
  "summary": {
    "total": 1,
    "success": 1,
    "failed": 0
  },
  "results": [
    {
      "input": "https://www.youtube.com/watch?v=X98VPQCE_WI",
      "status": "success",
      "type": "audio",
      "videoId": "X98VPQCE_WI",
      "url": "https://example.com/audio.mp3",
      "outputPath": "C:\\downloads\\X98VPQCE_WI.mp3"
    }
  ]
}
Processing error 
vot-cli --json ...
{
  "ok": false,
  "summary": {
    "total": 1,
    "success": 0,
    "failed": 1
  },
  "results": [
    {
      "input": "not-a-url",
      "status": "failed",
      "type": "audio",
      "videoId": null,
      "url": null,
      "error": "Invalid URL"
    }
  ]
}
Version 
vot-cli --version --json
{
  "version": "2.0.0",
  "runtime": "Bun/1.3.14"
}
Help 
vot-cli --help --json
{
  "usage": "vot-cli [options] <link> [link2] [link3] ...",
  "options": [
    { "flags": ["-h", "--help"], "description": "Show help (You're here)" },
    {
      "flags": ["--json"],
      "description": "Write result to stdout/stderr as JSON without progress info"
    }
  ],
  "requestLangs": ["auto", "ru", "en"],
  "responseLangs": ["ru", "en", "kk"],
  "subtitlesTypes": ["srt", "vtt", "json"]
}

Installation

Note

Also, please install yt-dlp to translate new YouTube videos and also get video titles for output filenames. If yt-dlp is not found, the script can return errors and video IDs will be used as filenames.

Choose the most convenient way to install vot-cli.

Pre-built binaries

If you don't want to install Node.js or Bun, you can simply download a pre-built binary from GitHub Releases.

Choose the archive for your operating system and architecture:

Linux

Extract the archive, make the file executable, and move it to a directory in your PATH:

tar -xzf vot-linux-x64.tar.gz
chmod +x vot-linux-x64
sudo mv vot-linux-x64 /usr/local/bin/vot-cli
vot-cli --version

macOS

Download vot-darwin-x64.tar.gz or vot-darwin-arm64.tar.gz (depending on your Mac) and run the same commands, replacing the filename.

Windows

Download vot-windows-x64.exe.zip, extract vot-windows-x64.exe, optionally rename it to vot-cli.exe.

To make it accessible from anywhere, add its folder to the PATH environment variable.

Via NPM/Bun (Cross-platform)

Warning

When running with Deno, grant all permissions at startup; otherwise, the script will not be able to work with files and the network or run yt-dlp, which will cause errors. e.g.: deno -A src/index.ts <args>

This option is suitable if you already have Bun.sh or Node.js 22.19+ installed.

  1. Install Bun.sh or Node.js.
  2. Install vot-cli globally:

Installation for Bun:

bun install -g vot-cli

Installation for Node:

npm install -g vot-cli

Building for NPM

  1. Install Bun.sh
  2. Install dependencies:
bun install
  1. Build vot-cli:
bun run build:bun

Building binaries

  1. Install Bun.sh
  2. Install dependencies:
bun install
  1. Run the build:
bun run compile

If you get Failed to move cross-compiled bun binary into cache directory on Windows, use WSL or move the source folder to the C: drive.

Local testing with the vot-cli command:

  1. Link the directory:
bun link
  1. Done, now you can use vot-cli in your terminal

📁 Useful links

  1. Browser extension: Link

  2. Scripts for downloading videos with built-in translation (add-ons for vot-cli):

    OS Shell Author Link
    Windows PowerShell Dragoy Link
    Unix Fish Musickiller Link
    Linux Bash s-n-alexeyev Link
    Cloud Google Colab alex2844 Link

✨ Optional features

Using yt-dlp for video titles

vot-cli can use yt-dlp to get human-readable video titles for output filenames.

If yt-dlp is not found on the system, video IDs will be used as filenames (X98VPQCE_WI.mp3 instead of the title).

You can disable this behavior with the --no-title flag.

❗ Notes

  1. Wrap links in quotes to avoid errors
  2. Writing to a system partition (e.g., "C: drive" on Windows) requires administrator privileges
  3. yt-dlp is optionally used for fetching video titles (see the "Optional features" section)