This module contains the various video processing backends.
FFmpeg Backend
FFmpeg backend for FMUS-VID.
This module provides the FFmpeg implementation of the Backend interface.
-
class fmusvid.backends.ffmpeg.FFmpegBackend[source]
FFmpeg implementation of the Backend interface.
-
__init__()[source]
Initialize the FFmpeg backend.
-
__del__()[source]
Clean up temporary files on instance destruction.
-
load(path, **kwargs)[source]
Load a video file.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
Video dictionary
-
create(width, height, duration, fps, color, **kwargs)[source]
Create a blank video.
- Parameters:
width (int) – Width in pixels
height (int) – Height in pixels
duration (float) – Duration in seconds
fps (float) – Frames per second
color (Tuple[int, int, int]) – Background color as RGB tuple
**kwargs – Additional options
- Return type:
Dict[str, Any]
- Returns:
Video dictionary
-
save(video, output_path, progress_callback=None, **kwargs)[source]
Save video to file.
- Parameters:
video (Dict[str, Any]) – Video dictionary
output_path (Union[str, Path]) – Output file path
progress_callback (Optional[Callable[[float], None]]) – Function to call with progress (0-1)
**kwargs – Additional options (codec, bitrate, etc.)
- Return type:
None
-
static is_available()[source]
Check if FFmpeg is available on the system.
- Return type:
bool
Core functionality for the FFmpeg backend.
Contains utility functions for finding ffmpeg/ffprobe, running commands, etc.
-
class fmusvid.backends.ffmpeg.core.FFmpegCore[source]
Core FFmpeg functionality.
-
get_info(video)[source]
Get video information.
- Parameters:
video (Dict[str, Any]) – Video dictionary
- Return type:
Dict[str, Any]
- Returns:
Dictionary with video info
FFmpeg filter operations.
This module provides implementation for various video filters with caching.
-
class fmusvid.backends.ffmpeg.filters.FFmpegFilters[source]
FFmpeg filters implementation with caching mechanism.
-
grayscale(video)[source]
Convert video to grayscale.
- Parameters:
video (Dict[str, Any]) – Video dictionary
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
apply_filter(video, filter_string)[source]
Apply a custom FFmpeg filter with caching.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
blur(video, radius)[source]
Apply Gaussian blur with specified radius.
- Parameters:
video (Dict[str, Any]) – Video dictionary
radius (float) – Blur radius (1.0 = slight blur, 10.0 = heavy blur)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
brightness(video, factor)[source]
Adjust video brightness.
- Parameters:
video (Dict[str, Any]) – Video dictionary
factor (float) – Brightness factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
contrast(video, factor)[source]
Adjust video contrast.
- Parameters:
video (Dict[str, Any]) – Video dictionary
factor (float) – Contrast factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
saturation(video, factor)[source]
Adjust video saturation.
- Parameters:
video (Dict[str, Any]) – Video dictionary
factor (float) – Saturation factor (1.0 = original, 1.5 = +50%, 0.5 = -50%, 0 = grayscale)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
batch_filters(video, filters)[source]
Apply multiple filters in a single FFmpeg operation.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
speed(video, factor)[source]
Change video playback speed.
- Parameters:
video (Dict[str, Any]) – Video dictionary
factor (float) – Speed factor (2.0 = 2x faster, 0.5 = half speed)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
fade_in(video, duration)[source]
Fade video in from black.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
fade_out(video, duration)[source]
Fade video out to black.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
fade_audio_in(video, duration)[source]
Fade audio in.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
fade_audio_out(video, duration)[source]
Fade audio out.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
chroma_key(video, color, similarity=0.1, blend=0.0)[source]
Remove green screen / chroma key.
- Parameters:
video (Dict[str, Any]) – Video dictionary
color (Tuple[int, int, int]) – RGB color to key out (e.g., (0, 255, 0) for green)
similarity (float) – Color similarity threshold (0.01 to 1.0)
blend (float) – Blend factor for semi-transparent edges (0.0 to 1.0)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
normalize_audio(video, target_db=-16.0)[source]
Normalize audio to target dB level.
- Parameters:
video (Dict[str, Any]) – Video dictionary
target_db (float) – Target loudness in dB (typically -16 to -20)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
crossfade(video1, video2, duration)[source]
Crossfade between two videos.
- Parameters:
video1 (Dict[str, Any]) – First video dictionary
video2 (Dict[str, Any]) – Second video dictionary
duration (float) – Crossfade duration in seconds
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
FFmpeg conversion operations.
This module provides implementation for various video conversion operations.
-
class fmusvid.backends.ffmpeg.conversion.FFmpegConversion[source]
FFmpeg implementation for conversion operations.
-
trim(video, start, end=None)[source]
Trim video to specified time range.
- Parameters:
video (Dict[str, Any]) – Video dictionary
start (float) – Start time in seconds
end (Optional[float]) – End time in seconds (None means until the end)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
resize(video, width=None, height=None, keep_aspect=True)[source]
Resize video to specified dimensions.
- Parameters:
video (Dict[str, Any]) – Video dictionary
width (Optional[int]) – Target width (None to auto-calculate from height)
height (Optional[int]) – Target height (None to auto-calculate from width)
keep_aspect (bool) – Maintain aspect ratio if only one dimension is specified
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
crop(video, x, y, width, height)[source]
Crop video to specified region.
- Parameters:
video (Dict[str, Any]) – Video dictionary
x (int) – X coordinate of top-left corner
y (int) – Y coordinate of top-left corner
width (int) – Width of crop region
height (int) – Height of crop region
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
rotate(video, degrees)[source]
Rotate video by specified degrees.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
Extract a single frame at specified time.
- Parameters:
-
- Return type:
Any
- Returns:
PIL Image
-
concat(videos)[source]
Concatenate multiple videos.
- Parameters:
videos (List[Dict[str, Any]]) – List of video dictionaries
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
grid(videos, rows, cols, **kwargs)[source]
Arrange videos in a grid layout.
- Parameters:
videos (List[Dict[str, Any]]) – List of video dictionaries
rows (int) – Number of rows
cols (int) – Number of columns
**kwargs – Additional options (padding, etc.)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
reverse(video)[source]
Reverse video playback.
- Parameters:
video (Dict[str, Any]) – Video dictionary
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
replace_audio(video, audio_path)[source]
Replace audio track with new audio.
- Parameters:
video (Dict[str, Any]) – Video dictionary
audio_path (Union[str, Path]) – Path to new audio file
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
export_gif(video, output_path, fps=None, quality=95, loop=0, width=None)[source]
Export video as animated GIF.
- Parameters:
video (Dict[str, Any]) – Video dictionary
output_path (Union[str, Path]) – Output GIF path
fps (Optional[float]) – Frame rate for GIF (None = use original)
quality (int) – Quality (1-100, higher = better)
loop (int) – Loop count (0 = infinite)
width (Optional[int]) – Resize width (None = keep original)
- Return type:
None
-
export_frames(video, output_dir, prefix='frame_', format='png', start=None, end=None, fps=None)[source]
Export video frames as images.
- Parameters:
video (Dict[str, Any]) – Video dictionary
output_dir (Union[str, Path]) – Output directory path
prefix (str) – Filename prefix
format (str) – Image format (png, jpg, etc.)
start (Optional[float]) – Start time in seconds (None = from beginning)
end (Optional[float]) – End time in seconds (None = to end)
fps (Optional[float]) – Frame rate for extraction (None = use original fps)
- Return type:
List[Path]
- Returns:
List of exported frame paths
FFmpeg overlay functionality.
This module provides functionality for overlaying videos, images, and text.
-
class fmusvid.backends.ffmpeg.overlay.FFmpegOverlay[source]
FFmpeg overlay functionality with caching capabilities.
-
overlay_frame(frame_data, overlay_data, position=(0, 0), opacity=1.0)[source]
Overlay an image on the frame.
- Parameters:
frame_data (Any) – Frame data (PIL Image)
overlay_data (Any) – Overlay image (PIL Image)
position (Tuple[int, int]) – (x, y) coordinates for placement
opacity (float) – Opacity of overlay (1.0 = fully opaque)
- Return type:
Any
- Returns:
Combined PIL Image
-
add_text_to_frame(frame_data, text, position, font='Arial', size=24, color='white')[source]
Add text to the frame.
- Parameters:
frame_data (Any) – Frame data (PIL Image)
text (str) – Text to add
position (Tuple[int, int]) – (x, y) coordinates for placement
font (str) – Font name
size (int) – Font size
color (Union[str, Tuple[int, int, int]]) – Text color (name or RGB tuple)
- Return type:
Any
- Returns:
PIL Image with text
-
overlay(video, overlay_video, position=(0, 0), start=0, duration=None, opacity=1.0)[source]
Overlay another video (picture-in-picture) with caching.
- Parameters:
video (Dict[str, Any]) – Video dictionary
overlay_video (Dict[str, Any]) – Video to overlay
position (Tuple[int, int]) – (x, y) coordinates for placement
start (float) – Start time in seconds
duration (Optional[float]) – Duration to display overlay (None = full duration)
opacity (float) – Opacity of overlay (1.0 = fully opaque)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
batch_overlay(video, overlays)[source]
Apply multiple overlays in a single FFmpeg operation.
- Parameters:
video (Dict[str, Any]) – Video dictionary
overlays (List[Dict[str, Any]]) – List of overlay specifications, each with keys:
- overlay_video: Video to overlay
- position: (x, y) coordinates for placement
- start: Start time in seconds
- duration: Duration to display overlay
- opacity: Opacity of overlay
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
add_text(video, overlay)[source]
Add text overlay to video using FFmpeg drawtext filter.
- Parameters:
-
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
add_image(video, overlay)[source]
Add image overlay to video using FFmpeg.
- Parameters:
video (Dict[str, Any]) – Video dictionary
overlay (Any) – GraphicsOverlay object from operations.text
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
Subtitle operations for FFmpeg backend.
This module provides subtitle functionality for the FFmpeg backend.
-
class fmusvid.backends.ffmpeg.subtitle.FFmpegSubtitle[source]
FFmpeg subtitle operations.
-
add_subtitles(video, entries, font='Arial', size=24, color='white', position=None)[source]
Add subtitles from a list of entries.
- Parameters:
-
- Return type:
Dict
- Returns:
Updated video dictionary
-
add_subtitle_text(video, entry, font='Arial', size=24, color='white')[source]
Add a single subtitle entry.
- Parameters:
video (Dict) – Video dictionary
entry (SubtitleEntry) – SubtitleEntry object
font (str) – Font name or path
size (int) – Font size in pixels
color (Union[str, Tuple[int, int, int]]) – Text color (name or RGB tuple)
- Return type:
Dict
- Returns:
Updated video dictionary
FFmpeg audio operations.
This module provides implementation for audio-related operations.
-
class fmusvid.backends.ffmpeg.audio.FFmpegAudio[source]
FFmpeg audio operations implementation.
-
mute(video)[source]
Remove audio track from video.
- Parameters:
video (Dict[str, Any]) – Video dictionary
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
volume(video, level)[source]
Set audio volume level.
- Parameters:
video (Dict[str, Any]) – Video dictionary
level (float) – Volume level (1.0 = original, 0.5 = 50%, 2.0 = 200%)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary
-
add_audio(video, audio_path, start=0, volume=1.0)[source]
Add audio track to video.
- Parameters:
video (Dict[str, Any]) – Video dictionary
audio_path (Union[str, Path]) – Path to audio file
start (float) – Start time for the audio (seconds)
volume (float) – Volume level (1.0 = original)
- Return type:
Dict[str, Any]
- Returns:
New video dictionary