Vezur Video Converter

Convert local videos to MP4, MOV, MKV, or WebM from Python or your terminal. This package provides a small set of explicit FFmpeg presets, media inspection, and failure-safe output handling. It has no Python runtime dependencies.

Project homepage: Vezur AI.

Requirements and installation

• Python 3.10 or newer.
• A separately installed FFmpeg distribution providing both ffmpeg and ffprobe on your PATH.
• Your FFmpeg build needs libx264 and aac for MP4/MOV/MKV, and libvpx-vp9 and libopus for WebM. Check with ffmpeg -encoders.

python -m pip install vezur-video-converter
ffmpeg -version
vezur-video --help

For example, install FFmpeg with brew install ffmpeg on macOS or sudo apt install ffmpeg on Debian/Ubuntu. On Windows, use a build linked from the FFmpeg download page and add its bin directory to PATH. You can also pass executable paths with --ffmpeg and --ffprobe.

FFmpeg is not bundled or downloaded by this package. Conversion runs locally; no Vezur account, API key, or upload is required.

Command-line examples

# MOV to MP4 (H.264 video and AAC audio)
vezur-video convert input.mov output.mp4

# MP4 to WebM (VP9 video and Opus audio)
vezur-video convert input.mp4 output.webm

# Resize proportionally and set frame rate
vezur-video convert input.mov small.mp4 --width 1280 --fps 30

# Remove audio and use a higher-quality H.264 setting
vezur-video convert input.mkv silent.mp4 --no-audio --crf 18

# Replace an existing destination only after conversion succeeds
vezur-video convert input.mov output.mp4 --overwrite --timeout 120

# JSON format/stream information, including codec, duration, and dimensions
vezur-video info output.mp4

# Available output extensions
vezur-video formats

python -m vezur_video_converter also works in place of vezur-video. Quote paths containing spaces. For an input name starting with a dash, use a path such as ./-clip.mov. The CLI returns 0 on success, 1 for processing or file errors, 2 for invalid command syntax, and 130 for interruption.

Python API

from vezur_video_converter import convert, probe

output = convert("input.mov", "output.mp4", width=1280, fps=30, timeout=120)
print(output)  # absolute pathlib.Path

metadata = probe(output)
for stream in metadata["streams"]:
    print(stream["codec_type"], stream["codec_name"])

Optional convert() arguments:

probe() accepts timeout (default 30 seconds) and ffprobe (default "ffprobe"). Its dictionary follows ffprobe's JSON schema; many numeric values are strings, and available keys depend on the input media.

Missing binaries raise DependencyError; encoder errors or timeouts raise ConversionError. Invalid options raise ValueError. Missing files, existing destinations, and filesystem failures raise standard OSError subclasses.

Conversion behavior and limits

• Input formats depend on your FFmpeg installation. Input must be a local file; remote URLs are not accepted, and network protocols are disabled for inputs.
• Conversion re-encodes video. It is not a lossless remuxer. CRF values are not directly comparable between encoders; lower values often increase file size.
• Only the first video and first audio stream are selected. Additional audio tracks, subtitles, data streams, chapters, and source metadata are omitted.
• Video output uses 8-bit yuv420p. This is intended for ordinary SDR clips; HDR tone mapping, alpha preservation, and professional color workflows are outside the scope of these presets.
• Without width, odd dimensions are padded to even dimensions by at most one pixel. With width, the height is rounded to an even value.
• Audio defaults to 128 kbps. Silent video inputs are supported.
• The destination directory must exist. Input and output must be different files, and symbolic-link destinations are rejected.
• Conversion writes a temporary file beside the destination. On failure or timeout, temporary output is removed and an existing destination is preserved. Allow enough free disk space for a full output file. Without overwrite, publication uses a hard link to avoid overwriting files created concurrently; this requires a filesystem with hard-link support (such as APFS, ext4, or NTFS). On unsupported filesystems, use a supported output location or explicitly opt into overwrite=True / --overwrite.
• This is a local command-line/library utility, not a sandbox for hostile media or a production upload service. Keep FFmpeg current and isolate untrusted processing appropriately when building a service around it.

Development

python -m venv .venv
# macOS/Linux; on Windows use .venv\Scripts\activate
source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest
python -m ruff check .
python -m build
python -m twine check --strict dist/*

Integration tests generate tiny synthetic video/audio files and exercise actual conversions. They are skipped if FFmpeg or ffprobe is missing. No user videos are needed. Tests require the encoders listed above.

License

The Python wrapper is MIT licensed. FFmpeg is a separate dependency with its own license and codec-related requirements; this package does not redistribute it.