{"id":21061384,"url":"https://github.com/chaudum/rgain3","last_synced_at":"2025-05-16T00:34:24.561Z","repository":{"id":44817535,"uuid":"196331607","full_name":"chaudum/rgain3","owner":"chaudum","description":"A Python 3 compatible fork of rgain -- ReplayGain tools and Python library","archived":false,"fork":false,"pushed_at":"2023-07-21T06:20:04.000Z","size":281,"stargazers_count":55,"open_issues_count":17,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-13T14:21:26.899Z","etag":null,"topics":["analysis","audio","multimedia","replaygain"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chaudum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-11T06:18:15.000Z","updated_at":"2025-05-10T21:46:03.000Z","dependencies_parsed_at":"2023-02-10T21:00:28.216Z","dependency_job_id":null,"html_url":"https://github.com/chaudum/rgain3","commit_stats":null,"previous_names":["chaudum/rgain"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaudum%2Frgain3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaudum%2Frgain3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaudum%2Frgain3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaudum%2Frgain3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chaudum","download_url":"https://codeload.github.com/chaudum/rgain3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448056,"owners_count":22072755,"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":["analysis","audio","multimedia","replaygain"],"created_at":"2024-11-19T17:24:15.776Z","updated_at":"2025-05-16T00:34:20.584Z","avatar_url":"https://github.com/chaudum.png","language":"Python","funding_links":[],"categories":["Multimedia content processing"],"sub_categories":[],"readme":"# 🎚️ rgain3\n\n## ReplayGain tools and Python library\n\nThis Python package provides APIs to read, calculate and write ReplayGain using\nPython as well as two scripts that utilize these APIs to apply ReplayGain\ninformation on audio files.\n\n_This is a Python 3 fork of Felix Krull's `rgain` repository on Bitbucket._\n\n## What is ReplayGain?\n\n\u003e ReplayGain is a proposed standard published by David Robinson in 2001 to measure and normalize the perceived loudness of audio in computer audio formats such as MP3 and Ogg Vorbis. It allows media players to normalize loudness for individual tracks or albums. This avoids the common problem of having to manually adjust volume levels between tracks when playing audio files from albums that have been mastered at different loudness levels.\n\n-- Source: [Wikipedia][1]\n\n\u003e ReplayGain is the name of a technique invented to achieve the same perceived playback loudness of audio files. It defines an algorithm to measure the perceived loudness of audio data.\n\n-- Source: [hydrogenaud.io][2]\n\n## Requirements\n\n- Python \u003e= 3.6 -- http://python.org/\n- GStreamer -- http://gstreamer.org/\n- PyGObject -- https://pygobject.readthedocs.io/en/latest/\n\nTo install these dependencies on Debian or Ubuntu (16.10 or newer):\n\n ```console\n$ apt install \\\n      gir1.2-gstreamer-1.0 \\\n      gstreamer1.0-plugins-base \\\n      gstreamer1.0-plugins-good \\\n      gstreamer1.0-plugins-bad \\\n      gstreamer1.0-plugins-ugly \\\n      python3 \\\n      python3-gi\n```\n\n(Or if you prefer to install the latest PyGObject from source code,\nreplace `python3-gi` with `libcairo2-dev libgirepository1.0-dev`.)\n\nYou will also need GStreamer decoding plugins for any audio formats you want to\nuse.\n\n## Installation\n\nJust install it like any other Python package using `pip`:\n\n ```console\n$ python3 -m pip install --user rgain3\n ```\n\n## Usage\n\n### `replaygain`\n\nThis is a program like, say, `vorbisgain` or `mp3gain`, the difference\nbeing that instead of supporting a mere one format, it supports several:\n\n- Ogg Vorbis (or probably anything you can put into an Ogg container)\n- Flac\n- WavPack\n- MP4 (commonly using the AAC codec)\n- MP3\n\nThe basic usage of the program is simple:\n\n```console\n$ replaygain AUDIOFILE1 AUDIOFILE2 ...\n```\n\nThere are various options; see them by running:\n\n```console\n$ replaygain --help\n```\n\n### `collectiongain`\n\nThis program is designed to apply Replay Gain to whole music collections, plus\nthe ability to simply add new files, run `collectiongain` and have it\nreplay-gain those files without asking twice.\n\nTo use it, simply run:\n\n```console\n$ collectiongain PATH_TO_MUSIC\n```\n\nand re-run it whenever you add new files. Run:\n\n```console\n$ collectiongain --help\n```\n\nto see possible options.\n\nIf, however, you want to find out how exactly `collectiongain` works, read on\n(but be warned: It's long, boring, technical, incomprehensible and awesome).\n`collectiongain` runs in two phases: The file collecting phase and the actual\nrun. Prior to analyzing any audio data, `collectiongain` gathers all audio\nfiles in the directory and determines a so-called album ID for each from the\nfile's tags:\n\n- If the file contains a Musicbrainz album ID, that is used.\n- Otherwise, if the file contains an *album* tag, it is joined with either\n\n  * a MusicBrainz album artist ID, if that exists\n  * an *albumartist* tag, if that exists,\n  * or the *artist* tag\n  * or nothing if none of the above tags exist.\n\n  The resulting artist-album combination is the album ID for that file.\n- If the file doesn't contain a Musicbrainz album ID or an *album* tag, it is\n  presumed to be a single track without album; it will only get track gain, no\n  album gain.\n\nSince this step takes a relatively long time, the album IDs are cached between\nseveral runs of `collectiongain`. If a file was modified or a new file was\nadded, the album ID will be (re-)calculated for that file only.\nThe program will also cache an educated guess as to whether a file was already\nprocessed and had ReplayGain added -- if `collectiongain` thinks so, that\nfile will totally ignored for the actual run. This flag is set whenever the file\nis processed in the actual run phase (save for dry runs, which you can enable\nwith the `--dry-run` switch) and is cleared whenever a file was changed. You\ncan pass the `--ignore-cache` switch to make `collectiongain` totally ignore\nthe cache; in that case, it will behave as if no cache was present and read your\ncollection from scratch.\n\nFor the actual run, `collectiongain` will simply look at all files that have\nsurvived the cleansing described above; for files that don't contain ReplayGain\ninformation, `collectiongain` will calculate it and write it to the files (use\nthe `--force` flag to calculate gain even if the file already has gain data).\nHere comes the big moment of the album ID: files that have the same album ID are\nconsidered to be one album (duh) for the calculation of album gain. If only one\nfile of an album is missing gain information, the whole album will be\nrecalculated to make sure the data is up-to-date.\n\n### MP3 formats\n\nProper ReplayGain support for MP3 files is a bit of a mess: on the one hand,\nthere is the `mp3gain` [application][3] which was relatively widely used (I\ndon't know if it still is) -- it directly modifies the audio data which has the\nadvantage that it works with pretty much any player, but it also means you have\nto decide ahead of time whether you want track gain or album gain. Besides, it's\njust not very elegant. On the other hand, there are at least two commonly used\nways [to store proper ReplayGain information in ID3v2 tags][4].\n\nNow, in general you don't have to worry about this when using this package: by\ndefault, `replaygain` and `collectiongain` will read and write ReplayGain\ninformation in the two most commonly used formats. However, if for whatever\nreason you need more control over the MP3 ReplayGain information, you can use\nthe `--mp3-format` option (supported by both programs) to change the\nbehaviour.\n\nPossible choices with this switch are:\n\n| Name | Description |\n|------|-------------|\n| `replaygain.org`\u003cbr\u003e(alias: `fb2k`) | Replay Gain information is stored in ID3v2 TXXX frames. This format is specified on the replaygain.org website as the recommended format for MP3 files. Notably, this format is used by music players like [foobar2000][5] and [Quod Libet][6]. The latter can also fall back on the legacy format. |\n| `legacy`\u003cbr\u003e(alias: `ql`) | Replay Gain information is stored in ID3v2.4 RVA2 frames. This format is described as \"legacy\" by replaygain.org; however, it might still be the primary format for some music players. It should be noted that this format does not support volume adjustments of more than 64 dB: if the calculated gain value is smaller than -64 dB or greater than or equal to +64 dB, it is clamped to these limit values. |\n| `default` | This is the default implementation used by both `replaygain` and `collectiongain`. When writing ReplayGain data, both the `replaygain.org` as well as the `legacy` format are written. As for reading, if a file contains data in both formats, both data sets are read and then compared. If they match up, that ReplayGain information is returned for the file. However, if they don't match, no ReplayGain data is returned to signal that this file does not contain valid (read: consistent) ReplayGain information. |\n\n## Development\n\nFork and clone this repository. Inside the checkout create a `virtualenv` and install `rgain3` in develop mode:\n\nNote that developing from source requires the Python headers and therefore the\n`python3.x-dev` system package to be installed.\n\n```console\n$ python3 -m venv env\n$ source env/bin/activate\n(env) $ python -m pip install -Ue .\n```\n\n### Running Tests\n\nTo run the tests with the Python version of your current virtualenv, simply\ninvoke `pytest` installing `test` extras:\n\n```console\n(env) $ python -m pip install -Ue \".[test]\"\n(env) $ pytest\n```\n\nYou can run tests for all supported Python version using `tox` like so:\n\n```console\n(env) $ tox\n```\n\n## Copyright\n\nWith the exception of the manpages, all files are::\n\n- Copyright (c) 2009-2015 Felix Krull \u003cf_krull@gmx.de\u003e\n- Copyright (c) 2019-2020 Christian Haudum \u003cdeveloper@christianhaudum.at\u003e\n\nThe manpages were originally written for the Debian project and are::\n\n- Copyright (c) 2011 Simon Chopin \u003cchopin.simon@gmail.com\u003e\n- Copyright (c) 2012-2015 Felix Krull \u003cf_krull@gmx.de\u003e\n\n\n[1]: https://en.wikipedia.org/wiki/ReplayGain\n[2]: http://wiki.hydrogenaud.io/index.php?title=ReplayGain\n[3]: http://mp3gain.sourceforge.net/\n[4]: http://wiki.hydrogenaud.io/index.php?title=ReplayGain_specification#ID3v2\n[5]: http://foobar2000.org\n[6]: https://github.com/quodlibet/quodlibet/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaudum%2Frgain3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaudum%2Frgain3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaudum%2Frgain3/lists"}