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.2.0.tar.gz (11.5 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.2.0-py3-none-any.whl (14.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: clipwright_loudness-0.2.0.tar.gz
  • Upload date:
  • Size: 11.5 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.2.0.tar.gz
Algorithm Hash digest
SHA256 ac7930ff0a035a7d5fa7f0a9f90470fbbb72c225f8e4fee5fe66d277214f93dc
MD5 c31f2c42d64059fdb1b8c0a694565d99
BLAKE2b-256 a0549af78c4f565b9e998e0a9c9a33f1ae3b611422cbbbb356aa9b217c0071c0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for clipwright_loudness-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 54f76cb453aee8c623bba870807c9abb4b178ae218132e0e533225cb59caa4aa
MD5 6d7204790196b4e3f7dd3ef2fe717570
BLAKE2b-256 d31c0215a797755c13e48263056d7ca01aa1854569d20c172d21e48706598ed1

See more details on using hashes here.

Provenance

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