clipwright-color

MCP tool for video brightness detection and OTIO timeline color annotation generation.

Overview

Measures average luma using the ffmpeg signalstats filter, writes a color correction directive (brightness offset, eq parameters) to timeline-level metadata["clipwright"]["color"].

Performs detection only (OTIO annotation); realization (eq filter application) is done once by clipwright-render (design M3: separation of detection and application).

Brightness derivation:

  • Samples frames at a configurable interval using fps=1/<interval> and signalstats=stat=brng.
  • Computes mean luma (YAVG) across sampled frames.
  • Derives brightness offset as clamp((target_luma - YAVG) / 255.0, -1.0, 1.0).
  • Contrast, saturation, and gamma are left at neutral defaults (1.0 / 1.0 / 1.0); only brightness is auto-derived from the measured luma.

Prerequisites

  • Python 3.11 or later
  • ffmpeg must exist on PATH or full path set in environment variable CLIPWRIGHT_FFMPEG.
export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
export CLIPWRIGHT_FFPROBE=/path/to/ffprobe

MCP Tool

clipwright_detect_color

Parameters

Name Type Default Description
media string required Input video file path (video stream required)
output string required Output OTIO timeline path (.otio, same directory as media)
options.target_luma float 128.0 Target average luma on the 0-255 scale (default: mid-grey)
options.sample_interval_sec float 1.0 Frame sampling interval in seconds (ffmpeg fps=1/interval, must be > 0)
timeline string | null null Existing OTIO timeline path (if specified, append color directive to it)

Return value

The tool returns a ToolResult envelope:

{
  "ok": true,
  "summary": "Color analysis complete. measured_luma=96.4 ...",
  "data": {
    "measured_luma": 96.4,
    "brightness": 0.123,
    "contrast": 1.0,
    "saturation": 1.0,
    "gamma": 1.0,
    "target_luma": 128.0,
    "sampled_frames": 12
  },
  "artifacts": [{"role": "timeline", "path": "out.otio", "format": "otio"}],
  "warnings": []
}

When measurement is not possible (measured=None, U-1), the color directive is not written but the timeline is still saved and a warning is returned.

Dependencies

Package Purpose
clipwright Shared types, envelope, errors, process.run
mcp[cli] MCP server
pydantic Parameter validation

ffmpeg is invoked as a separate process (via PATH or environment variable) for license independence.

Detection and Render Two-Phase Flow

  1. detect (this tool): ffmpeg -i <media> -vf "fps=1/1,signalstats=stat=brng,metadata=print" -f null - extracts per-frame YAVG and saves the derived eq directive to OTIO annotation.
  2. render (clipwright-render): reads metadata["clipwright"]["color"]["eq"] and applies eq=brightness=...:contrast=...:saturation=...:gamma=... in the ffmpeg filter graph.

Installation and Startup

Within a uv workspace:

uv run --package clipwright-color clipwright-color

Or install directly:

uv add clipwright-color
clipwright-color

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for satoh-y-0323 from gravatar.com satoh-y-0323

Credits

Author: satoh-y-0323

License

MIT

Requires

Python >=3.11

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clipwright_color-0.3.2.tar.gz (13.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

clipwright_color-0.3.2-py3-none-any.whl (16.6 kB view details)

Uploaded Python 3

File details

Details for the file clipwright_color-0.3.2.tar.gz.

File metadata

  • Download URL: clipwright_color-0.3.2.tar.gz
  • Upload date:
  • Size: 13.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for clipwright_color-0.3.2.tar.gz
Algorithm Hash digest
SHA256 c3901e8428070dd5bd8adfb9f53d3c8f666d8c7123e08a2c14fb28498c32b2d0
MD5 0261121d8682c3867da3b2c8b1846b62
BLAKE2b-256 c8179b4cb2b46000d66ea890e0d9c891636cee1aff0e8b3e8a19e0733125c437

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_color-0.3.2.tar.gz:

Publisher: publish.yml on satoh-y-0323/clipwright

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file clipwright_color-0.3.2-py3-none-any.whl.

File metadata

File hashes

Hashes for clipwright_color-0.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 aadb11c0b296da7c417b5b1d1d8d9c69e01b7e0b69185111470af1d194b2598b
MD5 385d3c1613e1d49e05b28befb4c3f83a
BLAKE2b-256 d22c67b839e888ff093948c27630d42eb61cc0a7e4b1d7214f043f1445b71897

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_color-0.3.2-py3-none-any.whl:

Publisher: publish.yml on satoh-y-0323/clipwright

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page