clipwright-loudness

MCP tool for audio loudness normalization detection and OTIO timeline annotation generation.

Overview

Measures audio loudness and peak level using ffmpeg loudnorm / volumedetect filters, writes loudness instructions (mode, target, measured) to timeline-level metadata["clipwright"]["loudness"].

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

Normalization modes:

  • loudnorm (EBU R128 LUFS): Two-stage linear method. detect measures with loudnorm print_format=json and saves measured_* parameters to OTIO annotation; render applies exact one-pass with loudnorm:linear=true.
  • peak (max dB match): Measures max_volume with volumedetect and applies gain difference in render.

Initial render support:

  • track scope only (single loudness normalization applied to entire timeline).
  • per_clip scope (individual clip application) deferred until after compositing.

Prerequisites

  • Python 3.11 or later
  • ffmpeg / ffprobe must exist on PATH or full paths set in environment variables CLIPWRIGHT_FFMPEG / CLIPWRIGHT_FFPROBE.

Add ffmpeg to PATH directly or specify via environment variables:

export CLIPWRIGHT_FFMPEG=/path/to/ffmpeg
export CLIPWRIGHT_FFPROBE=/path/to/ffprobe

MCP Tool

clipwright_detect_loudness

Parameters

Name Type Default Description
media string required Input media file path (audio required)
output string required Output OTIO timeline path (.otio, same directory as media)
options.mode "loudnorm" | "peak" "loudnorm" Normalization mode
options.target_i float -14.0 loudnorm mode: target integrated loudness (LUFS, -70 to -5)
options.target_tp float -1.0 loudnorm mode: target true peak (dBTP, -9 to 0)
options.target_lra float 11.0 loudnorm mode: target loudness range (LU, 1 to 50)
options.target_peak_db float -1.0 peak mode: target peak level (dB, -60 to 0)
timeline string | null null Existing OTIO timeline path (if specified, append to it)

Dependencies

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

ffmpeg / ffprobe are invoked as separate processes (via PATH or environment variables) for license independence.

loudnorm Linear Two-Stage Method

  1. detect (this tool): ffmpeg -i <media> -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null - gets measured_* parameters and saves them to OTIO annotation.
  2. render (clipwright-render): loudnorm=I=-14:TP=-1:LRA=11:measured_I=..:...:linear=true executes only one-pass linear application with detected parameters (improved accuracy).

Installation and Startup

Within a uv workspace:

uv run --package clipwright-loudness clipwright-loudness

Or install directly:

uv add clipwright-loudness
clipwright-loudness

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_loudness-0.3.3.tar.gz (11.4 kB view details)

Uploaded Source

Built Distribution

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

clipwright_loudness-0.3.3-py3-none-any.whl (14.1 kB view details)

Uploaded Python 3

File details

Details for the file clipwright_loudness-0.3.3.tar.gz.

File metadata

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

File hashes

Hashes for clipwright_loudness-0.3.3.tar.gz
Algorithm Hash digest
SHA256 bbf67f687de135541c5a23f0ff030aaa69e6dd9cfd2e54893b6985123ab42ec1
MD5 d9d6946a850b0e7979ba1996a033c95d
BLAKE2b-256 7223085088aff1245dae2274c865a31928ef4dd45171638859673eee50f8331d

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_loudness-0.3.3.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_loudness-0.3.3-py3-none-any.whl.

File metadata

File hashes

Hashes for clipwright_loudness-0.3.3-py3-none-any.whl
Algorithm Hash digest
SHA256 8b64e95535eda5a5894604bb8ee4a4e078013d8efe69cb73f3aebf5833c040cd
MD5 607fa9c9311731daf4343bc0f497a6b0
BLAKE2b-256 d09a53a33aec2f70251a3b893f4142050bd0022b9528548fa5bfd8b22354605d

See more details on using hashes here.

Provenance

The following attestation bundles were made for clipwright_loudness-0.3.3-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