pyvideotrans - Moses Yebei

The Problem

Clients that need to repurpose video assets for new markets must run a manual chain: extract audio, run speech‑to‑text, translate the transcript, synthesize a new voice track, then re‑encode the video. Each step typically requires a separate tool, manual file handling and ad‑hoc scripting, which introduces errors and delays.

What This Does

pyvideotrans delivers an end‑to‑end pipeline that automates ASR → subtitle translation → multi‑role TTS → video muxing. The core CLI lives in cli.py (functions main, stt_fun, tts_fun, sts_fun). Configuration handling is centralized in videotrans/configure/config.py, which loads language lists, API keys and runtime options. UI components (videotrans/mainwin/*.py) expose the same workflow in a Qt front‑end, while the heavy‑lifting back‑ends are under videotrans/recognition/, videotrans/translator/ and videotrans/tts/, each providing a plug‑in style wrapper around dozens of online or local models.

How It Is Wired

Execution starts at cli.py:main (line 14). main parses command‑line arguments and then calls one of the three worker functions:

stt_fun → videotrans/process/stt_fun.py → videotrans/recognition/_base.py → external ASR APIs (network) or local Whisper (subprocess).
tts_fun → videotrans/process/tts_fun.py → videotrans/tts/_base.py → selected TTS backend (network) or local model (subprocess).
sts_fun → orchestrates the full translate‑and‑dub flow: 1. videotrans/configure/config._set_env (initialises env, logs). 2. videotrans/task/trans_create.py builds a Task object that iterates over video segments. 3. For each segment the call chain is: runffmpeg (in videotrans/util/help_ffmpeg.py) → external ffmpeg binary, BaseRecogn → ASR, BaseTrans → translation, BaseTTS → synthesis, finally runffmpeg again to merge audio/video.

The most‑connected module is videotrans/configure/config.py (266 inbound imports, 3 outbound), making it the primary blast‑radius: any change propagates to almost the whole codebase. A circular import involving videotrans/mainwin/main_win.py exists; breaking it would reduce import‑time side effects.

File I/O is performed in 93 places (e.g., Path(...).mkdir in cli.py:main, open in various helpers). Network calls appear in 18 locations (API wrappers in recognition/, translator/, tts/). External commands are invoked via subprocess.run in videotrans/util/help_ffmpeg.py (e.g., runffmpeg). Cryptographic use is limited to a MD5 helper in videotrans/util/help_misc.py.

How To Use It

# 1️⃣ Clone the repo
git clone https://github.com/moses-y/pyvideotrans
cd pyvideotrans

# 2️⃣ Install dependencies (uv is recommended)
uv sync               # creates a virtual env and installs from pyproject.toml
# or, with pip
python -m venv .venv && . .venv/bin/activate
pip install -e .     # editable install

# 3️⃣ Provide required config (API keys, model paths)
#   Edit videotrans/configure/config.py or supply a JSON/YAML file referenced there.
#   Example keys: OPENAI_API_KEY, AZURE_SPEECH_KEY, FASTER_WHISPER_MODEL_PATH

# 4️⃣ Run a full translation job
python cli.py sts_fun --src-lang en --tgt-lang zh --input path/to/video.mp4 --output out_dir

sts_fun runs the complete pipeline; use stt_fun or tts_fun for isolated speech‑to‑text or text‑to‑speech testing. The CLI options are defined in cli.py and surfaced via argparse.

Real‑World Use

A media agency can drop a raw interview (interview.mov) into a watched folder, call the CLI with the source and target language, and receive a fully dubbed MP4 ready for distribution, all without manual subtitle editing. The same code can be wrapped in a micro‑service that watches a queue and processes jobs asynchronously.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/main.yml).
HIGH – CI does not execute the test suite (.github/workflows/main.yml).
MEDIUM – No least‑privilege GITHUB_TOKEN permissions declared (.github/workflows/main.yml).
MEDIUM – Dependabot / Renovate not configured (no dependabot.yml).
MEDIUM – No dependency‑vulnerability scan in CI.
MEDIUM – Test coverage low (12 tests for 308 source files).
LOW – Workflow jobs lack timeout-minutes.

Additional static findings: deep nesting (max depth 10) in videotrans/configure/config.py and several modules contain duplicated 6‑line blocks, which inflates maintenance cost.

The Bottom Line

pyvideotrans assembles a full video‑translation workflow in a single Python package, with clear entry points and modular back‑ends for ASR, translation and TTS. Its biggest risk is the concentration of logic in a few hub modules and the current CI gaps; addressing those would make the codebase safer to extend. It is suitable for teams that need a customizable, on‑premise solution and are comfortable managing the dependency and configuration complexity.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

380 files

Python308
JSON16
Markdown7
YAML2
TOML1

Transformers

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["videotrans<br/>293 modules"] g1["tests<br/>12 modules"] g2["(root)<br/>3 modules"] g2 -->|13| g0 g1 -->|10| g0

Module dependencies

The 10 most depended-upon modules of 308, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_videotrans_configure_config["config"] n1_videotrans_util___init__["__init__"] n2_videotrans_configure_excepts["excepts"] n3_videotrans___init__["__init__"] n4_ideotrans_component_set_form["set_form"] n5_videotrans_task_taskcfg["taskcfg"] n6_videotrans_tts__base["_base"] n7_ideotrans_configure___init__["__init__"] n8_videotrans_util_ListenVoice["ListenVoice"] n9_videotrans_recognition__base["_base"] n3_videotrans___init__ --> n0_videotrans_configure_config n4_ideotrans_component_set_form --> n0_videotrans_configure_config n4_ideotrans_component_set_form --> n1_videotrans_util___init__ n0_videotrans_configure_config --> n5_videotrans_task_taskcfg n2_videotrans_configure_excepts --> n0_videotrans_configure_config n9_videotrans_recognition__base --> n2_videotrans_configure_excepts n9_videotrans_recognition__base --> n0_videotrans_configure_config n9_videotrans_recognition__base --> n5_videotrans_task_taskcfg n9_videotrans_recognition__base --> n1_videotrans_util___init__ n9_videotrans_recognition__base --> n7_ideotrans_configure___init__ n6_videotrans_tts__base --> n2_videotrans_configure_excepts n6_videotrans_tts__base --> n0_videotrans_configure_config n6_videotrans_tts__base --> n1_videotrans_util___init__ n8_videotrans_util_ListenVoice --> n3_videotrans___init__ n8_videotrans_util_ListenVoice --> n2_videotrans_configure_excepts

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

sayyid5416/pyinstaller@v1.6.0

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Make CI invoke the test suite it hashigh12 occurrences

.github/workflows

12 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/main.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Expand the test suite; it cannot cover this codebasemedium12 occurrences

12 test files against 308 source files (ratio 0.039)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow

.github/workflows/main.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.