Core Module 

Example

>>> video.save("output.mp4")
>>> video.save("output.mp4", codec="h264", bitrate="5M")

async save_async(path, progress_callback=None, **kwargs)[source]

Save video asynchronously.

Parameters:

path (Union[str, Path]) – Output file path
progress_callback (Optional[Callable[[float], None]]) – Function to call with progress (0-1)
**kwargs – Export options (codec, bitrate, etc.)

Return type:

Example

>>> await video.save_async("output.mp4",
...                       progress_callback=lambda p: print(f"{p*100:.1f}%"))

info()[source]

Get video information.

Return type:: VideoInfo
Returns:: VideoInfo object

Example

>>> info = video.info()
>>> print(f"Resolution: {info.width}x{info.height}")

get_info()[source]

Get video information as a dictionary. For CLI compatibility.

Return type:: Dict[str, Any]
Returns:: Dictionary of video information

Example

>>> info_dict = video.get_info()
>>> print(f"Resolution: {info_dict['width']}x{info_dict['height']}")

property duration: float: Get video duration in seconds.

property width: int: Get video width in pixels.

property height: int: Get video height in pixels.

property fps: float: Get video frame rate.

property bitrate: str | None: Get video bitrate.

property has_audio: bool: Check if video has audio track.

trim(start, end=None)[source]

Trim video to specified time range.

Parameters:

start (float) – Start time in seconds
end (Optional[float]) – End time in seconds (None means until the end)

Return type:

Returns:

Self for method chaining

Example

>>> video.trim(10, 20)  # Keep only seconds 10-20

resize(width=None, height=None, keep_aspect=True)[source]

Resize video to specified dimensions.

Parameters:

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:

Returns:

Self for method chaining

Example

>>> video.resize(720)  # Resize to 720p (height auto-calculated)
>>> video.resize(width=1280, height=720)  # Resize to 720p

crop(x, y, width, height)[source]

Crop video to specified region.

Parameters:

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:

Returns:

Self for method chaining

Example

>>> video.crop(100, 100, 500, 300)  # Crop to 500x300 region

rotate(degrees)[source]

Rotate video by specified degrees.

Parameters:: degrees (float) – Rotation angle in degrees
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.rotate(90)  # Rotate 90 degrees clockwise

grayscale()[source]

Convert video to grayscale.

Return type:: Video
Returns:: Self for method chaining

Example

>>> video.grayscale()  # Convert to black and white

blur(radius)[source]

Apply Gaussian blur with specified radius.

Parameters:: radius (float) – Blur radius
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.blur(5)  # Apply blur with radius 5

brightness(factor)[source]

Adjust video brightness.

Parameters:: factor (float) – Brightness factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.brightness(1.2)  # Increase brightness by 20%

contrast(factor)[source]

Adjust video contrast.

Parameters:: factor (float) – Contrast factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.contrast(1.2)  # Increase contrast by 20%

mute()[source]

Remove audio track.

Return type:: Video
Returns:: Self for method chaining

Example

>>> video.mute()  # Remove audio

volume(level)[source]

Set audio volume.

Parameters:: level (float) – Volume level (1.0 = original, 0.5 = 50%, 2.0 = 200%)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.volume(0.8)  # Reduce volume to 80%

add_audio(audio_path, start=0, volume=1.0)[source]

Add audio track to the video.

Parameters:

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:

Returns:

Self for method chaining

Example

>>> video.add_audio("music.mp3", start=5, volume=0.8)

add_subtitles(subtitle_path, font='Arial', size=24, color='white', position=None)[source]

Add subtitles to the video.

Parameters:

subtitle_path (Union[str, Path]) – Path to subtitle file (.srt or .vtt)
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)
position (Optional[Tuple[int, int]]) – Optional (x, y) position (None for bottom center)

Return type:

Returns:

Self for method chaining

Example

>>> video.add_subtitles("subtitles.srt")
>>> video.add_subtitles("subtitles.vtt", font="DejaVuSans.ttf", size=32)

add_subtitle_text(text, start_time, end_time, font='Arial', size=24, color='white', position=None)[source]

Add a single subtitle entry directly to the video.

Parameters:

text (str) – Subtitle text
start_time (float) – Start time in seconds
end_time (float) – End time in seconds
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)
position (Optional[Tuple[int, int]]) – Optional (x, y) position (None for bottom center)

Return type:

Returns:

Self for method chaining

Example

>>> video.add_subtitle_text("Hello world", 5.0, 10.0)

extract_frame(time)[source]

Extract a single frame at specified time.

Parameters:: time (float) – Time in seconds
Returns:: Frame object

Example

>>> frame = video.extract_frame(10.5)
>>> frame.save("thumbnail.jpg")

get_frame(time)[source]

Extract a single frame at specified time (alias for extract_frame).

Parameters:: time (float) – Time in seconds
Returns:: Frame object (numpy array)

Example

>>> frame = video.get_frame(1.0)
>>> frame.shape  # (height, width, channels)

sharpen(amount=1.5)[source]

Sharpen video (not yet implemented).

Parameters:: amount (float) – Sharpening amount
Return type:: Video
Returns:: Self for method chaining

denoise(strength=0.5)[source]

Denoise video (not yet implemented).

Parameters:: strength (float) – Denoising strength
Return type:: Video
Returns:: Self for method chaining

animate(prop, start, end, duration)[source]

Animate a property (not yet implemented).

Parameters:

prop (str) – Property to animate
start (float) – Start value
end (float) – End value
duration (float) – Animation duration

Return type:

Returns:

Self for method chaining

overlay(video, position=(0, 0), start=0, duration=None, opacity=1.0)[source]

Overlay another video (picture-in-picture).

Parameters:

video (Video) – 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:

Returns:

Self for method chaining

Example

>>> main_video.overlay(pip_video, position=(50, 50), opacity=0.8)

classmethod create(width, height, duration, fps=30, color=(0, 0, 0), backend='auto', **kwargs)[source]

Create a blank video canvas.

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
backend (Union[str, Backend]) – Backend to use
**kwargs – Additional options

Return type:

Returns:

Video object

Example

>>> canvas = Video.create(1920, 1080, 10)  # 10 second blank video

classmethod concat(videos, backend='auto', **kwargs)[source]

Concatenate multiple videos.

Parameters:

videos (List[Video]) – List of Video objects
backend (Union[str, Backend]) – Backend to use
**kwargs – Additional options

Return type:

Returns:

New concatenated Video object

Example

>>> combined = Video.concat([video1, video2, video3])

classmethod grid(videos, rows, cols, backend='auto', **kwargs)[source]

Arrange videos in a grid layout.

Parameters:

videos (List[Video]) – List of Video objects
rows (int) – Number of rows
cols (int) – Number of columns
backend (Union[str, Backend]) – Backend to use
**kwargs – Additional options

Return type:

Returns:

New grid Video object

Example

>>> grid_video = Video.grid([video1, video2, video3, video4], rows=2, cols=2)

speed(factor)[source]

Change video playback speed.

Parameters:: factor (float) – Speed factor (2.0 = 2x faster, 0.5 = half speed)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.speed(2.0)  # 2x speed

saturation(factor)[source]

Adjust video saturation.

Parameters:: factor (float) – Saturation factor (1.0 = original, 1.5 = +50%, 0.5 = -50%, 0 = grayscale)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.saturation(1.5)  # Increase saturation

fade_in(duration)[source]

Fade video in from black.

Parameters:: duration (float) – Fade duration in seconds
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.fade_in(1.0)  # 1 second fade in

fade_out(duration)[source]

Fade video out to black.

Parameters:: duration (float) – Fade duration in seconds
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.fade_out(1.0)  # 1 second fade out

reverse()[source]

Reverse video playback.

Return type:: Video
Returns:: Self for method chaining

Example

>>> video.reverse()

chroma_key(color, similarity=0.1, blend=0.0)[source]

Remove green screen / chroma key.

Parameters:

color (Tuple[int, int, int]) – RGB color to key out (e.g., (0, 255, 0) for green screen)
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:

Returns:

Self for method chaining

Example

>>> video.chroma_key((0, 255, 0))  # Remove green screen

crossfade(other_video, duration)[source]

Crossfade between this video and another.

Parameters:

other_video (Video) – Video to crossfade to
duration (float) – Crossfade duration in seconds

Return type:

Returns:

Self for method chaining

Example

>>> video1.crossfade(video2, 1.0)

fade_audio_in(duration)[source]

Fade audio in.

Parameters:: duration (float) – Fade duration in seconds
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.fade_audio_in(1.0)

fade_audio_out(duration)[source]

Fade audio out.

Parameters:: duration (float) – Fade duration in seconds
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.fade_audio_out(1.0)

normalize_audio(target_db=-16.0)[source]

Normalize audio to target dB level.

Parameters:: target_db (float) – Target loudness in dB (typically -16 to -20)
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.normalize_audio(-16.0)

replace_audio(audio_path)[source]

Replace audio track with new audio.

Parameters:: audio_path (Union[str, Path]) – Path to new audio file
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.replace_audio("new_audio.mp3")

to_gif(path, fps=None, quality=95, loop=0, width=None)[source]

Export video as animated GIF.

Parameters:

path (Union[str, Path]) – Output GIF path
fps (Optional[float]) – Frame rate for GIF (None = use original, capped at 15)
quality (int) – Quality (1-100, higher = better)
loop (int) – Loop count (0 = infinite)
width (Optional[int]) – Resize width (None = keep original)

Return type:

Example

>>> video.to_gif("output.gif", fps=10, width=320)

to_image_sequence(output_dir, prefix='frame_', format='png', start=None, end=None, fps=None)[source]

Export video frames as images.

Parameters:

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

Example

>>> frames = video.to_image_sequence("frames/", prefix="img_", format="jpg")

add_text(text, position='center', font='Arial', size=32, color='white', duration=None, start_time=0)[source]

Add text overlay to the video.

Parameters:

text (str) – Text to display
position (Union[Tuple[int, int], str]) – Position as (x, y) tuple or preset (“center”, “top”, “bottom”, etc.)
font (str) – Font name or path to font file
size (int) – Font size in pixels
color (Union[str, Tuple[int, int, int]]) – Text color (name or RGB tuple)
duration (Optional[float]) – Duration to display text (None = entire video)
start_time (float) – When to start displaying text

Return type:

Returns:

Self for method chaining

Example

>>> video.add_text("Hello World", position="center", size=48)

add_image(image_path, position=(0, 0), opacity=1.0, scale=1.0, duration=None, start_time=0)[source]

Add image overlay to the video.

Parameters:

image_path (Union[str, Path]) – Path to image file
position (Tuple[int, int]) – (x, y) coordinates for placement
opacity (float) – Opacity of overlay (0.0 to 1.0)
scale (float) – Scale factor for image
duration (Optional[float]) – Duration to display image (None = entire video)
start_time (float) – When to start displaying image

Return type:

Returns:

Self for method chaining

Example

>>> video.add_image("logo.png", position=(10, 10), opacity=0.8)

apply_filter(filter_string)[source]

Apply custom FFmpeg filter string.

Parameters:: filter_string (str) – FFmpeg filter string
Return type:: Video
Returns:: Self for method chaining

Example

>>> video.apply_filter("negate")  # Invert colors

detect_scenes(threshold=30.0, min_scene_length=15)[source]

Detect scene changes in the video.

Parameters:

threshold (float) – Difference threshold for scene detection
min_scene_length (int) – Minimum frames between scene changes

Return type:

List[Any]

Returns:

List of scene change objects

Example

>>> scenes = video.detect_scenes()

analyze_audio()[source]

Analyze audio content of the video.

Return type:: Any
Returns:: Audio analysis results

Example

>>> analysis = video.analyze_audio()

stream_to(rtmp_url, **kwargs)[source]

Stream video to RTMP server.

Parameters:

rtmp_url (str) – RTMP stream URL
**kwargs – Additional streaming options

Return type:

Example

>>> video.stream_to("rtmp://live.example.com/stream/key")

__repr__()[source]

String representation of the Video object.

Return type:: str

class fmusvid.core.frame.Frame(frame_data, backend)[source]

Bases: object

Class for handling individual video frames.

This class provides methods for manipulating and saving frames.

__init__(frame_data, backend)[source]

Initialize a Frame object.

Parameters:

frame_data (Any) – Backend-specific frame data
backend (Any) – Backend instance

save(path, **kwargs)[source]

Save frame to file.

Parameters:

path (Union[str, Path]) – Output file path
**kwargs – Save options

Return type:

Example

>>> frame.save("thumbnail.jpg", quality=95)

resize(width=None, height=None, keep_aspect=True)[source]

Resize frame to specified dimensions.

Parameters:

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:

Returns:

New Frame object

Example

>>> thumbnail = frame.resize(width=320)

crop(x, y, width, height)[source]

Crop frame to specified region.

Parameters:

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:

Returns:

New Frame object

Example

>>> cropped = frame.crop(100, 100, 400, 300)

grayscale()[source]

Convert frame to grayscale.

Return type:: Frame
Returns:: New Frame object

Example

>>> bw = frame.grayscale()

blur(radius)[source]

Apply Gaussian blur with specified radius.

Parameters:: radius (float) – Blur radius
Return type:: Frame
Returns:: New Frame object

Example

>>> blurred = frame.blur(5)

brightness(factor)[source]

Adjust frame brightness.

Parameters:: factor (float) – Brightness factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
Return type:: Frame
Returns:: New Frame object

Example

>>> brighter = frame.brightness(1.2)

contrast(factor)[source]

Adjust frame contrast.

Parameters:: factor (float) – Contrast factor (1.0 = original, 1.5 = +50%, 0.5 = -50%)
Return type:: Frame
Returns:: New Frame object

Example

>>> higher_contrast = frame.contrast(1.2)

overlay(image, position=(0, 0), opacity=1.0)[source]

Overlay an image on the frame.

Parameters:

image – Image to overlay (Frame or PIL Image)
position (Tuple[int, int]) – (x, y) coordinates for placement
opacity (float) – Opacity of overlay (1.0 = fully opaque)

Return type:

Returns:

New Frame object

Example

>>> with_logo = frame.overlay(logo, position=(20, 20), opacity=0.8)

add_text(text, position, font='Arial', size=24, color='white')[source]

Add text to the frame.

Parameters:

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:

Returns:

New Frame object

Example

>>> with_caption = frame.add_text("Hello World", position=(50, 50), size=32)

to_pil()[source]

Convert frame to PIL Image.

Returns:: PIL Image object

Example

>>> pil_image = frame.to_pil()
>>> pil_image.show()

to_numpy()[source]

Convert frame to NumPy array.

Returns:: NumPy array (height, width, channels)

Example

>>> import numpy as np
>>> array = frame.to_numpy()
>>> print(f"Shape: {array.shape}")

__repr__()[source]

String representation of the Frame object.

Return type:: str

class fmusvid.core.audio.Audio(audio_data, backend)[source]

Bases: object

Class for handling audio operations.

This class provides methods for manipulating audio.

__init__(audio_data, backend)[source]

Initialize an Audio object.

Parameters:

audio_data (Any) – Backend-specific audio data
backend (Any) – Backend instance

save(path, **kwargs)[source]

Save audio to file.

Parameters:

path (Union[str, Path]) – Output file path
**kwargs – Save options - codec: Audio codec (e.g., “mp3”, “aac”) - bitrate: Audio bitrate (e.g., “192k”)

Return type: