pyVideoTrans

Appearance

pyVideoTrans FAQ and Troubleshooting ​

To help you get the most out of pyVideoTrans, we've compiled the following list of frequently asked questions and their solutions.

The Help/About menu contains many useful links, including model download URLs, CUDA configuration guides, and more. Check there if you encounter issues.

How to view logs: The logs/ folder in the software's root directory contains .log files named by date. When reporting errors, copy the last ~30 lines from the log file.

How to reset to factory defaults: Delete the four files cfg.json, params.json, codec.json, and ass.json from the videotrans/ directory, then restart the software.

Part 1: Installation and Startup Issues ​

1. Double-clicking sp.exe but the software won't open or shows no response for a long time? ​

This is usually normal — please be patient.

  • Cause: The software is built on PySide6 and the main interface contains many components. First-time initialization takes time. Depending on your computer, startup can take anywhere from 5 seconds to 2 minutes.
  • Solutions:
    1. Wait patiently: Allow some time after double-clicking.
    2. Check security software: Some antivirus programs may block the startup. Try temporarily disabling them, or add the software to your trusted list/whitelist.
    3. Check file path: Ensure the software is stored in a path containing only English letters and numbers — no Chinese characters, spaces, or special symbols. For example, D:\pyVideoTrans is fine, but D:\program file\视频 工具 may cause issues.
    4. Upgrade patch issue: If you applied an upgrade patch and can't start, the patching was done incorrectly. Download the full package again, extract it, then apply the new patch on top.

2. Startup error: missing python310.dll? ​

This means you downloaded only the patch, not the full package.

  • Solution:
    1. Download the full package from the official site.
    2. Extract the full package to a directory.
    3. Then download and extract the latest patch on top of the full package.

3. Does the software need to be installed? ​

No. The software is portable — no installation required. Extract the full package and double-click sp.exe to run directly.

4. Why does antivirus software flag or block the software? ​

  • Cause: The software is packaged with PyInstaller and does not have a commercial code signing certificate. Some security software may trigger a risk warning based on this — this is a common false positive.
  • Solutions:
    1. Add to trusted list: Add the software to your antivirus's trusted zone or whitelist.
    2. Run from source: If you're a developer, you can deploy from source to avoid this entirely.

5. Does the software support Windows 7? ​

No. Many core dependencies (PyTorch, PySide6, etc.) no longer support Windows 7. Please use Windows 10 or Windows 11.

6. How to deploy from source on macOS / Linux? ​

  • Prerequisites:
    • Python 3.10
    • FFmpeg (brew install ffmpeg / apt install ffmpeg)
    • uv package manager
    • libsndfile
  • Deployment steps:
    bash
    git clone https://github.com/jianchang512/pyvideotrans
cd pyvideotrans
uv sync
uv run sp.py
  • Optional extras: uv sync --all-extra installs all optional channels (qwen-tts, qwen-asr, moss-tts, chatterbox)

7. Startup error after deploying from source? ​

Common causes and solutions:

  • FFmpeg not installed: Ensure FFmpeg is installed and configured in your system PATH
  • Missing dependencies: Run uv sync to reinstall dependencies
  • Wrong Python version: Python 3.10 is required (specified in the .python-version file)

Part 2: Core Features and Settings ​

8. How to improve speech recognition accuracy? ​

Accuracy primarily depends on the model size and settings you choose.

  • Model selection: In "faster" or "openai" mode, larger models provide higher accuracy but are slower and more resource-intensive.
    • tiny: Smallest size, fastest speed, lowest accuracy.
    • base / small / medium: Balanced between performance and resource usage — commonly used options.
    • large-v3: Largest size, best accuracy, highest hardware requirements (8GB+ VRAM needed).
  • Optimized settings: Go to Tools/Options → Advanced Options

Find the faster/openai speech recognition adjustment section and apply these changes:

  • Voice threshold: Set to 0.5
  • Minimum duration / ms: Set to 3000
  • Max speech duration / sec: Set to 6
  • Silence separator ms: Set to 140
  • Hot words: Enter any domain-specific terms from the video here, separated by commas
  • Denoising: If the video has background music or noise, enable Split Vocal/BGM in More Settings to significantly improve recognition quality.

9. Why is the output video less clear / lower quality than the original? ​

Any operation involving re-encoding inevitably causes some quality loss. To maximize preservation of the original quality, ensure all of the following:

  1. Original video format: Use H.264 (libx264) encoded MP4 files for best compatibility.
  2. Disable video slowdown: Do not check Slow Video in the function options.
  3. Don't embed hard subtitles: Choose not to embed subtitles, or embed soft subtitles only. Hard subtitles force a complete video re-encode.
  4. Advanced Options → Video Output Quality: Default is 23; lower to 18 or below (minimum 0). Lower values = higher quality but larger file size.
  5. Advanced Options → Output Video Compression: Default is fast; choose slow or slower for higher quality at the cost of longer encoding time.
  6. Advanced Options → 264/265 Codec: Default is 264; choose 265 for higher quality output.

10. Why is the output video file extremely large? ​

  1. Adjust Advanced Options → Video Output Quality to 25–51 (higher value = smaller file but lower quality)
  2. Advanced Options → 264/265 Codec: Choose 265 — at the same quality level, H.265 produces smaller files

11. How to configure a network proxy? ​

Some translation or dubbing services (Google, OpenAI, Gemini, etc.) cannot be accessed directly from mainland China and require a proxy.

  • Setup: Enter your proxy server address in the "Proxy" text box on the main interface.
  • Format: Typically http://127.0.0.1:10808 (use the port from your proxy client settings).
  • Important: If you don't have a proxy or don't understand what it is, leave this field blank. Incorrect settings will cause errors.
  • Domestic APIs don't need a proxy: Baidu Translate, Tencent Translate, Alibaba Translate, DeepSeek, Zhipu AI, ByteDance Volcengine, and other domestic APIs bypass the proxy by default.
  • Local services don't need a proxy: GPT-SoVITS, ChatTTS, F5-TTS, and other local services automatically bypass the proxy.

12. How to customize subtitle font, color, and style? ​

Click on the main interface → More Settings → Hard Subtitle Style

Part 3: Speech Recognition Issues ​

13. Recognition result is empty or garbled ​

  • Cause: Possible language mismatch, no valid human speech in the video, or insufficient VRAM
  • Solutions:
    1. Check that the "Source Language" is correctly selected (don't over-rely on Auto)
    2. Check if background music is interfering (try enabling denoise)
    3. Insufficient VRAM: Lower beam_size, switch to int8 quantization, or use the small model
    4. Try switching ASR channels (e.g., from faster-whisper to openai-whisper)

14. Recognition is extremely slow ​

  • Cause: Using a large model without GPU acceleration
  • Solutions:
    1. Enable CUDA acceleration: Ensure CUDA 12.8+ and cuDNN 9.x are installed, then check Enable CUDA?
    2. Use a smaller model: Switch from large-v3 to medium or small
    3. CPU mode optimization: In Advanced Options, change Compute Data Type to int8

15. Out of memory error (Unable to allocate, CUDA out of memory) ​

  • Cause: Model is too large or VRAM is occupied by other programs
  • Solutions (in recommended order):
    1. Use a smaller model: Switch the recognition model from large-v3 to medium, small, or base. The large-v3 model requires at least 8GB VRAM.
    2. Adjust advanced settings: Go to Tools/Options → Advanced Options and make these changes:
      • CUDA Data Type: Change float32 to float16 or int8
      • beam_size: Change 5 to 1
      • best_of: Change 5 to 1
      • Context: Change true to false
    3. Check multi-GPU setup: If multiple GPUs are available, check if the first GPU has enough free VRAM. The software uses the first GPU by default; versions v3.98-317 and later automatically select the GPU with the most available VRAM.

16. Speaker diarization is inaccurate ​

  • Cause: The speaker diarization model has limited effectiveness in certain scenarios (e.g., multiple people speaking simultaneously, high background noise)
  • Solutions:
    1. In More Settings, enable Speaker Diarization and specify the number of speakers
    2. In Advanced Options, switch the diarization model (built-in, Ali CAM++, pyannote)
    3. Using the pyannote model requires applying for a HuggingFace token and agreeing to the license

17. LLM re-segmentation produces worse results ​

  • Cause: Local small models (e.g., 7B) lack sufficient intelligence, or the prompt is overly complex
  • Solutions:
    1. Use a stronger online model (DeepSeek-V3, GPT-4o, etc.)
    2. Simplify the prompt (edit in videotrans/prompts/recharge/recharge-llm.txt)
    3. When using clone voice cloning, it is not recommended to use LLM re-segmentation

18. Subtitles and audio are out of sync after dubbing ​

This is a common phenomenon in dubbed translations, caused by duration differences between languages.

  • Cause: Different languages require different numbers of syllables and grammatical structures to express the same meaning, leading to duration mismatches. For example, a 2-second Chinese sentence may become 3–4 seconds when dubbed in English.
  • Solutions:
    1. Enable Dubbing Speedup: Check Dubbing Speedup+ to automatically compress long dubbing to match subtitle duration
    2. Enable Slow Video: Check Slow Video to slow down the video to match dubbing duration
    3. Enable both: When the speed ratio exceeds 1.2x, both speedup and slowdown share the time difference equally
    4. Adjust speech rate: Set a Dubbing Rate value (e.g., +10%) to speed up overall dubbing
    5. Enable STT again: Check STT again to re-recognize the dubbed audio for more precise subtitle timing

For detailed principles, see Audio-Video Timeline Alignment

19. What is "STT again" and when is it needed? ​

STT again performs speech recognition on the dubbed audio after dubbing is complete, generating subtitles with more precise timing and shorter text.

  • When to use: When you've selected single subtitle embedding (hard or soft subtitles) and need precise alignment between subtitles and audio
  • Setup: Enable STT again, and configure the max/min speech duration in Advanced Options
  • Note: STT again requires additional processing time

Part 4: Translation Issues ​

20. Translation results contain blank lines or prompt text ​

  • Cause: Local small models lack intelligence, or the AI merged subtitle lines
  • Solutions:
    1. Local small models (e.g., 7B) are insufficient — switch to an online model like DeepSeek/GPT-4
    2. Disable Send SRT to switch to line-by-line translation
    3. Set trans_thread=1 to reduce concurrency
    4. For detailed explanation and solutions, see here

21. AI translation triggers content safety filtering ​

  • Error message: Content was filtered by AI risk control
  • Cause: The translation content was intercepted by the AI service's safety system
  • Solutions:
    1. Manually edit the subtitles to remove potentially triggering content
    2. Switch translation channels (e.g., from OpenAI to DeepSeek)

22. Translation doesn't match the original (subtitle lines misaligned) ​

  • Cause: The AI merged subtitle lines during translation, causing line number offset
  • Solutions:
    1. In Advanced Options, disable Send SRT
    2. Set translation concurrency to 1
    3. Use an online AI model with large context support

23. Translation cache produces stale results ​

  • Cause: Translation results were cached; changes to prompts or translation channels haven't taken effect
  • Solutions:
    1. Check the Clean Output checkbox on the main interface
    2. Or manually delete cache files in the tmp/translate_cache/ directory

Part 5: Dubbing Issues ​

24. Edge-TTS error 403 or generates silence ​

  • Cause: Microsoft rate limiting — too many requests in a short time
  • Solutions:
    1. In Advanced Options, set "Dubbing Threads" to 1
    2. Set "Dubbing Pause Seconds" to 5–10 seconds
    3. If using a proxy, Edge-TTS may fail due to proxy issues. Create an empty file named edgetts-noproxy.txt in the software's root directory to force bypass the proxy

25. F5-TTS / CosyVoice / GPT-SoVITS won't connect ​

  • Cause: Local TTS service not started or incorrect address configuration
  • Solutions:
    1. Ensure the external TTS service terminal window is still running
    2. Check the API address is correct (pay attention to port numbers)
    3. GPT-SoVITS needs to start api.py or api_v2.py — do NOT use the web UI on port 7860
    4. If you entered 0.0.0.0 as the address, change it to 127.0.0.1

26. GPT-SoVITS error {"detail":"Not Found"} ​

  • Cause: API version mismatch or wrong port
  • Solutions:
    1. Check whether you started api.py or api_v2.py, and enable the corresponding api_v2? option in the software
    2. Ensure you entered the API address (default 9880), not the web UI address (7860)

27. Index-TTS error Value: 'Same as the voice reference' is not in the list ​

  • Cause: Index-TTS internal bug with inconsistent multilingual translations
  • Solution: Open webui.py in the Index-TTS project root and replace i18n("与音色参考音频相同") with Same as the voice reference

28. Azure-TTS error Could not find module Microsoft.CognitiveServices.Speech.core.dll ​

  • Cause: Missing Microsoft VC++ runtime libraries
  • Solutions:
    1. If you downloaded only the patch, re-download the full package
    2. If you already have the full package, install the Microsoft Visual C++ Redistributable and restart your computer

29. Dubbed audio sounds robotic or has artifacts ​

  • Cause: Audio speedup ratio too high (> 3x), or poor quality reference audio
  • Solutions:
    1. Enable Slow Video to share the time difference with Dubbing Speedup+
    2. Improve reference audio quality: use clear 5–10 second single-speaker WAV files
    3. Enable Split Vocal/BGM to remove background noise

Part 6: Voice Cloning Issues ​

30. Voice cloning with clone role fails or has poor quality ​

  • Cause: Reference audio duration is outside the 3–10 second range, or the subtitle timeline was disrupted by LLM re-segmentation
  • Solutions:
    1. Disable LLM re-segmentation: It disrupts the timeline and causes misaligned reference audio extraction
    2. Force subtitle duration limits: In Advanced Options → ASR Parameters, set Max Speech Duration to 6–10 seconds and Min Speech Duration to 3000–4000 ms
    3. Enable Merge Short Subtitles to Adjacent and Whisper Pre-segmentation
    4. Use the OmniVoice-TTS channel for better compatibility with short reference audio
    5. Enable Split Vocal/BGM to improve reference audio quality

31. How to use custom reference audio? ​

  1. Record or extract a 5–10 second WAV format audio clip (single speaker, no background noise)
  2. Copy the audio to the f5-tts folder in the software directory
  3. Open TTS Settings → Set Reference Audio and fill in: filename.wav#spoken text of the audio
  4. Select the filename from the voice role dropdown on the main interface

Note: GPT-SoVITS reference audio must be placed in the GPT-SoVITS root directory, NOT in the f5-tts folder.

Part 7: Video Composition and Output Issues ​

32. Error ffprobe exec error or ffmpeg related exception during processing ​

  • Cause: File path too long or contains special characters
  • Solutions:
    1. Move the video file to a shallower directory (e.g., D:\videos)
    2. Rename to a short English or numeric filename
    3. Remove special characters from the filename (?*, emojis, etc.)

33. Software reports the video "has no audio track" ​

  • Possible cause 1: The video genuinely has no audio (some websites separate video and audio streams)
  • Possible cause 2: Video codec format is unsupported (e.g., AV1)
  • Possible cause 3: Background noise is too loud, masking human speech
  • Solutions:
    1. Play the video locally in a media player to confirm audio is present
    2. Try converting the video to standard H.264/MP4 format first
    3. Enable denoise or vocal/BGM separation

34. How to output a lossless video? ​

Video will be output without re-encoding when ALL of the following conditions are met:

  1. Original video is encoded as mp4/h.264/yuv420p
  2. Advanced Options → 264/265 Codec is set to 264
  3. Slow Video is NOT enabled
  4. Embed Hard Subs is NOT selected (soft subtitles don't affect this)

Note: If the dubbed audio is longer than the original video, the excess will be truncated.

35. Audio, subtitles, and video are out of sync after processing ​

This is normal in language translation scenarios.

  • Cause: Different languages use different sentence lengths and syllable counts to express the same meaning, so dubbing duration inevitably changes.
  • Solutions:
    1. Enable Dubbing Speedup+ and/or Slow Video
    2. Set a Dubbing Rate (e.g., +10%) to speed up overall speed
    3. Enable STT again for more precise subtitle timing
    4. For detailed principles, see Audio-Video Timeline Alignment

36. Persistent out-of-VRAM errors (e.g., Unable to allocate) ​

This means your GPU doesn't have enough VRAM or memory for the current task.

  • Solutions (in recommended order):
    1. Use a smaller model: Switch the recognition model from large-v3 to medium, small, or base
    2. Adjust advanced settings:
      • CUDA Data Type: Change float32 to float16 or int8
      • beam_size: Change 5 to 1
      • best_of: Change 5 to 1
      • Context: Change true to false

37. CUDA is installed, but GPU acceleration is not working? ​

Check the following possible causes:

  • CUDA version incompatible: The software requires CUDA 12.8 or higher
  • Outdated GPU driver: Update your NVIDIA driver to the latest version
  • Missing cuDNN: Ensure cuDNN 9.x is installed and configured in your environment variables
  • Hardware incompatible: GPU acceleration only supports NVIDIA GPUs. AMD and Intel GPUs cannot use CUDA
  • Environment variables not set: Check that your system PATH includes CUDA's bin and lib directories

38. GPU usage is low — is that normal? ​

Yes, it's normal. The software's workflow is: Speech Recognition → Text Translation → Text-to-Speech → Video Composition.

Only the first stage — "Speech Recognition" — makes heavy use of the GPU. Other stages (translation, composition) primarily rely on the CPU. Low GPU utilization during most of the process is expected behavior.

39. After processing several videos, disk space is full? ​

This is usually caused by the Slow Video feature generating many temporary files.

  • Cause: This feature splits the video into many small segments by subtitle and processes each one, generating cache files far larger than the original video.
  • Solutions:
    1. Manual cleanup: After processing, manually delete all contents inside the tmp/ folder in the software root directory
    2. Automatic cleanup: The software automatically cleans these caches when you close it normally

40. Re-processing the same video always produces the same recognition results and subtitles? ​

  • Cause: The software enables caching by default. If it detects that subtitle files have already been generated for a video, it uses the cached results.
  • Solution: Check the Clean Output checkbox in the top-left area of the main interface

Part 8: Batch Processing Issues ​

41. Batch video translation always gets stuck ​

By default, batch tasks split each job into multiple stages with cross-stage parallel processing. Too many tasks can exhaust system resources.

  • Solution: Enable Advanced Options → Force Serial Execution for Batch Translation to switch to serial processing.

42. How to control concurrency in batch processing? ​

In Advanced Options → General Settings:

  • CPU Concurrent Tasks: Maximum CPU tasks running simultaneously — should not exceed CPU core count
  • GPU Concurrent Tasks: Number of GPU tasks running simultaneously — set to 1 unless you have multi-GPU or a single GPU with >24GB VRAM
  • Batch Translation Videos Per Batch: Set to 1 for sequential processing, or 0 to process all at once

Part 9: Advanced Options Explained ​

43. What's the difference between Dubbing Speedup and Slow Video? ​

OptionEffectBest for
Dubbing SpeedupSpeeds up dubbed audio to match subtitle duration; slight quality loss possibleDubbing is 1–2x longer than subtitles
Slow VideoSlows down video to match dubbing duration; video may stutter slightlyDubbing is 2x+ longer than subtitles
Both enabledEach handles half the time difference for best resultsDubbing is much longer than subtitles

44. What does Send SRT do? ​

When enabled, the AI translation receives the full SRT format including line numbers and timestamps, producing better translation quality but potentially merging lines. Recommendations:

  • Enable when using large online models (DeepSeek, GPT-4o)
  • Disable when using small local models

45. What's the difference between STT again and LLM Re-segmentation? ​

OptionWhen it runsPurpose
LLM Re-segmentationAfter speech recognitionAI corrects typos, re-segments long text
STT againAfter dubbing is completeRe-recognizes dubbed audio for more precise timeline

When using clone voice cloning, it is not recommended to use LLM re-segmentation.

46. How to choose a subtitle embedding type? ​

TypeDescriptionUse case
No subtitle embeddingReplaces voice only, no subtitles addedDubbing only
Embed Hard SubsSubtitles permanently burned into the video, cannot be turned offUniversal player compatibility
Embed Soft SubsSubtitles as a separate track, can be toggled on/off in playerFlexible subtitle display
Embed Hard Subs (Bi)Bilingual hard subtitles (e.g., Chinese + English)Bilingual comparison
Embed Soft Subs (Bi)Bilingual soft subtitlesBilingual comparison with toggle

Part 10: File and Path Issues ​

47. What are the requirements for input file paths? ​

  1. Path length: Windows command line has a 260-character limit; keep file paths as short as possible
  2. Special characters: Filenames should not contain ?*, emojis, or other special symbols
  3. Chinese characters in path: Supported but English paths are recommended to avoid compatibility issues
  4. Spaces: Paths can contain spaces, but it's best to avoid them

48. Where are output files saved? ​

  • Default location: _video_out/ folder in the original video's directory
  • Batch tool outputs: Batch transcription, dubbing, and SRT translation output to the output/ directory
  • Custom output: Configurable via the main interface

49. How to import existing SRT subtitles? ​

  1. Create a _video_out/ folder in the same directory as the video
  2. Create a subfolder with the video name including format extension (e.g., myvideo-mp4)
  3. Copy subtitle files into the subfolder, renaming them to source-lang.srt (source) and target-lang.srt (target)
  4. Import the video and run translation — the software will automatically skip the ASR and translation stages

Part 11: CLI Issues ​

50. Basic CLI usage ​

bash
uv run cli.py --task <task-type> --name "<file-path>" [other parameters]

Task types: stt (speech-to-text), tts (text-to-speech), sts (subtitle translation), vtv (video translation)

51. How to view available channels and languages? ​

bash
uv run cli.py --list providers    # View all channels
uv run cli.py --list languages    # View all language codes
uv run cli.py --list models       # View faster-whisper models

52. Common CLI errors ​

  • --name is required: No input file specified
  • File not found: Wrong file path or file doesn't exist
  • --voice_role is required: Voice role must be specified in TTS mode
  • --target_language_code is required: Target language must be specified in STS/VTV mode

Part 12: General Information ​

53. Does the software support Docker deployment? ​

Yes. Via the WebUI interface.

54. Can the software recognize hard subtitles in the video (OCR)? ​

No. The software works by analyzing the audio track of the video, recognizing human speech, and converting it to text. It does not have optical character recognition (OCR) capabilities. If you need this feature, check out this separate project for extracting hard subtitles from videos

55. Can I add support for new languages? ​

Yes, new target languages can be added. See here for details.

56. Is the software free? Can it be used commercially? ​

  • Cost: This is a free and open-source project. All features can be used at no cost. Note that third-party translation, TTS, or STT APIs may charge their own fees, but this is unrelated to the software itself.
  • Commercial use: Individuals and companies are free to use this software. However, if you want to integrate this project's code into your own commercial product, you must comply with the GPL-v3 open-source license. Additionally, some channels use models or online APIs that may have their own license requirements regarding commercial use — consult the respective platform for details.

57. Is customer support available? ​

No. This is a free, open-source project developed by an individual without revenue, so a dedicated support team is not available. If you encounter issues, please carefully read this FAQ first. Alternatively, you can scan the WeChat QR code in the bottom-right corner of the software to make a donation, leave your WeChat ID in the message, and receive paid technical support.

58. Where to download the software and models? ​

59. Errors and logs ​

  • Log location: The logs folder in the software root directory contains log files named with the current date
  • Reporting: Click "Report Error" in error dialogs to automatically submit to the official forum; or copy the last 30 lines of the log to ask an AI assistant

60. Why does the new version no longer have "Auto Detect" in the spoken language list? ​

"Auto Detect" is available in the "Batch Speech To Text" panel. It was removed from the "Translate A/V" function because downstream steps (subtitle translation, dubbing involving reference audio) require a clearly specified source language for certain channels, otherwise errors will occur. If you only need to transcribe speech to subtitles, use the "Batch Speech To Text" panel on the left.

Quick Troubleshooting Table ​

ProblemPossible CauseSolution
Software won't startAntivirus blocking / path issueAdd to whitelist / move to English path
Missing python310.dllDownloaded patch onlyDownload full package, then apply patch
Empty recognition resultsWrong language / no valid speechSelect correct language / enable denoise
Out of VRAMModel too largeUse smaller model / switch to int8 / lower beam_size
GPU not enabledCUDA not installed / driver outdatedInstall CUDA 12.8+ / update driver
Translation has blank linesAI merged subtitle linesDisable Send SRT / use online model
Edge-TTS 403Microsoft rate limitingReduce concurrency / increase pause seconds
Audio/subtitle out of syncLanguage duration differencesEnable Dubbing Speedup / Slow Video
ffprobe errorPath too long or special charactersSimplify filename / move to shallower directory
Disk space fullSlow Video generates temp filesClean the tmp/ folder
Poor clone dubbingReference audio duration issuesKeep 3–10 seconds / disable LLM re-segmentation
GPT-SoVITS 404API version mismatchCheck api.py vs api_v2.py