Metadata-Version: 2.4
Name: video-fx
Version: 0.1.0
Summary: 150 named video effects across 30 base engines — glitch, VHS, cinematic color, lens, particles, and stylization
Project-URL: Homepage, https://github.com/tomastimelock/video-fx
Project-URL: Issues, https://github.com/tomastimelock/video-fx/issues
Project-URL: Source, https://github.com/tomastimelock/video-fx
Author-email: Trollfabriken AITrix AB <dev@trollfabriken.se>
License: MIT License
        
        Copyright (c) 2026 Trollfabriken AITrix AB
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: color-grading,effects,ffmpeg,glitch,vfx,vhs,video
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.10
Requires-Dist: ffmpeg-python>=0.2
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless>=4.8
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.5
Requires-Dist: typer>=0.9
Provides-Extra: all
Requires-Dist: scikit-image>=0.22; extra == 'all'
Requires-Dist: web-overlay>=0.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: overlay
Requires-Dist: web-overlay>=0.1; extra == 'overlay'
Provides-Extra: scikit
Requires-Dist: scikit-image>=0.22; extra == 'scikit'
Description-Content-Type: text/markdown

# 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

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

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

```python
# 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**

```json
[
  {"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 <dev@trollfabriken.se>
GitHub: tomastimelock
PyPI:   opusmorale
```
