# pyloudnorm [](https://travis-ci.org/csteinmetz1/pyloudnorm) 
Flexible audio loudness meter in Python.
Implementation 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). <br/>
Allows control over gating block size and frequency weighting filters for additional control.
For 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).
## Installation
You can install with pip as follows
```
pip install pyloudnorm
```
For the latest releases always install from the GitHub repo
```
pip install git+https://github.com/csteinmetz1/pyloudnorm
```
## Usage
### Find the loudness of an audio file
It's easy to measure the loudness of a wav file.
Here we use PySoundFile to read a .wav file as an ndarray.
```python
import soundfile as sf
import pyloudnorm as pyln
data, rate = sf.read("test.wav") # load audio (with shape (samples, channels))
meter = pyln.Meter(rate) # create BS.1770 meter
loudness = meter.integrated_loudness(data) # measure loudness
```
### Loudness normalize and peak normalize audio files
Methods are included to normalize audio files to desired peak values or desired loudness.
```python
import soundfile as sf
import pyloudnorm as pyln
data, rate = sf.read("test.wav") # load audio
# peak normalize audio to -1 dB
peak_normalized_audio = pyln.normalize.peak(data, -1.0)
# measure the loudness first
meter = pyln.Meter(rate) # create BS.1770 meter
loudness = meter.integrated_loudness(data)
# loudness normalize audio to -12 dB LUFS
loudness_normalized_audio = pyln.normalize.loudness(data, loudness, -12.0)
```
### Advanced operation
A number of alternate weighting filters are available, as well as the ability to adjust the analysis block size.
Examples are shown below.
```python
import soundfile as sf
import pyloudnorm as pyln
from pyloudnorm import IIRfilter
data, rate = sf.read("test.wav") # load audio
# block size
meter1 = pyln.Meter(rate) # 400ms block size
meter2 = pyln.Meter(rate, block_size=0.200) # 200ms block size
# filter classes
meter3 = pyln.Meter(rate) # BS.1770 meter
meter4 = pyln.Meter(rate, filter_class="DeMan") # fully compliant filters
meter5 = pyln.Meter(rate, filter_class="Fenton/Lee 1") # low complexity improvement by Fenton and Lee
meter6 = pyln.Meter(rate, filter_class="Fenton/Lee 2") # higher complexity improvement by Fenton and Lee
meter7 = pyln.Meter(rate, filter_class="Dash et al.") # early modification option
# create your own IIR filters
my_high_pass = IIRfilter(0.0, 0.5, 20.0, rate, 'high_pass')
my_high_shelf = IIRfilter(2.0, 0.7, 1525.0, rate, 'high_shelf')
# create a meter initialized without filters
meter8 = pyln.Meter(rate, filter_class="custom")
# load your filters into the meter
meter8._filters = {'my_high_pass' : my_high_pass, 'my_high_shelf' : my_high_shelf}
```
## Dependancies
- **SciPy** ([https://www.scipy.org/](https://www.scipy.org/))
- **NumPy** ([http://www.numpy.org/](http://www.numpy.org/))
## Citation
If you use pyloudnorm in your work please consider citing us.
```
@inproceedings{steinmetz2021pyloudnorm,
title={pyloudnorm: {A} simple yet flexible loudness meter in Python},
author={Steinmetz, Christian J. and Reiss, Joshua D.},
booktitle={150th AES Convention},
year={2021}}
```
## References
> Ian Dash, Luis Miranda, and Densil Cabrera, "[Multichannel Loudness Listening Test](http://www.aes.org/e-lib/browse.cfm?elib=14581),"
> 124th International Convention of the Audio Engineering Society, May 2008
> 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),"
> 133rd International Convention of the Audio Engineering Society, October 2012
> 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),"
> 134th International Convention of the Audio Engineering Society, May 2013
> Steven Fenton and Hyunkook Lee, "[Alternative Weighting Filters for Multi-Track Program Loudness Measurement](http://www.aes.org/e-lib/browse.cfm?elib=19215),"
> 143rd International Convention of the Audio Engineering Society, October 2017
> Brecht De Man, "[Evaluation of Implementations of the EBU R128 Loudness Measurement](http://www.aes.org/e-lib/browse.cfm?elib=19790),"
> 145th International Convention of the Audio Engineering Society, October 2018.
Raw data
{
"_id": null,
"home_page": "https://github.com/csteinmetz1/pyloudnorm",
"name": "pyloudnorm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": "",
"keywords": "",
"author": "Christian Steinmetz",
"author_email": "c.j.steinmetz@qmul.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/75/b5/39d59c44ecd828fabfdbd796b50a561e6543ca90ef440ab307374f107856/pyloudnorm-0.1.1.tar.gz",
"platform": null,
"description": "\n# pyloudnorm [](https://travis-ci.org/csteinmetz1/pyloudnorm) \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). <br/>\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## Dependancies\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> Ian Dash, Luis Miranda, and Densil Cabrera, \"[Multichannel Loudness Listening Test](http://www.aes.org/e-lib/browse.cfm?elib=14581),\"\n> 124th International Convention of the Audio Engineering Society, May 2008\n\n> Pedro D. Pestana and \u00c1lvaro Barbosa, \"[Accuracy of ITU-R BS.1770 Algorithm in Evaluating Multitrack Material](http://www.aes.org/e-lib/online/browse.cfm?elib=16608),\"\n> 133rd International Convention of the Audio Engineering Society, October 2012\n\n> Pedro D. Pestana, Josh D. Reiss, and \u00c1lvaro 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> 134th International Convention of the Audio Engineering Society, May 2013\n\n> 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> 143rd International Convention of the Audio Engineering Society, October 2017\n\n> Brecht De Man, \"[Evaluation of Implementations of the EBU R128 Loudness Measurement](http://www.aes.org/e-lib/browse.cfm?elib=19790),\" \n> 145th International Convention of the Audio Engineering Society, October 2018. \n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Implementation of ITU-R BS.1770-4 loudness algorithm in Python.",
"version": "0.1.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "58f56724805521ab4e723a12182f92374031032aff28a8a89dc8505c52b79032",
"md5": "73e01dbee7c21f779f9c03cae4944e56",
"sha256": "d7f12ebdd097a464d87ce2878fc4d942f15f8233e26cc03f33fefa226f869a14"
},
"downloads": -1,
"filename": "pyloudnorm-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73e01dbee7c21f779f9c03cae4944e56",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 9636,
"upload_time": "2023-01-05T16:11:27",
"upload_time_iso_8601": "2023-01-05T16:11:27.331503Z",
"url": "https://files.pythonhosted.org/packages/58/f5/6724805521ab4e723a12182f92374031032aff28a8a89dc8505c52b79032/pyloudnorm-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75b539d59c44ecd828fabfdbd796b50a561e6543ca90ef440ab307374f107856",
"md5": "e320557e8a4fb72fca22f3d3f18b9c2d",
"sha256": "63cd4e197dea4e7795160ea08ed02d318091bce883e436a6dbc5963326b71e1e"
},
"downloads": -1,
"filename": "pyloudnorm-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e320557e8a4fb72fca22f3d3f18b9c2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 8588,
"upload_time": "2023-01-05T16:11:28",
"upload_time_iso_8601": "2023-01-05T16:11:28.601387Z",
"url": "https://files.pythonhosted.org/packages/75/b5/39d59c44ecd828fabfdbd796b50a561e6543ca90ef440ab307374f107856/pyloudnorm-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-05 16:11:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "csteinmetz1",
"github_project": "pyloudnorm",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyloudnorm"
}
JSON
