video-fx 0.1.0

150 named video effects across 30 base engines — glitch, VHS, cinematic color, lens, particles, and stylization

video-fx

150 named video effects through 30 base engines — glitch, VHS, cinematic color, lens, particles, and stylization.

What this is

video-fx is a Python library that applies named, parameterized video effects to video files. It exposes 150 effects across 6 categories through a single stable API. Effects operate frame-by-frame via OpenCV and NumPy; video I/O uses ffmpeg. Every effect accepts an intensity float (0.0–1.0) and an optional parameter dict. Effects can be applied individually or chained. The catalog ships as JSON inside the wheel so no network calls are needed at runtime.

Install

pip install video-fx

ffmpeg >= 6.0 must be on PATH. video-fx does not vendor ffmpeg.

Extras

Extra	Installs	Enables
[overlay]	web-overlay	HTML-rendered overlays via the overlay engine
[scikit]	scikit-image	Better paint and watercolor filters
[all]	both of the above	Full feature set

pip install "video-fx[scikit]"
pip install "video-fx[all]"

Quickstart

from video_fx import apply_effect, apply_effect_chain, list_effects, list_categories

# Apply a single effect at 60 % intensity
apply_effect("input.mp4", "output.mp4", effect="vhs_distortion", intensity=0.6)

# Apply a named effect with explicit parameters
apply_effect(
    "input.mp4",
    "output_teal.mp4",
    effect="teal_and_orange",
    intensity=0.8,
    params={"shadows_teal": 0.4, "highlights_orange": 0.6},
)

# Chain three effects in a single pass
apply_effect_chain(
    "input.mp4",
    "output_chain.mp4",
    effects=[
        {"effect": "film_grain", "intensity": 0.4},
        {"effect": "bleach_bypass", "intensity": 0.5},
        {"effect": "lens_flare", "intensity": 0.3},
    ],
)

# Inspect the catalog
names = list_effects()              # list of 150 slug strings
categories = list_categories()      # list of 6 category strings

The 150 effects

Effects are grouped into 6 categories. The slug is the string passed to apply_effect.

Glitch / Digital (25 effects)

Slug	Name
digital_glitch	Digital Glitch
rgb_split	RGB Split
chromatic_aberration	Chromatic Aberration
datamosh	Datamosh
pixel_sort	Pixel Sort
block_corruption	Block Corruption
signal_tear	Signal Tear
frame_drop	Frame Drop
freeze_glitch	Freeze Glitch
compression_artifacts	Compression Artifacts
bitcrush_video	Bitcrush Video
corrupt_scan	Corrupt Scan
broken_sync	Broken Sync
cyber_glitch_flash	Cyber Glitch Flash
matrix_code_overlay	Matrix Code Overlay
hud_interference	HUD Interference
noise_burst	Noise Burst
invert_flash	Invert Flash
edge_glitch	Edge Glitch
ghost_frame_glitch	Ghost Frame Glitch
datastream_overlay	Datastream Overlay
buffering_freeze	Buffering Freeze
broken_codec	Broken Codec
byte_rain	Byte Rain
color_channel_jitter	Color Channel Jitter

Base engines: slice_corrupt, channel_shift, noise_blast, decode_glitch, frame_drop

VHS / Analog (25 effects)

Slug	Name
vhs_distortion	VHS Distortion
vhs_tracking_lines	VHS Tracking Lines
tape_wrinkle	Tape Wrinkle
analog_color_bleed	Analog Color Bleed
crt_scanlines	CRT Scanlines
crt_curvature	CRT Curvature
crt_phosphor_glow	CRT Phosphor Glow
interlacing	Interlacing
analog_snow	Analog Snow
vhs_timecode	VHS Timecode
camcorder_overlay	Camcorder Overlay
tape_pause_jitter	Tape Pause Jitter
bad_tape_dropout	Bad Tape Dropout
analog_roll	Analog Roll
tv_power_off	TV Power Off
tv_power_on	TV Power On
vignetted_crt	Vignetted CRT
old_broadcast	Old Broadcast
pal_ntsc_shift	PAL/NTSC Shift
tape_rewind	Tape Rewind
tape_fast_forward	Tape Fast Forward
head_switching_noise	Head Switching Noise
luma_chroma_delay	Luma Chroma Delay
ghosting_echo	Ghosting Echo
archive_tape_damage	Archive Tape Damage

Base engines: scanlines, chroma_offset, crt_geometry, tape_artifacts, broadcast_degrade

Cinematic Color (25 effects)

Slug	Name
bleach_bypass	Bleach Bypass
teal_and_orange	Teal and Orange
film_emulation	Film Emulation
kodak_warm	Kodak Warm
fuji_cool	Fuji Cool
black_and_white	Black and White
high_contrast_noir	High Contrast Noir
dreamy_soft_focus	Dreamy Soft Focus
pastel_grade	Pastel Grade
vintage_fade	Vintage Fade
sepia	Sepia
cold_blue_grade	Cold Blue Grade
warm_sunset_grade	Warm Sunset Grade
horror_green_grade	Horror Green Grade
sci_fi_cyan_grade	Sci-Fi Cyan Grade
documentary_natural	Documentary Natural
news_broadcast_grade	News Broadcast Grade
music_video_hypercolor	Music Video Hypercolor
muted_nordic	Muted Nordic
apocalyptic_dust	Apocalyptic Dust
day_for_night	Day for Night
underexposed_thriller	Underexposed Thriller
overexposed_memory	Overexposed Memory
cross_process	Cross Process
retro_70s_grade	Retro 70s Grade

Base engines: curves, film_emulation, split_tone, lut_grade

Camera / Lens (25 effects)

Slug	Name
camera_shake	Camera Shake
handheld_drift	Handheld Drift
whip_pan_blur	Whip Pan Blur
zoom_blur	Zoom Blur
rack_focus	Rack Focus
lens_flare	Lens Flare
anamorphic_flare	Anamorphic Flare
bokeh_overlay	Bokeh Overlay
depth_of_field	Depth of Field
tilt_shift	Tilt Shift
fisheye_lens	Fisheye Lens
wide_angle_warp	Wide Angle Warp
lens_dirt	Lens Dirt
rain_on_lens	Rain on Lens
light_leak	Light Leak
film_gate_weave	Film Gate Weave
shutter_stutter	Shutter Stutter
rolling_shutter	Rolling Shutter
speed_ramp_blur	Speed Ramp Blur
cinematic_push_in	Cinematic Push In
crash_zoom	Crash Zoom
dolly_zoom	Dolly Zoom
subject_follow_shake	Subject Follow Shake
micro_jitter	Micro Jitter
optical_breathing	Optical Breathing

Base engines: shake, blur_directional, flare, focus_layer, distort_geometric

Light / Particles / Weather (25 effects)

Slug	Name
film_grain	Film Grain
dust_particles	Dust Particles
sparks	Sparks
embers	Embers
snow	Snow
rain	Rain
heavy_rain	Heavy Rain
fog	Fog
smoke	Smoke
fire_overlay	Fire Overlay
lightning_flash	Lightning Flash
god_rays	God Rays
haze	Haze
confetti	Confetti
bubbles	Bubbles
underwater_caustics	Underwater Caustics
heat_waves	Heat Waves
magic_particles	Magic Particles
lens_sparkles	Lens Sparkles
atmospheric_ash	Atmospheric Ash
sandstorm	Sandstorm
floating_pollen	Floating Pollen
laser_beams	Laser Beams
volumetric_smoke	Volumetric Smoke
fireflies	Fireflies

Base engines: particle_system, weather_streaks, fog_smoke, light_layer, noise_layer

Stylization / Artistic (25 effects)

Slug	Name
cartoon	Cartoon
anime_look	Anime Look
comic_book	Comic Book
halftone	Halftone
posterize	Posterize
oil_paint	Oil Paint
watercolor	Watercolor
pencil_sketch	Pencil Sketch
charcoal	Charcoal
blueprint	Blueprint
thermal_art	Thermal Art
duotone	Duotone
monochrome_tint	Monochrome Tint
neon_edge	Neon Edge
emboss	Emboss
mosaic	Mosaic
glass_mosaic	Glass Mosaic
prism	Prism
kaleidoscope	Kaleidoscope
mirror_symmetry	Mirror Symmetry
rotoscope_paint	Rotoscope Paint
line_art	Line Art
claymation_look	Claymation Look
stop_motion_look	Stop Motion Look
low_poly	Low Poly

Base engines: paint_filter, edge_stylize, halftone, posterize, mosaic, mirror

Summary

Category	Count	Base engines
Glitch / Digital	25	5
VHS / Analog	25	5
Cinematic Color	25	4
Camera / Lens	25	5
Light / Particles / Weather	25	5
Stylization / Artistic	25	6
Total	150	30

Composition with the Trollfabriken stack

video-fx is the effect layer in the Trollfabriken video pipeline. Downstream packages compose it directly:

• watch-cast applies surveillance and security-camera styles by calling video-fx effects as primitives
• overlay-cast layers social and broadcast graphics over video-fx-processed frames
• scene-fx drives temporal effects (speed ramps, beat sync) that invoke video-fx effects at keyframes

# Composing with watch-cast (installed separately)
from watch_cast import apply_surveillance_style

apply_surveillance_style("input.mp4", "output.mp4", style="cctv_color", intensity=0.9)
# Internally calls video_fx.apply_effect_chain with vhs + lens + color effects

# Driving video-fx from a beat-synced trigger (scene-fx)
from scene_fx import beat_sync_effect

beat_sync_effect(
    "input.mp4",
    "output.mp4",
    effect="rgb_split",
    bpm=128,
    intensity_on_beat=0.8,
    intensity_off_beat=0.1,
)

CLI

The video-fx command is installed with the package.

# List all 150 effect slugs
video-fx list

# List slugs filtered by category
video-fx list --category cinematic_color

# List the 6 categories
video-fx categories

# Show parameters and defaults for one effect
video-fx info teal_and_orange

# Apply a single effect
video-fx apply input.mp4 output.mp4 --effect vhs_distortion --intensity 0.7

# Apply a chain defined in a JSON file
video-fx render input.mp4 output.mp4 --chain chain.json

# Preview the first 5 seconds at low resolution (requires ffplay on PATH)
video-fx preview input.mp4 --effect film_grain --intensity 0.5 --duration 5

# Print the JSON schema for a named effect's parameter block
video-fx schema bleach_bypass

chain.json format

[
  {"effect": "film_grain",   "intensity": 0.35},
  {"effect": "teal_and_orange", "intensity": 0.7, "params": {"shadows_teal": 0.5}},
  {"effect": "lens_flare",   "intensity": 0.25}
]

Internal architecture

The library is structured around 30 base engine modules in src/video_fx/engines/, grouped by category subdirectory (glitch/, vhs/, color/, lens/, particles/, style/). Each engine module exposes a single apply(frame: np.ndarray, intensity: float, params: dict) -> np.ndarray function. The catalog loader (src/video_fx/catalog/loader.py) maps the 150 named effect slugs to their engine and parameter defaults via src/video_fx/data/effect_mapping.json. The public API in src/video_fx/api.py handles video decode, frame dispatch, and re-encode. Easing curves for intensity envelopes live in src/video_fx/easing/.

What this is not

• A video editor or timeline tool. video-fx applies effects to existing clips; it does not cut, trim, or arrange them. For arrangement, use video-arrange from the same family.
• A live-streaming pipeline. All processing is offline, reading from and writing to files.
• A speech-to-text or audio-analysis tool. video-fx does not analyze audio content. Beat-sync behavior is provided by scene-fx + audio-arrange.
• An AI or neural-network effects library. All 150 effects in v0.1 are deterministic signal-processing implementations. No model weights are downloaded at runtime.
• A replacement for DaVinci Resolve, FFmpeg filter chains, or After Effects. video-fx targets programmatic, pipeline-embedded usage where Python code generates effect parameters from external data.

Runtime requirements

• Python >= 3.10
• ffmpeg >= 6.0 on PATH (encode and decode)
• ffplay on PATH only if using video-fx preview

Provenance

Built at Trollfabriken AITrix AB for CineForge pipeline music-video and trailer work, AIMOS Insight municipal report stylization, SocKartan civic-transparency video segments, and the Timelock Film AB festival slate.

Author: Trollfabriken AITrix AB <[e-mail]>
GitHub: tomastimelock
PyPI:   opusmorale