voice-over-translation/README-EN.md

Voice Over Translation

Caution

Before creating Issues, we strongly recommend that you read the FAQ section and with existing Issues.

All rights to the original software belong to their respective owners. This extension is not affiliated with the original rights holders.

Voice-over translation is now available beyond Yandex Browser. Thanks to the Yandex.Translate team and all contributors helping improve this project.

Installing the extension:

Warning

Important for Tampermonkey 5.2+ (MV3) users: In Chromium-based browsers (Chrome, Edge, Brave, Vivaldi, etc.) you must:

1. Open the extensions page (chrome://extensions) and enable "Developer mode" (details in Tampermonkey documentation).
2. If you use Chromium 138+, open extension details and enable "Allow User Scripts".

For Opera users:

1. Use Violentmonkey instead of Tampermonkey.
2. In the extension settings, enable "Allow access to search page results" (Opera guide: where to find this setting), otherwise the script will not work.

1. Install a userscript manager: Tampermonkey (or Violentmonkey for Opera)
2. Install the script

Install Native Extension for Chrome / Chromium

1. Open Releases and download vot-extension-chrome-<version>.zip
2. Open your extensions page:
   • Chrome: chrome://extensions
   • Edge: edge://extensions
   • Brave: brave://extensions
   • Opera: opera://extensions
3. Enable Developer mode
4. Drag and drop the downloaded .zip file onto the extensions page

Install Native Extension for Firefox

1. Open Releases, click vot-extension-firefox-<version>.xpi, and confirm installation in Firefox

List of features:

• Translate videos into Russian, English, or Kazakh from supported source languages
• Auto-translate videos on open
• Auto-enable subtitles on open
• Smart subtitle layout that adapts line width and text size to player dimensions
• Display AI-generated subtitles
• Display site-provided subtitles (for example, auto-translated YouTube subtitles)
• Save subtitles in .srt, .vtt, and .json formats
• Save translated audio as .mp3
• Separate volume sliders for original and translated audio
• Adaptive volume: duck original audio while translated speech is playing
• Limit translation for videos in your native language (language can be selected in the menu)
• Link translation volume with video volume
• Limit translation from selected languages
• Hotkeys for translation and subtitles (including key combinations)
• Easy subtitle appearance customization
• Word-by-word translation directly in subtitles

Useful links:

1. JavaScript library (vot.js): Link
2. Terminal version (vot-cli): Link
3. Wiki: Link

Note:

1. It is recommended to allow autoplay for audio/video to avoid runtime playback errors
2. The extension cannot translate videos longer than 4 hours (translator API limitation)
3. For stable audio-download flow, use up-to-date and supported userscript managers (for example, Tampermonkey or Violentmonkey)

List of supported sites:

You can find the full list of supported websites and their specific limitations in the wiki.

Our domains:

These domains can be set in the extension settings (only those domains that can be changed without rebuilding are listed here):

Proxy-server

Required for proxying requests when direct access to Yandex servers is unavailable.

• vot-worker.toil.cc (Load balancer between proxy servers)
• vot-worker-s1.toil.cc
• vot-worker-s2.toil.cc
• vot.deno.dev
• vot-new.toil-dump.workers.dev (⚠️ doesn't work in Russia)

Media Proxy-server

It's necessary for proxying .m3u8 files and correcting the translation for indirect links to .mp4 or .webm(for more information in the repository)

• media-proxy.toil.cc

VOT-Backend

It's necessary to translate additional sites that use the .m3u8 or .mpd video format.

• vot.toil.cc

VOT Status and Stats

Check current status and uptime of all servers here:

• votstatus.toil.cc

Check proxy server usage statistics (updated every 5 minutes):

• votstats.toil.cc

How to build an extension?

1. Install Node.js 22+ / Bun.sh
2. Install dependencies:

NPM:

npm install

Bun:

bun install

3. Build targets:

   3.0. Userscript (regular build):

   npm run build
   

   3.1. Userscript (minified build):

   npm run build:min
   

   3.2. Userscript (both variants):

   npm run build:all
   

   3.3. Native Chrome/Firefox extension packages:

   npm run build:ext
   

   3.4. Development userscript build with sourcemaps:

   npm run build:dev
   

Userscript artifacts are generated in dist/, native extension artifacts in dist-ext/.

Customization of appearance:

The extension supports appearance customization via Stylus, Stylish, and similar tools.

Example style override:

/* ==UserStyle==
@name         VOT-styles
@version      16.09.2023
@namespace    vot-styles
@description  LLL
@author       Toil
@license      No License
==/UserStyle== */

:root {
  --vot-font-family: "Roboto", "Segoe UI", BlinkMacSystemFont, system-ui,
    -apple-system;

  --vot-primary-rgb: 139, 180, 245;
  --vot-onprimary-rgb: 32, 33, 36;
  --vot-surface-rgb: 32, 33, 36;
  --vot-onsurface-rgb: 227, 227, 227;

  --vot-subtitles-color: rgb(var(--vot-onsurface-rgb, 227, 227, 227));
  --vot-subtitles-passed-color: rgb(var(--vot-primary-rgb, 33, 150, 243));
}

Tested browsers and loaders

This list is updated infrequently but is usually still relevant.

The extension has been tested in the following browsers:

Status	Browser	Min. Browser Version	Platform	Extension
✅	Firefox Developer Edition	v106	Windows	Tampermonkey (MV2), FireMonkey, Violentmonkey, Greasemonkey
✅	Firefox	v116.0.2	Windows, Linux, Android	Tampermonkey (MV2), Violentmonkey
✅	Firefox Nightly	v118.0a1	Windows, Android	Tampermonkey (MV2)
✅	LibreWolf	v100.0.2-1	Windows	Tampermonkey (MV2)
✅	Brave	v1.46	Windows	Tampermonkey (MV2)
✅	MS Edge	v106.0.1370.34	Windows, Linux	Tampermonkey (MV2)
✅	Cent Browser	v4.3.9.248	Windows	Tampermonkey (MV2)
✅	Cent Browser Beta	v5.0.1002.182	Windows	Tampermonkey (MV2)
✅	Google Chrome	v106	Windows, MacOS, Linux	Tampermonkey (MV2), Tampermonkey (MV3), Violentmonkey, User Javascript and CSS
✅	Opera GX (LVL4)	core91	Windows	Violentmonkey
✅	Opera GX (LVL5)	core109	Windows	Violentmonkey
✅	Opera	v92.0.4561.43	Windows	Violentmonkey
✅	Vivaldi	5.7.2921.63	Windows, Linux	Tampermonkey (MV2)
✅	Safari	v15.6.1	MacOS, iOS	Userscripts, Tampermonkey
✅	Kiwi Browser	v116.0.5845.61	Android	Tampermonkey (MV2)
✅	Yandex Browser	v24.4	Windows	Tampermonkey (MV2), Tampermonkey (MV3)
✅	Arc	v1.6.1	Windows	Tampermonkey (MV3)
✅	Incognition	v4.1.1.0 (v125)	Windows	Tampermonkey (MV3), Tampermonkey (MV2)

Min. browser version is the lowest version where the extension was tested. This does not guarantee behavior on older versions. Please note that we do not support or fix issues in outdated browsers.

To activate the script in Tampermonkey (MV3), you must enable "Developer Mode".

Tested in the following userscript manager extensions:

Status	Browser	Extension
✅	Any	Tampermonkey Legacy (MV2)
✅	Opera	Violentmonkey
✅	Chrome	Tampermonkey (MV3)
⚠️¹	Safari	Userscripts
✅	Any	Violentmonkey
❔	Any	AdGuard Userscripts
Install guide	Firefox	Firemonkey
✅	Firefox	Greasemonkey
Install guide¹	Any	User Javascript and CSS

¹ - Works in proxy mode, disabling the "Use audio download" feature may cause issues with newly requested translations.

Contributing

Please refer to the contributing guide.

Based on sodapng/voice-over-translation project (license MIT)