{"id":22280246,"url":"https://github.com/csteinmetz1/pyloudnorm","last_synced_at":"2025-05-15T11:05:04.791Z","repository":{"id":45623997,"uuid":"110436854","full_name":"csteinmetz1/pyloudnorm","owner":"csteinmetz1","description":"Flexible audio loudness meter in Python with implementation of ITU-R BS.1770-4 loudness algorithm","archived":false,"fork":false,"pushed_at":"2024-01-26T17:29:26.000Z","size":49383,"stargazers_count":581,"open_issues_count":16,"forks_count":53,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-27T20:45:02.318Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.christiansteinmetz.com/projects-blog/pyloudnorm","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csteinmetz1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-12T13:56:23.000Z","updated_at":"2024-06-18T13:58:30.996Z","dependencies_parsed_at":"2024-06-18T14:08:36.895Z","dependency_job_id":null,"html_url":"https://github.com/csteinmetz1/pyloudnorm","commit_stats":{"total_commits":92,"total_committers":7,"mean_commits":"13.142857142857142","dds":0.08695652173913049,"last_synced_commit":"1fb914693e07f4bea06fdb2e4bd2d6ddc1688a9e"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csteinmetz1%2Fpyloudnorm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csteinmetz1%2Fpyloudnorm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csteinmetz1%2Fpyloudnorm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csteinmetz1%2Fpyloudnorm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csteinmetz1","download_url":"https://codeload.github.com/csteinmetz1/pyloudnorm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248167054,"owners_count":21058530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T15:27:04.581Z","updated_at":"2025-04-10T06:25:20.103Z","avatar_url":"https://github.com/csteinmetz1.png","language":"Python","funding_links":[],"categories":["DSP, Transforms \u0026 Spectral Analysis","Media Tools"],"sub_categories":["IO router / deconstructed loops anchor","Audio \u0026 Subtitles"],"readme":"# pyloudnorm  [![Build Status](https://travis-ci.org/csteinmetz1/pyloudnorm.svg?branch=master)](https://travis-ci.org/csteinmetz1/pyloudnorm) ![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.3551801.svg)\nFlexible audio loudness meter in Python. \n\nImplementation of [ITU-R BS.1770-4](https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.1770-4-201510-I!!PDF-E.pdf). \u003cbr/\u003e\nAllows control over gating block size and frequency weighting filters for additional control. \n\nFor full details on the implementation see our [paper](https://csteinmetz1.github.io/pyloudnorm-eval/paper/pyloudnorm_preprint.pdf) with a summary in our [AES presentation video](https://www.youtube.com/watch?v=krSJpQ3d4gE).\n\n## Installation\nYou can install with pip as follows\n```\npip install pyloudnorm\n```\n\nFor the latest releases always install from the GitHub repo\n```\npip install git+https://github.com/csteinmetz1/pyloudnorm\n```\n## Usage\n\n### Find the loudness of an audio file\nIt's easy to measure the loudness of a wav file. \nHere we use PySoundFile to read a .wav file as an ndarray.\n```python\nimport soundfile as sf\nimport pyloudnorm as pyln\n\ndata, rate = sf.read(\"test.wav\") # load audio (with shape (samples, channels))\nmeter = pyln.Meter(rate) # create BS.1770 meter\nloudness = meter.integrated_loudness(data) # measure loudness\n```\n\n### Loudness normalize and peak normalize audio files\nMethods are included to normalize audio files to desired peak values or desired loudness.\n```python\nimport soundfile as sf\nimport pyloudnorm as pyln\n\ndata, rate = sf.read(\"test.wav\") # load audio\n\n# peak normalize audio to -1 dB\npeak_normalized_audio = pyln.normalize.peak(data, -1.0)\n\n# measure the loudness first \nmeter = pyln.Meter(rate) # create BS.1770 meter\nloudness = meter.integrated_loudness(data)\n\n# loudness normalize audio to -12 dB LUFS\nloudness_normalized_audio = pyln.normalize.loudness(data, loudness, -12.0)\n```\n\n### Advanced operation\nA number of alternate weighting filters are available, as well as the ability to adjust the analysis block size. \nExamples are shown below.\n```python\nimport soundfile as sf\nimport pyloudnorm as pyln\nfrom pyloudnorm import IIRfilter\n\ndata, rate = sf.read(\"test.wav\") # load audio\n\n# block size\nmeter1 = pyln.Meter(rate)                               # 400ms block size\nmeter2 = pyln.Meter(rate, block_size=0.200)             # 200ms block size\n\n# filter classes\nmeter3 = pyln.Meter(rate)                               # BS.1770 meter\nmeter4 = pyln.Meter(rate, filter_class=\"DeMan\")         # fully compliant filters  \nmeter5 = pyln.Meter(rate, filter_class=\"Fenton/Lee 1\")  # low complexity improvement by Fenton and Lee\nmeter6 = pyln.Meter(rate, filter_class=\"Fenton/Lee 2\")  # higher complexity improvement by Fenton and Lee\nmeter7 = pyln.Meter(rate, filter_class=\"Dash et al.\")   # early modification option\n\n# create your own IIR filters\nmy_high_pass  = IIRfilter(0.0, 0.5, 20.0, rate, 'high_pass')\nmy_high_shelf = IIRfilter(2.0, 0.7, 1525.0, rate, 'high_shelf')\n\n# create a meter initialized without filters\nmeter8 = pyln.Meter(rate, filter_class=\"custom\")\n\n# load your filters into the meter\nmeter8._filters = {'my_high_pass' : my_high_pass, 'my_high_shelf' : my_high_shelf}\n\n```\n\n## Dependencies\n- **SciPy** ([https://www.scipy.org/](https://www.scipy.org/))\n- **NumPy** ([http://www.numpy.org/](http://www.numpy.org/))\n\n\n## Citation\nIf you use pyloudnorm in your work please consider citing us.\n```\n@inproceedings{steinmetz2021pyloudnorm,\n        title={pyloudnorm: {A} simple yet flexible loudness meter in Python},\n        author={Steinmetz, Christian J. and Reiss, Joshua D.},\n        booktitle={150th AES Convention},\n        year={2021}}\n```\n\n## References\n\n\u003e Ian Dash, Luis Miranda, and Densil Cabrera, \"[Multichannel Loudness Listening Test](http://www.aes.org/e-lib/browse.cfm?elib=14581),\"\n\u003e 124th International Convention of the Audio Engineering Society, May 2008\n\n\u003e Pedro D. Pestana and Álvaro Barbosa, \"[Accuracy of ITU-R BS.1770 Algorithm in Evaluating Multitrack Material](http://www.aes.org/e-lib/online/browse.cfm?elib=16608),\"\n\u003e 133rd International Convention of the Audio Engineering Society, October 2012\n\n\u003e Pedro D. Pestana, Josh D. Reiss, and Álvaro Barbosa, \"[Loudness Measurement of Multitrack Audio Content Using Modifications of ITU-R BS.1770](http://www.aes.org/e-lib/browse.cfm?elib=16714),\"\n\u003e 134th International Convention of the Audio Engineering Society, May 2013\n\n\u003e Steven Fenton and Hyunkook Lee, \"[Alternative Weighting Filters for Multi-Track Program Loudness Measurement](http://www.aes.org/e-lib/browse.cfm?elib=19215),\"\n\u003e 143rd International Convention of the Audio Engineering Society, October 2017\n\n\u003e Brecht De Man, \"[Evaluation of Implementations of the EBU R128 Loudness Measurement](http://www.aes.org/e-lib/browse.cfm?elib=19790),\" \n\u003e 145th International Convention of the Audio Engineering Society, October 2018. \n\n## Tensorized/Differentiable Implementations\n\nFor use in differentiable contexts, such as part of a loss function, there are the following implementations:\n- PyTorch: [Descript Inc.'s `audiotools`](https://github.com/descriptinc/audiotools/blob/master/audiotools/core/loudness.py)\n- Jax: [jaxloudnorm](https://github.com/boris-kuz/jaxloudnorm)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsteinmetz1%2Fpyloudnorm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsteinmetz1%2Fpyloudnorm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsteinmetz1%2Fpyloudnorm/lists"}