Metadata-Version: 2.5
Name: vezur-video-converter
Version: 0.1.0
Summary: Local video conversion and inspection with FFmpeg, a Python API, and a CLI.
Project-URL: Homepage, https://vezurai.com
Author: Vezur AI
License-Expression: MIT
License-File: LICENSE
Keywords: converter,ffmpeg,mp4,video,webm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://vezurai.com).

## Requirements and installation

- Python 3.10 or newer.
- A separately installed [FFmpeg](https://ffmpeg.org/download.html) 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`.

```bash
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

```bash
# 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

```python
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:

| Argument | Default | Meaning |
| --- | --- | --- |
| `overwrite` | `False` | Replace an existing destination only on successful conversion |
| `width` | `None` | Positive even width; height is calculated proportionally and rounded to even |
| `fps` | `None` | Finite positive output frame rate; FFmpeg may duplicate/drop frames |
| `crf` | `None` | H.264: 0–51, default 23; VP9: 0–63, default 32; lower generally means higher quality |
| `audio` | `True` | Include the first audio stream when present |
| `timeout` | `None` | Maximum FFmpeg runtime in seconds; no time limit by default |
| `ffmpeg` | `"ffmpeg"` | Executable name or path |

`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

| Output | Video encoder | Audio encoder | Defaults |
| --- | --- | --- | --- |
| `.mp4` | libx264 / H.264 | AAC | CRF 23, medium preset, faststart |
| `.mov` | libx264 / H.264 | AAC | CRF 23, medium preset, faststart |
| `.mkv` | libx264 / H.264 | AAC | CRF 23, medium preset |
| `.webm` | libvpx-vp9 / VP9 | Opus | CRF 32, constant quality with zero target bitrate |

- 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

```bash
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.
