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.2.tar.gz (11.3 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.2-py3-none-any.whl (14.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: clipwright_loudness-0.3.2.tar.gz
  • Upload date:
  • Size: 11.3 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.2.tar.gz
Algorithm Hash digest
SHA256 0ec05e6a2205797baee6444d7309762e77fb9b783ea719787b8a0a6fc58e4ac6
MD5 d57c6258041e758fe725ce65650c2a75
BLAKE2b-256 6f7f3489a17d142163fa67ada4d6c4d29958039f280c1fcd9f124528cd807cf4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for clipwright_loudness-0.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 58f4c182291ac509b54cdb8fe9c73e4615be9be83287e12d0d12d09d8a8de024
MD5 6f2519f111334fd4703dca60831c80be
BLAKE2b-256 f4c8da0cdfaf93a58c2cf5b5f98c0af63bb14c27d9341159fe90bc4bc92a27e7

See more details on using hashes here.

Provenance

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