<commit_before>What is a music player?
=======================

Sometimes I get asked questions like:

> What does a music player do?
> Isn't it trivial to just play some mp3s?
> What makes a music player better at playing music than some media player like [VLC](http://www.videolan.org/vlc/) ([*](#vlc))?
> Can the audio playback quality really differ between different players?

So, I'll try to answer these questions here now.


## [Resampling](http://en.wikipedia.org/wiki/Resampling_%28audio%29)

The [soundcard](http://en.wikipedia.org/wiki/Sound_card) or the [operating system (OS)](http://en.wikipedia.org/wiki/Operating_system) usually gets [raw PCM data](http://en.wikipedia.org/wiki/Pulse-code_modulation) from an application. It usually internally works with PCM data at 48 kHz or 96 kHz. If you feed it the PCM data at another frequency, it is often able to resample the data automatically.

Audio [CDs](http://en.wikipedia.org/wiki/Compact_Disc) and most MP3s are encoded with 44.1 kHz and thus there is some resampling needed at some point.

Resampling isn't trivial and there is not really a straight-forward way to do it. Thus, different algorithms can result in much different quality.

A simple media player usually doesn't cares about that and leaves the resampling to the OS or has only some simple resampling algorithm.

A music player usually has its own high-quality resampling algorithm.

This project uses [libswresample of FFmpeg](http://ffmpeg.org/doxygen/trunk/libswresample_2resample_8c-source.html).


## [Loudness normalization](http://en.wikipedia.org/wiki/Audio_normalization#Loudness_normalization)

Different songs from different sources often have different volume / loudness.

A media player usually just plays the song as-is.

In a music player, you usually want that all songs are played with about the same loudness so that you don't have to manually frequently change the volume to adopt to the current song.

Many existing music players don't have their own loudness analyzing algorithm. They depend on external software which analyzes your music and saves the volume-change-information in the metatags of your songs. The music player checks for that metadata information and applies the volume change. However, if it stumbles upon a song which misses this metadata information, it will not be able to do the loudness normalization.

Some professional music players such as iTunes have their own analyzing algorithm.

This project also has its own analyzing algorithm which calculates the loudness of a song based on the [ReplayGain specification](http://www.replaygain.org/).


## Avoid [clipping](http://en.wikipedia.org/wiki/Clipping_%28audio%29) issues when incrementing the volume

When you set the volume to more than 100% (which could also theoretically, though rarely happen from the loudness normalization), you might get the case that you get PCM samples which exceeds the maximum value. E.g. assume that a PCM sample value must be between -1 and 1. If you apply the volume change and you get a value `v > 1`, you must make it fit somehow. The simplest variant would be to just use `1` as the value in that case. This is called clipping.

You want to avoid clipping because it results in bad distorted sound.

Via [dynamic range compression](http://en.wikipedia.org/wiki/Dynamic_range_compression), you can get rid of this effect while at the same time have other quality losses and you have the audio data altered.

This project uses a smooth compression variant which is only applied for values above some high threshold. Thus, in most cases, the audio data is not altered at all which is what [audiophiles](http://en.wikipedia.org/wiki/Audiophile) usually want. The compression itself has some nice properties such as that it is always smooth and will never need clipping.


## Equalizer
<commit_msg>Fix broken link to replaygain.org.<commit_after>What is a music player?
=======================

Sometimes I get asked questions like:

> What does a music player do?
> Isn't it trivial to just play some mp3s?
> What makes a music player better at playing music than some media player like [VLC](http://www.videolan.org/vlc/) ([*](#vlc))?
> Can the audio playback quality really differ between different players?

So, I'll try to answer these questions here now.


## [Resampling](http://en.wikipedia.org/wiki/Resampling_%28audio%29)

The [soundcard](http://en.wikipedia.org/wiki/Sound_card) or the [operating system (OS)](http://en.wikipedia.org/wiki/Operating_system) usually gets [raw PCM data](http://en.wikipedia.org/wiki/Pulse-code_modulation) from an application. It usually internally works with PCM data at 48 kHz or 96 kHz. If you feed it the PCM data at another frequency, it is often able to resample the data automatically.

Audio [CDs](http://en.wikipedia.org/wiki/Compact_Disc) and most MP3s are encoded with 44.1 kHz and thus there is some resampling needed at some point.

Resampling isn't trivial and there is not really a straight-forward way to do it. Thus, different algorithms can result in much different quality.

A simple media player usually doesn't cares about that and leaves the resampling to the OS or has only some simple resampling algorithm.

A music player usually has its own high-quality resampling algorithm.

This project uses [libswresample of FFmpeg](http://ffmpeg.org/doxygen/trunk/libswresample_2resample_8c-source.html).


## [Loudness normalization](http://en.wikipedia.org/wiki/Audio_normalization#Loudness_normalization)

Different songs from different sources often have different volume / loudness.

A media player usually just plays the song as-is.

In a music player, you usually want that all songs are played with about the same loudness so that you don't have to manually frequently change the volume to adopt to the current song.

Many existing music players don't have their own loudness analyzing algorithm. They depend on external software which analyzes your music and saves the volume-change-information in the metatags of your songs. The music player checks for that metadata information and applies the volume change. However, if it stumbles upon a song which misses this metadata information, it will not be able to do the loudness normalization.

Some professional music players such as iTunes have their own analyzing algorithm.

This project also has its own analyzing algorithm which calculates the loudness of a song based on the [ReplayGain specification](http://wiki.hydrogenaudio.org/index.php?title=ReplayGain_1.0_specification).


## Avoid [clipping](http://en.wikipedia.org/wiki/Clipping_%28audio%29) issues when incrementing the volume

When you set the volume to more than 100% (which could also theoretically, though rarely happen from the loudness normalization), you might get the case that you get PCM samples which exceeds the maximum value. E.g. assume that a PCM sample value must be between -1 and 1. If you apply the volume change and you get a value `v > 1`, you must make it fit somehow. The simplest variant would be to just use `1` as the value in that case. This is called clipping.

You want to avoid clipping because it results in bad distorted sound.

Via [dynamic range compression](http://en.wikipedia.org/wiki/Dynamic_range_compression), you can get rid of this effect while at the same time have other quality losses and you have the audio data altered.

This project uses a smooth compression variant which is only applied for values above some high threshold. Thus, in most cases, the audio data is not altered at all which is what [audiophiles](http://en.wikipedia.org/wiki/Audiophile) usually want. The compression itself has some nice properties such as that it is always smooth and will never need clipping.


## Equalizer

{'fraction_non_alphanumeric': 0.06708649273872253, 'fraction_numerical': 0.006939982007454055, 'mean_word_length': 4.684441197954712, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 3, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6471738', 'n_tokens_mistral': 2071, 'n_tokens_neox': 1947, 'n_words': 1062}