Python library for FFmpeg-based video and audio processing. Provides the core functions behind PyVideoKit-CLI, and can be used directly in your own Python projects.
- 📼 VHS effect — retro visual noise, color bleed, and audio degradation
- ✂️ Trim — cut a segment by start/end time with stream copy (no re-encoding)
- 🔗 Concatenate — join multiple videos with stream compatibility validation
- 🎬 Fade — fade-in and/or fade-out on an FFV1 master
- 🔊 Extract audio — dump the audio track to uncompressed WAV (PCM 16-bit)
- 🎞️ Convert to FFV1 — create a lossless MKV master for editing
- 📺 Prepare for YouTube — encode to ProRes 422 HQ MOV, upscaled to 4K
- Python ≥ 3.10
- FFmpeg and FFprobe available in
PATH - SoX available in
PATH(required byapply_vhs_effect)
No Python package dependencies — the library delegates all heavy lifting to external tools via subprocess.
yay -S python-pyvideokit-libsFFmpeg, FFprobe, and SoX are installed automatically as pacman dependencies.
pip install PyVideoKit-LibsMake sure FFmpeg, FFprobe, and SoX are available in your PATH.
If you also have PyVideoKit-GUI installed, you can add it to your application launcher. Arch Linux users get this automatically via the AUR package. For all other systems:
1. Save the icon:
mkdir -p ~/.local/share/icons/hicolor/scalable/apps
cat > ~/.local/share/icons/hicolor/scalable/apps/pvk-gui.svg << 'EOF'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
<rect x="4" y="14" width="40" height="30" rx="3" fill="#2d3561"/>
<rect x="10" y="19" width="28" height="20" rx="2" fill="#1a2038"/>
<polygon points="18,21 18,37 33,29" fill="#ff6b6b"/>
<rect x="4" y="6" width="40" height="8" rx="2" fill="#ff6b6b"/>
<rect x="11" y="6" width="6" height="8" fill="#ffffff"/>
<rect x="23" y="6" width="6" height="8" fill="#ffffff"/>
<rect x="35" y="6" width="5" height="8" fill="#ffffff"/>
</svg>
EOF2. Create the .desktop entry:
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/pvk-gui.desktop << 'EOF'
[Desktop Entry]
Version=1.0
Type=Application
Name=PyVideoKit
GenericName=Video Processing Tool
Comment=FFmpeg-based video processing GUI
Exec=pvk-gui
Icon=pvk-gui
Categories=AudioVideo;Video;AudioVideoEditing;
Terminal=false
Keywords=video;ffmpeg;trim;fade;vhs;youtube;convert;
EOF3. Refresh the icon cache (may be required on some desktop environments):
gtk-update-icon-cache ~/.local/share/icons/hicolor/PyVideoKit will now appear in your application launcher.
from pathlib import Path
from pyvideokit_libs import convert_to_ffv1, fade_video, prepare_youtube
# 1. Create a lossless master
master = convert_to_ffv1(Path("recording.mp4"))
# 2. Add a 1-second fade in and out
faded = fade_video(master, fade_in=1.0, fade_out=1.0)
# 3. Export for YouTube
result = prepare_youtube(faded)
print(result)All functions accept an optional on_progress callback (pct: float) -> None for tracking progress.
Apply a retro VHS visual and audio effect. The input must have an audio stream. Produces a .mkv file.
out = apply_vhs_effect(Path("video.mp4"))Cut a segment from a video using stream copy (no re-encoding). start and end are in seconds.
out = trim_video(Path("video.mkv"), start=10.0, end=90.5)Use parse_time_to_seconds("00:01:30") to convert a timestamp string to seconds.
Concatenate two or more videos using stream copy. Validates stream compatibility (codec, resolution, fps, audio format) before proceeding.
out = join_videos([Path("clip1.mkv"), Path("clip2.mkv"), Path("clip3.mkv")])Add fade-in and/or fade-out to an FFV1 video. Output is re-encoded as FFV1 with PCM audio.
out = fade_video(Path("master.mkv"), fade_in=1.5, fade_out=2.0)Extract the audio track to an uncompressed WAV file (PCM 16-bit, pcm_s16le).
out = extract_audio(Path("video.mkv"))Convert any video to a lossless FFV1/MKV master. Use this as the first step before applying effects. fps defaults to None (preserve source frame rate); pass an integer to force a specific rate.
master = convert_to_ffv1(Path("recording.mp4")) # preserve source fps
master = convert_to_ffv1(Path("recording.mp4"), fps=60) # force 60 fpsEncode an FFV1 master to ProRes 422 HQ MOV for YouTube upload:
- Upscaled to 4K (2160p height), aspect ratio preserved
- ProRes 422 HQ (
prores_ks, profile 3), 10-bit 4:2:2 (yuv422p10le) - Uncompressed 16-bit PCM audio
out = prepare_youtube(Path("master_ffv1.mkv"))| Function | Description |
|---|---|
parse_time_to_seconds(ts) |
Parse SS, MM:SS, or HH:MM:SS to a float |
seconds_to_hms(seconds) |
Convert seconds to HH:MM:SS.mmm string |
probe_duration(path) |
Get media duration in seconds via FFprobe |
probe_stream_props(path) |
Get codec, dimensions, fps, sample rate, channels |
probe_video_codec(path) |
Get the video codec name |
probe_has_audio(path) |
Check whether an audio stream is present |
make_output_path(input_path, suffix, ext) |
Generate an output filename next to the input |
resolve_output_path(default, output) |
Resolve a file or directory output argument |
require_tools(*names) |
Raise if any external tool is not in PATH |
require_video_codec(path, codec, hint) |
Raise if the video codec does not match |
require_audio_stream(path) |
Raise if no audio stream is present |
run_ffmpeg_with_progress(cmd, duration, on_progress) |
Run an FFmpeg command with progress tracking |
All functions raise FFmpegError when an FFmpeg subprocess exits with a non-zero code.
from pyvideokit_libs import FFmpegError, convert_to_ffv1
try:
out = convert_to_ffv1(Path("bad_file.mp4"))
except FFmpegError as e:
print(f"FFmpeg failed (exit {e.returncode}):")
for line in e.error_lines:
print(line)convert_to_ffv1 → trim_video / fade_video / apply_vhs_effect → prepare_youtube
Functions that re-encode (
fade_video,apply_vhs_effect,prepare_youtube) expect an FFV1.mkvas input.
This project is licensed under the GPLv3 License — see the LICENSE file for details.