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:
Latest release

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.4.1.tar.gz (11.7 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.4.1-py3-none-any.whl (14.3 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for clipwright_loudness-0.4.1.tar.gz
Algorithm Hash digest
SHA256 769b151308911de29c1cff108ef5aeaa2d319571016b58e2ef4fd9db00b83f70
MD5 f897b0beee6f70cb9f85b56f1b3e10e8
BLAKE2b-256 8ed669149d3a94c03151b9752544f7a43da79101dbed04eb158f25a64c294f4c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for clipwright_loudness-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e9c875f09e0ef27aeb9a71ead426d575e84346a2d51b5541f7a4f876ccff4786
MD5 8f52bd57830cb6f60824fae96db89dac
BLAKE2b-256 c439c61c73e39160e5163525c4f366560685b17f1c7691fd2e5d5ec45c318de5

See more details on using hashes here.

Provenance

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