### Install Linux/Mac Application Files

Source: https://github.com/complexlogic/rsgain/blob/master/CMakeLists.txt

Installs the target executable, man pages, and presets to the specified installation prefix for Linux and macOS. Handles different packaging strategies.

```cmake
elseif (UNIX)
  install(TARGETS ${EXECUTABLE_TITLE} DESTINATION "${CMAKE_INSTALL_PREFIX}/bin")
  if (INSTALL_MANPAGE)
    install(FILES "${PROJECT_BINARY_DIR}/${EXECUTABLE_TITLE}.1.gz" DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man1")
  endif ()
  install(DIRECTORY "${PROJECT_SOURCE_DIR}/config/presets" DESTINATION "${CMAKE_INSTALL_PREFIX}/share/${EXECUTABLE_TITLE}")
  if (PACKAGE STREQUAL "TXZ" OR PACKAGE STREQUAL "ZIP")
    set(BINARY_PREFIX ".")
    set(PRESETS_PREFIX ".")
  else ()
    set(BINARY_PREFIX "${CMAKE_INSTALL_PREFIX}/bin")
    set(PRESETS_PREFIX "${CMAKE_INSTALL_PREFIX}/share/${EXECUTABLE_TITLE}")
  endif ()
  install(TARGETS ${EXECUTABLE_TITLE} DESTINATION "${BINARY_PREFIX}")
  install(DIRECTORY "${PROJECT_SOURCE_DIR}/config/presets" DESTINATION "${PRESETS_PREFIX}")
  set(PRESETS_DIR ${CMAKE_INSTALL_PREFIX}/share/${EXECUTABLE_TITLE}/presets)
```

--------------------------------

### Install to system directories on Unix

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Install the compiled binary to system paths.

```bash
sudo make install
```

--------------------------------

### Install rsgain on Fedora

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain using dnf on Fedora.

```bash
sudo dnf install rsgain
```

--------------------------------

### Install rsgain on FreeBSD

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain on FreeBSD via the ports tree or using pkg.

```bash
cd /usr/ports/audio/rsgain && make install clean

pkg install rsgain
```

--------------------------------

### Example Preset File Structure

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

This is an example of an INI-formatted preset file. It shows the structure with global settings and format-specific overrides for FLAC, MP3, and Opus.

```ini
[Global]
TargetLoudness=-18
Album=true
ClipMode=p
TruePeak=false
Lowercase=false
PreserveMtimes=false

[FLAC]
TagMode=i

[MP3]
ID3v2Version=4

[Opus]
OpusMode=r
TargetLoudness=-23

```

--------------------------------

### Install rsgain in Nix environment

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain into your Nix environment using nix-env.

```bash
nix-env -f '<nixpkgs>' -iA rsgain
```

--------------------------------

### Install Windows Application Files

Source: https://github.com/complexlogic/rsgain/blob/master/CMakeLists.txt

Installs application files, including executables, licenses, and presets, to the binary directory for Windows. It also handles copying Visual C++ runtime DLLs.

```cmake
if (WIN32)
  install(DIRECTORY ${PROJECT_BINARY_DIR}/$<CONFIG>/ DESTINATION .)
  foreach(item CHANGELOG LICENSE LICENSE-CRCpp)
    configure_file("${PROJECT_SOURCE_DIR}/${item}" "${PROJECT_BINARY_DIR}/${item}.txt")
    install(FILES "${PROJECT_BINARY_DIR}/${item}.txt" DESTINATION .)
  endforeach ()

  # Install presets
  file(GLOB presets ${PROJECT_SOURCE_DIR}/config/presets/*.ini)
  foreach(preset ${presets})
	get_filename_component(preset_name ${preset} NAME)
    configure_file(${preset} ${PROJECT_BINARY_DIR}/presets/${preset_name})
  endforeach ()
  install(DIRECTORY "${PROJECT_BINARY_DIR}/presets" DESTINATION .)

  # Copy the Visual C++ runtime DLLs in case user doesn't have them installed
  set(CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP TRUE)
  include(InstallRequiredSystemLibraries)
  foreach(required_lib vcruntime140.dll vcruntime140_1.dll msvcp140.dll)
    foreach(system_lib ${CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS})
      string(FIND ${system_lib} ${required_lib} found_lib)
      if (NOT found_lib EQUAL -1)
        install(FILES ${system_lib} DESTINATION .)
      endif ()
    endforeach ()
  endforeach ()

  # Set up CPack
  set(CPACK_PACKAGE_NAME ${EXECUTABLE_TITLE})
  set(CPACK_GENERATOR "ZIP")
  include(CPack)
endif()
```

--------------------------------

### Convenience Output Macros Example

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Illustrates the usage of convenience output macros for different message types. These examples show how to pass format strings and variadic arguments to the macros for styled console output.

```cpp
output_ok("Scanned {} files", count);
output_warn("Clipping protection adjusted {} tracks", adjust_count);
output_error("Failed to open file: {}", path);
output_fail("Fatal error: {}", error_msg);
```

--------------------------------

### Example Output with Prefixes

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Shows example console output using predefined prefixes for success, warnings, and errors. These prefixes often incorporate ANSI color codes and platform-specific characters for visual distinction.

```text
[✔] File: album.flac
[!] Clipping protection adjusted 2 files
[✘] Error: File not found
```

--------------------------------

### Install dependencies on FreeBSD

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use the pkg manager to install required development libraries on FreeBSD.

```bash
pkg install ebur128 taglib libfmt inih ffmpeg
```

--------------------------------

### Install rsgain on Arch/Manjaro

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain from the AUR using an AUR helper like 'yay'.

```bash
yay -S rsgain
```

--------------------------------

### Install dependencies on APT-based Linux

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use this command to install required development libraries on Debian, Ubuntu, and Mint systems.

```bash
sudo apt install libebur128-dev libtag1-dev libavformat-dev libavcodec-dev libswresample-dev libavutil-dev libfmt-dev libinih-dev
```

--------------------------------

### Install dependencies on Portage-based Linux

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use this command to install required development libraries on Gentoo and related systems.

```bash
sudo emerge --ask --noreplace --tree media-libs/libebur128 media-libs/taglib media-video/ffmpeg dev-libs/inih dev-libs/libfmt
```

--------------------------------

### Install dependencies on DNF-based Linux

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use this command to install required development libraries on Fedora systems.

```bash
sudo dnf install libebur128-devel taglib-devel libavformat-free-devel libavcodec-free-devel libswresample-free-devel libavutil-free-devel fmt-devel inih-devel
```

--------------------------------

### Install dependencies on macOS

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use Homebrew to install required development libraries on macOS.

```bash
brew install libebur128 taglib ffmpeg fmt inih 
```

--------------------------------

### Multi-Format Consistency with rsgain

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

This example ensures consistent target loudness across different audio formats (FLAC, MP3, Opus, M4A) by applying specific rsgain custom commands for each.

```bash
#!/bin/bash
# Ensure all formats use consistent target loudness
TARGET=-18

rsgain custom -a -s i -l $TARGET *.flac
rsgain custom -a -s i -l $TARGET *.mp3
rsgain custom -a -s i -l $TARGET -o d *.opus
rsgain custom -a -s i -l $TARGET -I 4 *.m4a
```

--------------------------------

### Install rsgain using Scoop on Windows

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Installs rsgain via the Scoop package manager, enabling automatic upgrades. Ensure the Scoop extras bucket is enabled before running.

```powershell
scoop install extras/rsgain
```

--------------------------------

### Output Example for MTProgress

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Illustrates the expected output format for the MTProgress update method, showing the current progress and the directory being scanned.

```text
[1/150] Scanning directory: /media/music/Artist/Album
```

--------------------------------

### Easy Mode Preset File Example

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/configuration.md

This INI-format preset file configures global and MP3-specific settings for rsgain. Use it to customize tagging behavior.

```ini
[Global]
TagMode=i
TargetLoudness=-18
Album=true
ClipMode=p
TruePeak=false
Lowercase=false
ID3v2Version=keep
OpusMode=d
PreserveMtimes=false

[MP3]
ID3v2Version=3

[FLAC]
TagMode=i

[Opus]
OpusMode=r
TargetLoudness=-23
```

--------------------------------

### Basic Custom Mode Scan Example

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/configuration.md

Scans two MP3 files, inserts ReplayGain tags, calculates album gain, and uses a -18 LUFS target. Ensure files are specified correctly.

```bash
rsgain custom -a -s i -l -18 file1.mp3 file2.mp3
```

--------------------------------

### Install dependencies on Pacman-based Linux

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Use this command to install required development libraries on Arch and Manjaro systems.

```bash
sudo pacman -S libebur128 taglib ffmpeg fmt libinih
```

--------------------------------

### Install rsgain on Debian/Ubuntu

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain using apt on Debian 13 (Trixie) and Ubuntu 24.04 (noble).

```bash
sudo apt install rsgain
```

--------------------------------

### rsgain custom command examples

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/command-reference.md

Demonstrates various use cases for the rsgain custom command, including tagging, analysis, and export.

```bash
rsgain custom -a -s i -l -18 song1.mp3 song2.mp3 song3.mp3
```

```bash
rsgain custom -a -s s *.flac
```

```bash
rsgain custom -s d *.mp3
```

```bash
rsgain custom -a -s s -O s *.flac > analysis.csv
```

```bash
rsgain custom -a -s i -o s *.opus
```

```bash
rsgain custom -a -s i -I 4 *.mp3
```

```bash
rsgain custom -a -s i -c p -m -0.5 *.flac
```

```bash
rsgain custom -a -s s -t *.flac
```

```bash
rsgain custom -a -s s -q *.mp3
```

--------------------------------

### Generate zipped package on Windows

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Create a zipped installation package using CMake.

```bash
cmake --build . --config Release --target package
```

--------------------------------

### ProgressBar Output Format Example

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Illustrates the output format of the ProgressBar's update method, showing the percentage completion and a visual representation of the progress. This format is used to provide real-time feedback to the user.

```text
  75% [======    ]

```

--------------------------------

### Run rsgain without installing using Nix

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Execute rsgain directly from nixpkgs without a formal installation.

```bash
nix run nixpkgs#rsgain
```

--------------------------------

### Install rsgain on Android via Termux

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Install rsgain on Android devices using the Termux package manager.

```bash
pkg install rsgain
```

--------------------------------

### Create and Use a Custom Preset File

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Define custom gain and processing settings in an INI file. This example shows a preset for MP3, FLAC, and Opus files with specific loudness targets and clipping modes. The preset is then applied using the 'easy' command.

```ini
[Global]
TargetLoudness=-16
Album=true
ClipMode=p
TruePeak=false
PreserveMtimes=false

[MP3]
ID3v2Version=4
Lowercase=false

[FLAC]
TruePeak=false

[Opus]
OpusMode=s
TargetLoudness=-23
```

```bash
rsgain easy -p mypreset /path/to/music
```

--------------------------------

### rsgain::print Usage Example

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Demonstrates how to use the rsgain::print function for formatted output to standard output and standard error. It shows basic string and variable insertion into the format string.

```cpp
rsgain::print("File: {} ({}x{})
", filename, width, height);
rsgain::print(stderr, "Error: {}
", error_message);
```

--------------------------------

### Install rsgain .deb package on Debian Bookworm

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Download and install the .deb package for Debian Bookworm. Note: This package may not work on recent Ubuntu releases due to an FFmpeg ABI break.

```bash
wget https://github.com/complexlogic/rsgain/releases/download/v3.7/rsgain_3.7-1_amd64.deb
sudo apt install ./rsgain_3.7-1_amd64.deb
```

--------------------------------

### Windows Console Setup for ANSI Support

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

This C++ code snippet demonstrates the Windows-specific initialization sequence for console output, including enabling ANSI escape sequence support and hiding the cursor.

```cpp
#include <windows.h>

// ...

HANDLE hConsole = GetStdHandle(STD_OUTPUT_HANDLE);
DWORD dwMode = 0;
GetConsoleMode(hConsole, &dwMode);
dwMode |= ENABLE_VIRTUAL_TERMINAL_PROCESSING;
SetConsoleMode(hConsole, dwMode);

// ... hide cursor
CONSOLE_CURSOR_INFO cursorInfo;
GetConsoleCursorInfo(hConsole, &cursorInfo);
cursorInfo.bVisible = FALSE;
SetConsoleCursorInfo(hConsole, &cursorInfo);
```

--------------------------------

### MP3 ReplayGain Tags

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/file-formats.md

Example of ReplayGain track and album gain/peak information stored in ID3v2 TXXX frames for MP3 files.

```text
TXXX[id3:Description="REPLAYGAIN_TRACK_GAIN"]: +2.50 dB
TXXX[id3:Description="REPLAYGAIN_TRACK_PEAK"]: 1.234567
TXXX[id3:Description="REPLAYGAIN_ALBUM_GAIN"]: +1.25 dB
TXXX[id3:Description="REPLAYGAIN_ALBUM_PEAK"]: 0.987654
```

--------------------------------

### Get Easy Mode Configuration

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Retrieves the Easy Mode configuration for a specific audio file type. Returns a Config struct with Easy Mode defaults, including format-specific and preset overrides.

```cpp
const Config& get_config(FileType type)
```

--------------------------------

### Clone and prepare build directory on Windows

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Initial steps to download the source code and create a build directory on Windows.

```bash
git clone https://github.com/complexlogic/rsgain.git
cd rsgain
mkdir build
cd build
```

--------------------------------

### Clone and prepare build directory on Unix

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Initial steps to download the source code and create a build directory on Unix systems.

```bash
git clone https://github.com/complexlogic/rsgain.git
cd rsgain
mkdir build && cd build
```

--------------------------------

### Build and test on Unix

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Compile the project and run the executable.

```bash
make
./rsgain
```

--------------------------------

### Build and test on Windows

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Compile the project and run the executable on Windows.

```bash
cmake --build . --config Release
.\Release\rsgain.exe
```

--------------------------------

### ScanJob Factory Method (Easy Mode)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/scan-api.md

Creates a ScanJob for scanning an entire directory in Easy Mode. Recursively finds audio files and applies default configurations.

```cpp
static ScanJob* ScanJob::factory(const std::filesystem::path &path)
```

--------------------------------

### Configure build with vcpkg on Windows

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Generate Visual Studio project files using CMake and vcpkg.

```bash
cmake .. -DVCPKG=ON
```

--------------------------------

### Display rsgain Help and Version

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/command-reference.md

Use these commands to display help information or the version of the rsgain tool.

```bash
rsgain --help
```

```bash
rsgain --version
```

--------------------------------

### Generate Uninstall Target

Source: https://github.com/complexlogic/rsgain/blob/master/CMakeLists.txt

Configures and adds a custom target named 'uninstall' that executes a CMake script to remove installed files. This is typically used after installation.

```cmake
configure_file(
      "${PROJECT_SOURCE_DIR}/config/cmake_uninstall.cmake.in"
      "${PROJECT_BINARY_DIR}/cmake_uninstall.cmake")
  add_custom_target(uninstall COMMAND ${CMAKE_COMMAND} -P ${PROJECT_BINARY_DIR}/cmake_uninstall.cmake)
```

--------------------------------

### Easy Mode Entry Point

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

The entry point for Easy Mode. Parses command-line arguments and initiates the directory scan. Supports preset loading and multithreading.

```cpp
void easy_mode(int argc, char *argv[])
```

--------------------------------

### get_config

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Get Easy Mode configuration for a specified file type. Returns static Config struct with Easy Mode defaults.

```APIDOC
## get_config

### Description
Get Easy Mode configuration for a specified file type. Returns static Config struct with Easy Mode defaults.

### Signature
```cpp
const Config& get_config(FileType type)
```

### Parameters
#### Path Parameters
- **type** (FileType) - Required - Audio format (MP3, FLAC, Opus, etc.)

### Returns
- **const Config&** - Configuration structure with Easy Mode defaults

### Supported Types
- DEFAULT - Multi-format directory defaults
- MP2, MP3 - MPEG audio
- FLAC - Free Lossless Audio Codec
- OGG - Ogg Vorbis/Speex
- OPUS - Opus codec
- M4A - MPEG-4 Audio
- WMA - Windows Media Audio
- WAV - Waveform Audio
- AIFF - Audio Interchange File Format
- WAVPACK - WavPack
- APE - Monkey's Audio
- TAK - Tom's Audio Kompressor
- MPC - Musepack
- DSF - DSD Stream Format
- MATROSKA, WEBM - Matroska container (if supported)

### Easy Mode Defaults (all formats)

| Setting | Value | Rationale |
|---------|-------|-----------|
| tag_mode | 'i' | Insert/scan tags |
| target_loudness | -18.0 LUFS | ReplayGain 2.0 standard |
| clip_mode | 'p' | Positive-only protection |
| do_album | true | Calculate album gain |
| true_peak | false | Sample peak (faster) |
| lowercase | false | Uppercase tags (standard) |
| id3v2version | ID3V2_KEEP | Preserve existing version |
| opus_mode | 'd' | Standard ReplayGain tags |
```

--------------------------------

### WorkerThread Constructor

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Constructs a WorkerThread instance, initializing it with an initial scan job and shared synchronization primitives. The internal thread starts immediately and begins processing the initial job.

```APIDOC
## WorkerThread Constructor

### Description
Create worker thread with initial job.

### Parameters:
- initial_job (`unique_ptr<ScanJob>&`): First ScanJob to process (transferred)
- main_mutex (`mutex&`): Shared mutex protecting main loop
- ffmpeg_mutex (`mutex&`): Shared mutex for FFmpeg thread safety
- main_cv (`condition_variable&`): Main thread condition variable
- data (`ScanData&`): Shared results aggregator

### Description:
Constructs worker thread with shared synchronization primitives. Starts internal thread immediately. Thread begins working on initial_job.
```

--------------------------------

### Apply Standard ReplayGain Tags (foobar2000)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Applies standard ReplayGain tags to FLAC files, compatible with foobar2000.

```bash
# Standard ReplayGain tags (works with foobar2000)
rsgain custom -a -s i *.flac
```

--------------------------------

### WorkerThread Constructor

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Constructs a WorkerThread instance, initializing it with an initial scan job and shared synchronization primitives. The internal thread starts immediately and begins processing the initial job.

```cpp
WorkerThread(std::unique_ptr<ScanJob> &initial_job,
             std::mutex &main_mutex,
             std::mutex &ffmpeg_mutex,
             std::condition_variable &main_cv,
             ScanData &data)
```

--------------------------------

### Opus Files: Standard ReplayGain (Default)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Writes standard ReplayGain tags for maximum compatibility. Targets -18 LUFS. Recommended for most modern players.

```bash
rsgain custom -a -s i -o d *.opus
```

--------------------------------

### ProgressBar Class Definition

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/types.md

Renders a console progress bar for single-threaded operations. Manages console output positioning and updates. Requires initialization with start position and total length.

```cpp
class ProgressBar {
    private:
        int c_prev = -1;
        int w_prev = -1;
        int pos_prev = -1;
        int start;
        int len = 0;
        char *buffer = nullptr;

        static int get_console_width();
    
    public:
        void begin(int start, int len);
        void update(int pos);
        void complete();
#ifdef _WIN32
        static void set_console(HANDLE c);
#endif
};

```

--------------------------------

### Complete Library Processing with rsgain

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

This workflow demonstrates a full library processing cycle: first analyzing with a dry run, then tagging with multithreading, and finally verifying tags using ffprobe.

```bash
#!/bin/bash
# 1. Analyze (dry run)
echo "Analyzing library..."
rsgain easy -q /path/to/music

# 2. Tag (with multithreading)
echo "Tagging library..."
rsgain easy -m MAX /path/to/music

# 3. Verify
echo "Verifying tags..."
find /path/to/music -name "*.flac" -o -name "*.mp3" | head -5 | while read f;
    echo "=== $(basename "$f") ==="
    ffprobe -v quiet -print_format flat=h=: -show_format "$f" | grep REPLAY || echo "No tags"
done
```

--------------------------------

### Verify ReplayGain Tags with MediaInfo

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Alternatively, use the 'mediainfo' command-line tool to inspect ReplayGain tags in audio files like FLAC.

```bash
# Or use mediainfo
mediainfo song.flac | grep -i replay
```

--------------------------------

### Apply Standard ReplayGain Tags (VLC)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Applies standard ReplayGain tags to FLAC files, compatible with VLC Media Player.

```bash
# Standard tags
rsgain custom -a -s i *.flac
```

--------------------------------

### Generate Makefile on Unix

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Configure the build system using CMake.

```bash
cmake .. -DCMAKE_BUILD_TYPE=Release
```

--------------------------------

### easy_mode

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Easy Mode entry point. Parses command-line arguments and executes directory scan. Supports preset and multithreading options.

```APIDOC
## easy_mode

### Description
Easy Mode entry point. Parses command-line arguments and executes directory scan. Supports preset and multithreading options.

### Signature
```cpp
void easy_mode(int argc, char *argv[])
```

### Parameters
#### Path Parameters
- **argc** (int) - Required - Argument count (including command name "easy")
- **argv** (char*[]) - Required - Argument array starting with "easy"

### Behavior
Parses Easy Mode-specific options, loads preset configuration, initiates recursive directory scan with optional multithreading, displays statistics, and exits. Supports `-p` preset option and `-m` multithreading.

**Common Options:**
- `-p preset_name` - Load INI configuration preset
- `-m N` or `-m MAX` - Use N worker threads (or auto-detect)
- `-S` - Skip files with existing ReplayGain tags
- `-l N` - Override target loudness to N LUFS
- `-q` - Quiet mode (suppress progress output)
- `-O` - Tab-delimited output to stdout
```

--------------------------------

### Example Preset for Skipping All Files Except Opus

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

This INI configuration skips all files except Opus, allowing targeted tagging. It sets the global tag mode to skip and the Opus tag mode to include, with a specific Opus mode for R128 gain tags.

```ini
[Global]
TagMode=n

[Opus]
TagMode=i
OpusMode=r
```

--------------------------------

### Apply Gain with Custom Peak Level Headroom

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Set a custom maximum peak level to create headroom, preventing clipping. Negative values for the `-m` flag specify the amount of headroom in dB. For example, -0.5 dB provides 0.5 dB of headroom.

```bash
# 0.5 dB headroom
rsgain custom -a -c p -m -0.5 *.flac
```

```bash
# 1.0 dB headroom (conservative)
rsgain custom -a -c a -m -1.0 *.flac
```

--------------------------------

### Organize Music for Album Gain

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Ensure your music is organized into separate directories per album for correct album gain calculations. Then run rsgain in easy mode at the album level.

```bash
# Run Easy Mode at artist/album level
rsgain easy /music/Artist A/Album 1
```

--------------------------------

### Run rsgain in Easy Mode

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/command-reference.md

Recursively scans a directory with recommended settings. Use options to customize the scan.

```bash
rsgain easy /path/to/music/library
```

```bash
rsgain easy -m MAX /path/to/music/library
```

```bash
rsgain easy -p ebur128 -m 4 /path/to/music/library
```

--------------------------------

### Load Preset Configuration

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/command-reference.md

Use the -p or --preset option in Easy Mode to load a custom INI configuration file or a built-in preset like 'ebur128'. Presets define various format-specific settings.

```bash
rsgain easy -p /custom/preset.ini /music
```

```bash
rsgain easy -p ebur128 /music
```

--------------------------------

### Build Debian package

Source: https://github.com/complexlogic/rsgain/blob/master/docs/BUILDING.md

Generate a .deb package using CPack.

```bash
make package
```

--------------------------------

### Build rsgain Docker image

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Build a Docker image for rsgain from its Dockerfile in the repository.

```bash
docker build -t rsgain https://github.com/complexlogic/rsgain.git
```

--------------------------------

### Spotify/YouTube Music Normalization (-14 LUFS)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Use 'easy' mode for a quick Spotify standard normalization or 'custom' mode for more control. Targets -14 LUFS.

```bash
rsgain easy -l -14 /path/to/music
```

```bash
rsgain custom -a -s i -l -14 *.flac
```

--------------------------------

### Tag Entire Library with rsgain

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Use this command to apply maximum ReplayGain tags to all audio files in your music directory.

```bash
#!/bin/bash
MUSIC_DIR="/mnt/music"
rsgain easy -m MAX "$MUSIC_DIR"
```

--------------------------------

### Verify ReplayGain Tags with FFprobe

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Use FFprobe to read and verify the ReplayGain tags written to MP3 files. This helps confirm that the gain and peak values were applied correctly.

```bash
# Use FFmpeg to read tags
ffprobe -v quiet -print_format flat=h=: -show_format song.mp3 | grep -i replay
```

--------------------------------

### Run rsgain with sudo

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

If permission issues persist, try running rsgain with administrator privileges using 'sudo'.

```bash
# Or run as appropriate user
sudo rsgain custom *.flac
```

--------------------------------

### Invoke Easy Mode Scan (Bash)

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Use this command to initiate a recursive scan of your music library with default recommended settings. Ensure the path points to your music directory.

```bash
rsgain easy /path/to/music/library
```

--------------------------------

### scan_easy

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

Core Easy Mode scanning implementation. Recursively discovers audio files, creates ScanJobs, dispatches to worker threads, and collects results.

```APIDOC
## scan_easy

### Description
Core Easy Mode scanning implementation. Recursively discovers audio files, creates ScanJobs, dispatches to worker threads, and collects results.

### Signature
```cpp
void scan_easy(const std::filesystem::path &path, const std::filesystem::path &preset, size_t nb_threads)
```

### Parameters
#### Path Parameters
- **path** (filesystem::path) - Required - Root directory to scan recursively
- **preset** (filesystem::path) - Required - Path to INI preset file (empty for defaults)
- **nb_threads** (size_t) - Required - Number of worker threads (0 for single-threaded)

### Behavior
Recursively discovers audio files in directory tree, creates ScanJob per directory, dispatches to WorkerThread pool, collects results, and outputs statistics. Loads preset configuration if provided, applying overrides per file type.

- One ScanJob created per directory containing audio files
- If nb_threads > 1, jobs are processed in parallel
- Album gain calculated per directory
- Statistics aggregated across all directories
- Progress bar shown during scan (unless -q flag)
- Output written to stdout (if -O flag) or displayed as statistics
```

--------------------------------

### Easy Mode Parser Configuration

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/parsing-api.md

Applies preset configurations per file type and allows command-line overrides. Loads FLAC preset defaults.

```cpp
const Config& config = get_config(FileType::FLAC);  // Load FLAC preset
// config now has Easy Mode defaults:
// .tag_mode = 'i'             // insert tags
// .clip_mode = 'p'            // positive-only protection
// .do_album = true            // calculate album gain
// .target_loudness = -18.0
```

--------------------------------

### Optimize for Slow Systems with Sample Peak and Quiet Mode

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Demonstrates optimizing rsgain for slower systems by using sample peak calculation (faster) and quiet mode to suppress progress output.

```bash
# Sample peak (default, faster)
rsgain custom -s i *.flac

# True peak (slower, more accurate)
rsgain custom -s i -t *.flac

# Quiet mode (suppresses progress, faster output)
rsgain easy -q /path/to/music
```

--------------------------------

### Scan Directory Recursively (Easy Mode)

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Recursively scans an entire music library using recommended settings. It finds audio files, groups them by directory (album), measures loudness, calculates gain, writes ReplayGain tags, and applies clipping protection.

```bash
rsgain easy /path/to/music
```

--------------------------------

### Apply ReplayGain for Opus Files with foobar2000 Compensation

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Applies ReplayGain tags to Opus files, accounting for the +5 dB compensation often added by foobar2000.

```bash
# For Opus files, foobar adds +5 dB compensation
rsgain custom -a -s i -o d *.opus
```

--------------------------------

### Smart Pointers for Resource Management

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/types.md

Illustrates common smart pointer usage for managing dynamically allocated objects like EBU R128 state, scan jobs, and threads, ensuring proper cleanup.

```cpp
std::unique_ptr<ebur128_state, decltype(&free_ebur128)> ebur128;
// EBU R128 loudness meter with custom deleter
```

```cpp
std::unique_ptr<ScanJob> job;
// ScanJob with default delete
```

```cpp
std::unique_ptr<std::thread> thread;
// Thread object for worker threads
```

--------------------------------

### Core Easy Mode Scanning Function

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/easymode-api.md

The core implementation for scanning directories with Easy Mode. Recursively discovers audio files, processes them using a thread pool, and outputs statistics. Accepts a path, preset file, and number of threads.

```cpp
void scan_easy(const std::filesystem::path &path, 
               const std::filesystem::path &preset, 
               size_t nb_threads)
```

--------------------------------

### Run rsgain Docker container with mounted volume

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

Run the rsgain Docker container, mounting a host directory to access your music library. Use the -v option for volume mounting.

```bash
docker run -v /path/to/library:/mnt rsgain easy -m MAX /mnt
```

--------------------------------

### Check File Type with 'file' command

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Verify that a file is of a supported audio format using the 'file' command.

```bash
# Verify file is actually audio format
file song.flac
```

--------------------------------

### Check File Permissions

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

If you encounter a 'Permission denied' error, check and adjust file permissions using 'chmod'.

```bash
# Check file permissions
chmod 644 song.flac
```

--------------------------------

### Config Structure

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/api-reference.md

The `Config` struct holds all settings for ReplayGain scanning and tagging. It allows fine-grained control over tag modes, loudness targets, peak levels, album processing, and output formatting.

```APIDOC
## Config Structure

### Description
The `Config` struct encapsulates all configuration settings for ReplayGain scanning and tagging operations.

### Fields
- **tag_mode** (`char`) - Tag operation mode: 'd'=delete, 'i'=insert/scan, 's'=scan-only, 'n'=skip. Default: 's' (custom) or 'i' (easy).
- **skip_existing** (`bool`) - Skip files that already have REPLAYGAIN_TRACK_GAIN tag. Default: false.
- **target_loudness** (`double`) - Target loudness in LUFS (range: -30 to -5). Default: -18.0.
- **max_peak_level** (`double`) - Maximum peak level in dB for clipping protection. Default: 0.0.
- **true_peak** (`bool`) - Use true peak calculation instead of sample peak. Default: false.
- **clip_mode** (`char`) - Clipping protection: 'n'=none, 'p'=positive-only, 'a'=always. Default: 'n' (custom) or 'p' (easy).
- **do_album** (`bool`) - Calculate and tag album gain. Default: false (custom) or true (easy).
- **album_as_aes77** (`bool`) - Use loudest track as album loudness (AES77 mode). Default: false.
- **tab_output** (`OutputType`) - Output mode for tab-delimited results. Default: NONE.
- **sep_header** (`bool`) - Add sep header for Microsoft Excel compatibility. Default: false.
- **sort_alphanum** (`bool`) - Sort output alphanumerically by filename. Default: false.
- **lowercase** (`bool`) - Write lowercase tag names instead of uppercase. Default: false.
- **id3v2version** (`unsigned int`) - ID3v2 version: 0=keep existing, 3, or 4. Default: 0 (keep).
- **opus_mode** (`char`) - Opus tagging mode: 'd'=ReplayGain, 'r'=R128, 's'=R128 with -23 LUFS, 't'=track header gain, 'a'=album header gain. Default: 'd'.
- **skip_mp4** (`bool`) - Skip MP4 files (implementation detail for Easy Mode). Default: false.
- **preserve_mtimes** (`bool`) - Preserve file modification times after tagging. Default: false.
- **dual_mono** (`bool`) - Treat mono files as dual-mono when scanning. Default: false.
```

--------------------------------

### Easy Mode Scan with Preset and Multithreading

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/configuration.md

Scans a library using the EBU R128 preset (-23 LUFS) and automatically detects the optimal number of parallel threads for the CPU. Specify the library path correctly.

```bash
rsgain easy -p ebur128 -m MAX /path/to/library
```

--------------------------------

### Profile Processing Time with Multithreading

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Compares the processing time of rsgain in single-threaded mode versus multithreaded mode (MAX) to demonstrate potential speedups.

```bash
# Single-threaded
time rsgain easy -m 1 /path/to/music

# Multithreaded
time rsgain easy -m MAX /path/to/music
```

--------------------------------

### MP3 Files: Preserve Existing ID3v2 Version

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

Recommended for maximum compatibility. Keeps the existing ID3v2 version or defaults to 2.3 if none exists.

```bash
rsgain custom -a -s i -I keep *.mp3
```

--------------------------------

### ProgressBar::begin

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/output-api.md

Initializes the progress bar with the total number of work units. This method must be called before any calls to `update()`.

```APIDOC
## ProgressBar::begin

### Description
Initialize progress bar with total work units.

### Parameters:
#### Path Parameters
- **start** (`int`) - Required - Starting file index
- **len** (`int`) - Required - Total file count

### Description
Sets up progress bar dimensions. Must be called before `update()`.
```

--------------------------------

### Configure Fedora Package

Source: https://github.com/complexlogic/rsgain/blob/master/CMakeLists.txt

Sets CPack variables for building RPM packages, including file name, versioning, license, group, autoreqprov, and required packages.

```cmake
elseif (PACKAGE STREQUAL "RPM")
    set(CPACK_RPM_FILE_NAME "RPM-DEFAULT")
    if (COMMITS_SINCE_TAG AND COMMIT_HASH)
      set(CPACK_RPM_PACKAGE_VERSION "${PROJECT_VERSION}-r${COMMITS_SINCE_TAG}-${COMMIT_HASH}")
    endif ()
    set(CPACK_RPM_PACKAGE_LICENSE "BSD")
    set(CPACK_RPM_PACKAGE_GROUP "Applications/Multimedia")
    set(CPACK_RPM_PACKAGE_AUTOREQPROV 0)
    set(CPACK_RPM_PACKAGE_REQUIRES "libavcodec-free >= 6, libavformat-free >= 6, libswresample-free >= 6, libavutil-free >= 6, libebur128, zlib, inih")
```

--------------------------------

### Invoke Easy Mode Scan (PowerShell)

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

This command performs a recursive scan of your music library using recommended settings. Enclose paths with spaces in double quotes.

```powershell
rsgain easy "C:\path\to\music library"
```

--------------------------------

### Use Absolute Path for Files

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

When encountering 'File not found' errors, ensure you are using the absolute path to the file.

```bash
rsgain custom /absolute/path/to/file.flac
```

--------------------------------

### Easy Mode Scan with Multithreading

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/command-reference.md

Scans the music library using multiple threads for faster processing. Set to MAX for automatic thread count.

```bash
rsgain easy -m MAX /media/music
```

--------------------------------

### Apply Gain with Positive Gains Only Protection

Source: https://github.com/complexlogic/rsgain/blob/master/_autodocs/usage-examples.md

This is the default behavior in easy mode. Negative gains are applied as calculated, while positive gains are reduced if they would cause the peak to exceed full scale. This ensures files do not become louder than safe limits.

```bash
rsgain custom -c p *.flac
```

--------------------------------

### Enable Multithreaded Scanning (Bash)

Source: https://github.com/complexlogic/rsgain/blob/master/README.md

To speed up scans on large libraries, use the -m option followed by the desired number of threads. This is optimized for directories, not individual files.

```bash
rsgain easy -m 4 /path/to/music/library
```