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.4.0.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.0-py3-none-any.whl (14.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: clipwright_loudness-0.4.0.tar.gz
  • Upload date:
  • Size: 11.7 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.4.0.tar.gz
Algorithm Hash digest
SHA256 fe6711ff9e56f122bfe6b30439f15be9c800b63687994483c71de541446479ce
MD5 596609143ded88b0875915ba027ba1f2
BLAKE2b-256 662952e38c1f97e3539f4e01c640fd1129f7c2c9f324154d27971c823f8715e0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for clipwright_loudness-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 61e1e1f1083b4b7be4479cfe8479bb336a29f9833673a10894b073872cc4e30b
MD5 7c2fd2952422f0dd9399602cde4750b7
BLAKE2b-256 5f27825feea581f1fd444285835ea5ef24ecb363405f5bac7071426c26f825ac

See more details on using hashes here.

Provenance

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