Homebrew is a package manager for macOS — think of it as an "app store for developer tools". Open Terminal (you can find it in Applications > Utilities, or search for it with Spotlight) and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions. When it finishes, close and reopen Terminal.

To verify it worked, type:

brew --version

You should see something like Homebrew 4.x.x.

Still in Terminal, run:

brew install ffmpeg chromaprint

This installs ffmpeg (audio decoder) and fpcalc (audio fingerprinting tool). It may take a few minutes.

Verify both are installed:

ffmpeg -version
fpcalc -version

Both commands should print version information (not "command not found").

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen Terminal, then verify:

uv --version

git clone https://github.com/AndreaBonn/audio-filename-fixer.git
cd audio-filename-fixer
uv sync

cp .env.example config.env

Now open config.env with any text editor (TextEdit, VS Code, nano...) and set your music folder path:

nano config.env

Change MUSIC_DIR to point to your music folder, for example:

MUSIC_DIR=/Users/yourname/Music

Save and close (in nano: Ctrl+O, Enter, Ctrl+X).

uv run python music_tagger.py --dry-run --music-dir ~/Music

This runs in preview mode — it shows what would change without touching any file. If you see output listing your audio files, everything works.

When you're satisfied with the dry-run output:

uv run python music_tagger.py

macOS uses launchd instead of systemd. To run the tagger every night at 3:00 AM:

1. Create the file ~/Library/LaunchAgents/com.music-tagger.plist:

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.music-tagger.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.music-tagger</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd "$HOME/audio-filename-fixer" && source config.env && .venv/bin/python music_tagger.py</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>3</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <key>StandardOutPath</key>
    <string>/tmp/music-tagger.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/music-tagger.log</string>
</dict>
</plist>
EOF

2. Enable it:

launchctl load ~/Library/LaunchAgents/com.music-tagger.plist

3. To disable it later:

launchctl unload ~/Library/LaunchAgents/com.music-tagger.plist

1. Go to python.org/downloads and download the latest Python installer
2. Run the installer
3. Important: check the box "Add Python to PATH" at the bottom of the first screen
4. Click "Install Now"

To verify, open PowerShell (search for it in the Start menu) and type:

python --version

You should see Python 3.11.x or higher.

1. Go to git-scm.com/downloads/win and download the installer
2. Run it with default settings (click "Next" through all screens)

Verify in PowerShell:

git --version

1. Go to gyan.dev/ffmpeg/builds and download "ffmpeg-release-essentials.zip"
2. Extract the zip file to C:\ffmpeg (create this folder if it doesn't exist)
3. Inside you'll find a folder like ffmpeg-7.x-essentials_build — open it and go into the bin folder
4. Copy the full path to the bin folder (e.g., C:\ffmpeg\ffmpeg-7.1-essentials_build\bin)
5. Add it to your PATH:
   • Press Win + R, type sysdm.cpl, press Enter
   • Go to the "Advanced" tab, click "Environment Variables"
   • Under "User variables", find "Path", select it, click "Edit"
   • Click "New" and paste the path to the bin folder
   • Click "OK" on all windows

Close and reopen PowerShell, then verify:

ffmpeg -version

1. Go to acoustid.org/chromaprint and download the Windows package
2. Extract the zip file
3. Copy fpcalc.exe to the same bin folder where you put ffmpeg (e.g., C:\ffmpeg\ffmpeg-7.1-essentials_build\bin), so it's already in your PATH

Verify:

fpcalc -version

In PowerShell, run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen PowerShell, then verify:

uv --version

git clone https://github.com/AndreaBonn/audio-filename-fixer.git
cd audio-filename-fixer
uv sync

copy .env.example config.env

Open config.env with Notepad:

notepad config.env

Change MUSIC_DIR to point to your music folder, for example:

MUSIC_DIR=C:\Users\YourName\Music

Save and close Notepad.

In PowerShell, you need to load the environment variables from config.env before running:

Get-Content config.env | ForEach-Object {
    if ($_ -match '^([^#][^=]+)=(.*)$') {
        [Environment]::SetEnvironmentVariable($Matches[1], $Matches[2], 'Process')
    }
}

uv run python music_tagger.py --dry-run

This runs in preview mode — it shows what would change without touching any file.

Load the config and run (same two commands, without --dry-run):

Get-Content config.env | ForEach-Object {
    if ($_ -match '^([^#][^=]+)=(.*)$') {
        [Environment]::SetEnvironmentVariable($Matches[1], $Matches[2], 'Process')
    }
}

uv run python music_tagger.py

Tip: To avoid typing the config loading command every time, you can create a shortcut file. Save this as run.ps1 in the project folder:

# run.ps1 — Run the music tagger on Windows
Get-Content "$PSScriptRoot\config.env" | ForEach-Object {
    if ($_ -match '^([^#][^=]+)=(.*)$') {
        [Environment]::SetEnvironmentVariable($Matches[1], $Matches[2], 'Process')
    }
}
uv run python "$PSScriptRoot\music_tagger.py" @args

Then run it with: powershell -File run.ps1 or powershell -File run.ps1 --dry-run.

1. Open Task Scheduler (search for it in the Start menu)
2. Click "Create Basic Task" in the right panel
3. Name: Music Filename-Fixer & Auto-Tagger, click Next
4. Trigger: Daily, click Next
5. Set the time to 3:00 AM, click Next
6. Action: Start a program, click Next
7. Program: powershell
8. Arguments: -ExecutionPolicy Bypass -File "C:\Users\YourName\audio-filename-fixer\run.ps1"
9. Click Finish

To test it immediately: right-click the task and select "Run".