FineTune Documentation

Technical Documentation: ronitsingh10/FineTune

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

FineTune

Control the volume of every app independently, boost quiet ones up to 4x, route audio to different speakers, and shape your sound with EQ and headphone correction. Lives in your menu bar. Free and open-source.

Install Copy Chapter

Homebrew (recommended)

brew install --cask finetune

Manual — Download latest release

Quick Start Copy Chapter

1. Install FineTune and launch it from your Applications folder
2. Grant Screen & System Audio Recording permission when prompted
3. Click the FineTune icon in your menu bar. Apps playing audio appear automatically.

That's it. Adjust sliders, route audio, and explore EQ from the menu bar.

Tip: Want FineTune to auto-switch to a specific device when you connect it? Open edit mode (pencil icon) and drag it above the built-in speakers. This is a one-time setup. Your preferred order is saved permanently.

Features Copy Chapter

🎚 Volume Control Copy Section

• Per-app volume — Individual sliders and mute for each application
• Per-app volume boost — 2x / 3x / 4x gain presets
• Pinned apps — Keep apps visible in the menu bar even when they're not playing, so you can configure volume, EQ, and routing in advance
• Ignore apps — Completely disengage FineTune from specific apps. Tears down the audio tap so the app returns to normal macOS audio
• Scroll-wheel volume — Hover any slider in the popup, the HUD, or the EQ panel and scroll to adjust.

⌨️ Keyboard Copy Section

• Global volume hotkeys — Bind your own keys to App Volume Up, App Volume Down, and App Mute from Settings → Shortcuts. The "app" is whichever is currently making sound, so volume-down while a YouTube tab plays behind a foreground Terminal turns down YouTube, not the terminal. If nothing is audible, the hotkey falls through to the frontmost app.
• Toggle the popup from anywhere — Bind a hotkey to Toggle FineTune Popup and the menu bar opens or closes on demand, including from full-screen apps.
• Configurable step size — Pick Coarse / Normal / Fine / Extra-Fine under Settings → Shortcuts → Volume Step. The same setting governs the F10–F12 media keys, the global hotkeys, and the popup's arrow-key navigation.
• Hold to ramp, auto-unmute on volume-up — Holding App Volume Up or Down emits repeats the way macOS does for arrow keys. Volume-up while muted unmutes and sets the new level in one keystroke.
• Drive the popup with the keyboard — Once the popup is open, ↑ / ↓ move between rows, ← / → adjusts the focused row's volume (Shift = 2× step), M toggles mute, Return / Space activates, Tab switches between Output and Input device tabs, Esc closes. The focused row autoscrolls to center as you arrow through.

🔀 Audio Routing Copy Section

• Multi-device output — Route audio to multiple devices simultaneously
• Audio routing — Send apps to different outputs or follow system default
• Device priority — Choose which device FineTune switches to when a new device connects; auto-fallback on disconnect
• Auto-restore — When a device reconnects, apps automatically return to it with their volume, routing, and EQ intact

🎛 EQ & Correction Copy Section

• 10-band EQ — 20 presets across 5 categories
• User EQ presets — Save, rename, and manage custom EQ configurations per app
• AutoEQ headphone correction — Search thousands of headphone profiles or import your own ParametricEQ.txt files for per-device frequency response correction
• Loudness compensation — Automatic bass and treble correction at low volumes using ISO 226:2023 equal-loudness contours, with real-time level management to keep perceived loudness consistent

🖥 Devices & System Copy Section

• Input device control — Monitor and adjust microphone levels
• Alert volume — Control macOS notification and alert volume from settings
• Smart volume backend — FineTune auto-picks hardware, DDC, or software volume per device. If the hardware slider on a USB DAC or HDMI output doesn't actually control level, force software volume from the device inspector and FineTune remembers the choice for that device
• Device inspector — Tap the info button on any device row for sample rate (with picker), transport, UID copy, hog-mode banner, and the software-volume override
• Hide devices — Eye toggle in edit mode hides output and input devices you don't want in the list, mirroring the app-hide flow
• Bluetooth device management — Connect paired devices directly from the menu bar
• Monitor speaker control — Adjust volume on external displays via DDC
• Media keys & Volume HUD — Opt-in F10–F12 control for the default output device, with a Tahoe-style or Classic-style on-screen HUD. The write goes through FineTune's volume pipeline, so keys keep working on USB interfaces and HDMI outputs where macOS's own keys are greyed out because the hardware slider is broken.
• Dynamic menu bar icon — Pick from four styles in Settings (Default, Speaker, Waveform, Equalizer). The Speaker style tracks volume live (zero / low / mid / high glyphs) and switches to a slashed speaker when muted. All styles briefly flash the new output's SF Symbol on device switch. Changing style applies instantly, no relaunch required.
• Menu bar app — Lightweight, always accessible
• URL schemes — Automate volume, mute, device routing, and more from scripts

🎨 Appearance Copy Section

• Light or Dark theme — Settings → General → Theme matches macOS or locks FineTune to Light or Dark. The menu bar popup, every popover, and the volume HUD switch immediately.
• Popup density — Settings → General → Popup Size picks Compact / Comfortable / Spacious with a live tile preview. Compact fits more apps on small screens; Spacious gives bigger hit areas for trackpads.

Documentation Copy Chapter

• AutoEQ & Headphone Correction — Apply frequency correction from the AutoEQ project, import EqualizerAPO profiles, or browse autoeq.app
• URL Schemes — Automate FineTune from Terminal, Shortcuts, Raycast, or scripts
• Troubleshooting — Permission issues, missing apps, audio problems

Contributing Copy Chapter

• Star this repo — Help others discover FineTune
• Report bugs — Open an issue
• Contribute code — See CONTRIBUTING.md

Build from Source Copy Section

git clone https://github.com/ronitsingh10/FineTune.git
cd FineTune
open FineTune.xcodeproj

Requirements Copy Chapter

• macOS 15.0 (Sequoia) or later
• Audio capture permission (prompted on first launch)

Support Copy Chapter

FineTune is free and open source, forever. If it made your day a little easier, you can buy me a coffee — but genuinely not expected 🙏

License Copy Chapter

GPL v3

Guide Autoeq (`guide/autoeq.md`) Copy Section

AutoEQ & Headphone Correction

English · 简体中文

FineTune can apply headphone-specific frequency response corrections using profiles from the AutoEQ project. This compensates for your headphones' natural frequency curve, giving you a flatter, more accurate sound.

How It Works Copy Chapter

Every pair of headphones colors the sound differently. Some boost bass, others are harsh in the treble. AutoEQ measures these deviations and generates corrective EQ filters. FineTune applies these filters per-device, so each pair of headphones gets its own correction profile.

Corrections are applied on top of FineTune's 10-band EQ, so you can still tweak the sound to your taste after applying a profile.

Browse Built-in Profiles Copy Chapter

1. Click the wand icon next to any headphone device in FineTune
2. Search for your headphone model by name
3. Select a profile. It's applied immediately.

Profiles are fetched on demand from the AutoEQ database and cached locally for offline use. The database includes thousands of headphones from major brands (Sony, Sennheiser, Apple, Bose, Audio-Technica, Beyerdynamic, and more).

Tip: If your exact model isn't listed, try searching for the product line — similar models often share frequency response characteristics.

Import Custom Profiles Copy Chapter

If you have a custom measurement or want to use a profile from another source:

1. Click "Import ParametricEQ.txt..." at the bottom of the AutoEQ panel
2. Select your .txt file
3. The profile is imported and applied to the selected device
4. Use the Correction switch in the picker to A/B the profile without removing it

FineTune accepts EqualizerAPO ParametricEQ.txt files:

Preamp: -6.2 dB
Filter 1: ON PK Fc 100 Hz Gain -2.3 dB Q 1.41
Filter 2: ON LSC Fc 105 Hz Gain 7.0 dB Q 0.71
Filter 3: ON HSC Fc 8000 Hz Gain 2.1 dB Q 0.71

Supported Filter Types Copy Section

Up to 10 filters per profile. The Preamp line sets a global gain offset to prevent clipping.

Where to Get Profiles Copy Chapter

• Built-in search — The easiest way. Thousands of headphones are available directly in FineTune.
• autoeq.app — Web-based tool with more options. Select EqualizerAPO ParametricEq as the equalizer app, download the file, and import it into FineTune.
• AutoEQ GitHub — The full repository of measurements and generated profiles.
• Custom measurements — If you've measured your headphones yourself (e.g., with a MiniDSP EARS or similar), you can create a ParametricEQ.txt file in any text editor following the format above.

Managing Profiles Copy Chapter

• Each device remembers its assigned profile independently
• To temporarily bypass a profile, click the wand icon and turn Correction off
• To remove a profile entirely, click the wand icon and select No correction
• Favorite frequently-used profiles for quick access with the star icon — favorited profiles appear at the top of search results and are shown when the search field is empty

Guide Autoeq.Zh CN (`guide/autoeq.zh-CN.md`) Copy Section

AutoEQ 与耳机校正

English · 简体中文

本翻译由社区维护，更新可能晚于英文版。最新内容请以 English version 为准。
This translation is community-maintained and may lag the English version. See the English version for the most current information.

FineTune 可以使用来自 AutoEQ 项目的耳机专属频响校正配置。它会针对你耳机本身的频率曲线做补偿，让声音更平直、更准确。

工作原理 Copy Chapter

每副耳机对声音的染色都不一样：有的低频偏多，有的高频刺耳。AutoEQ 测量出这些偏离，并生成对应的修正 EQ 滤波器。FineTune 会按设备分别应用这些滤波器，所以每副耳机都拥有自己独立的校正配置。

校正会叠加在 FineTune 的 10 段 EQ 之上，因此应用一份配置之后，你仍然可以按个人口味继续微调。

浏览内置配置 Copy Chapter

1. 点击 FineTune 中任一耳机设备旁的 魔棒图标
2. 按型号搜索你的耳机
3. 选中一个配置，立即生效

配置会按需从 AutoEQ 数据库拉取，并在本地缓存以便离线使用。数据库覆盖了主流厂商上千款耳机（Sony、Sennheiser、Apple、Bose、Audio-Technica、Beyerdynamic 等）。

小贴士： 如果你的具体型号没出现在列表里，可以试着搜索同一产品线 —— 相近型号的频响特性往往相近。

导入自定义配置 Copy Chapter

如果你有自己的测量结果，或者想用其他来源的配置：

1. 点击 AutoEQ 面板底部的 "Import ParametricEQ.txt..."
2. 选择你的 .txt 文件
3. 配置会被导入并应用到当前选中的设备
4. 使用选择器中的 Correction 开关，可以在不删除配置的前提下做 A/B 对比

FineTune 接受 EqualizerAPO 的 ParametricEQ.txt 文件：

Preamp: -6.2 dB
Filter 1: ON PK Fc 100 Hz Gain -2.3 dB Q 1.41
Filter 2: ON LSC Fc 105 Hz Gain 7.0 dB Q 0.71
Filter 3: ON HSC Fc 8000 Hz Gain 2.1 dB Q 0.71

支持的滤波器类型 Copy Section

每份配置最多 10 个滤波器。Preamp 行设定一个全局增益偏移，用于避免削波。

在哪里获取配置 Copy Chapter

• 内置搜索 —— 最方便的方式。FineTune 直接内置了上千款耳机
• autoeq.app —— 网页版工具，选项更丰富。把 equalizer app 选成 EqualizerAPO ParametricEq，下载文件后导入 FineTune 即可
• AutoEQ GitHub —— 完整的测量数据与生成配置仓库
• 自行测量 —— 如果你自己测量了耳机（例如用 MiniDSP EARS 之类的设备），可以按上面的格式在任意文本编辑器里手写一个 ParametricEQ.txt 文件

管理配置 Copy Chapter

• 每台设备都会独立记住自己绑定的配置
• 要临时旁路一个配置，点击魔棒图标并把 Correction 关掉
• 要彻底移除一个配置，点击魔棒图标并选择 No correction
• 用星标图标把常用的配置加入收藏，方便快速访问 —— 收藏过的配置会出现在搜索结果顶部，搜索框为空时也会一并显示

Guide Troubleshooting (`guide/troubleshooting.md`) Copy Section

Troubleshooting

No sound / audio stops working Copy Chapter

FineTune requires the Screen & System Audio Recording permission to capture and route app audio.

1. Open System Settings → Privacy & Security → Screen & System Audio Recording
2. Find FineTune in the list and enable it
3. Restart FineTune — the permission doesn't take effect until relaunch

If you previously denied the permission prompt, you'll need to enable it manually from System Settings.

App not appearing Copy Chapter

FineTune only shows apps that are actively playing audio. If an app isn't visible:

• Make sure the app is actually producing sound (start playback)
• Check if the app is hidden. Open edit mode (pencil icon) and look for the eye icon next to the app name. A crossed-out eye means the app is being ignored.
• Some apps use helper processes for audio. Try restarting the app.

App causing audio issues Copy Chapter

Some apps don't work well with CoreAudio process taps — particularly audio processors, DAWs, VoIP tools, and apps that do their own low-level audio routing. Symptoms include distorted audio, echo, or audio cutting out.

Fix: Open edit mode (pencil icon) and click the eye icon to ignore the problematic app. This tears down the process tap entirely for that app, so it goes back to normal macOS audio routing.

Common apps that may need to be ignored:

• Audio Hijack, Loopback, and other Rogue Amoeba apps
• Some VoIP/conferencing tools with custom audio engines
• FaceTime, WhatsApp, and other calling apps (tapping can break echo cancellation, causing volume ducking)

Volume slider not working Copy Chapter

There are two cases.

Per-app slider. Some apps use helper processes to play audio rather than the main app process, so the slider you see might be controlling the wrong process. Try restarting the app. If the issue persists, check edit mode to see if the app appears as a different process name.

Per-device slider. When you open a device, FineTune picks a volume backend automatically:

• Hardware: the device reports a native volume control (most USB DACs, AirPods, built-in speakers).
• DDC: an external display that responds to the monitor-control protocol.
• Software: FineTune attenuates inside its own audio graph.

Auto-detection gets it right for most devices, but some USB DACs and HDMI/DisplayPort outputs advertise a hardware slider that doesn't actually move the output level. If the device slider doesn't change the volume, open the device inspector (the info button on the device row) and turn on Software volume. FineTune remembers the choice per device. The toggle is hidden when auto-detect already picked Software, because there's no alternative backend to switch to.

Audio device not switching automatically Copy Chapter

FineTune uses a device priority list to decide which output device to use. When a device connects, FineTune only switches to it if it's ranked higher than the current device. When a device disconnects, FineTune falls back to the next highest-priority device that's still connected.

By default, devices are added to the bottom of the list in the order they're first seen. Since your Mac's built-in speakers are always connected, they end up at the top (highest priority), so FineTune won't auto-switch to headphones, external speakers, or other devices when they connect.

This is a one-time setup. Once you set your preferred order, it's saved permanently and works across app restarts.

How to reorder:

1. Click the pencil icon in the menu bar popup to enter edit mode
2. Drag devices to reorder, or click the priority number and type a new position
3. Click the checkmark to exit edit mode — your order is saved

The device at position 1 has the highest priority. FineTune will always prefer the highest-priority device that's currently connected.

Input and output devices have separate priority lists — switch between them using the tabs in edit mode.

Note: For AirPods, taking them out of your ears and putting them back in (without the case) is handled by macOS Automatic Ear Detection. FineTune doesn't interfere with that.

Input devices not showing Copy Chapter

FineTune's input device monitoring requires separate microphone permission.

1. Open System Settings → Privacy & Security → Microphone
2. Find FineTune and enable it
3. Restart FineTune

Media keys don't control FineTune Copy Chapter

Media keys (F10 / F11 / F12) are opt-in and require the Accessibility permission so FineTune can observe the keystrokes.

1. Open System Settings → Privacy & Security → Accessibility
2. Enable FineTune in the list. If it's already on, toggle it off and back on to clear a rare permission-bootstrap race.
3. Open FineTune Settings → Media Keys & HUD, turn on Control volume with media keys, and pick a HUD style (Tahoe or Classic) or disable the HUD

If the keys still don't work right after launch, a WindowServer handoff can briefly swallow the first keypress. Try once more; subsequent presses are reliable.

Volume HUD not appearing Copy Chapter

• Check Settings → Media Keys & HUD. The HUD is off by default and has to be enabled separately from the media-key toggle.
• Switch HUD styles if one isn't rendering. Tahoe uses macOS 26's system HUD look; Classic matches the older translucent rounded-rect style.

EQ not applying / sounds the same Copy Chapter

• The EQ is enabled by default. Check that the toggle switch in the EQ panel header is on.
• The default preset is Flat (all bands at 0 dB), which makes no audible changes. Select a different preset or adjust the bands manually.
• EQ is per-app, not per-device. Make sure you're adjusting the EQ for the correct app.
• If using AutoEQ headphone correction, that's separate from the 10-band EQ. Verify a profile is assigned to the correct device via the wand icon

Audio quality sounds degraded Copy Chapter

• Check if volume boost is set above 1x — high boost levels can cause clipping on loud passages
• If using EQ, large boosts across multiple bands can push levels too high. Try pulling bands down instead of boosting others up.
• AutoEQ profiles include a preamp gain reduction to prevent clipping; manual EQ does not, so be mindful of total gain
• Try resetting the app to defaults: open "finetune://reset" in Terminal

Guide Url Schemes (`guide/url-schemes.md`) Copy Section

URL Schemes

Control FineTune from Terminal, shell scripts, Shortcuts, Raycast, or any app that can open URLs. This makes it easy to automate volume changes, build keyboard shortcuts, or integrate FineTune into your workflow.

Actions Copy Chapter

Examples Copy Chapter

# Set Spotify to 50% volume
open "finetune://set-volumes?app=com.spotify.client&volume=50"

# Set different volumes for different apps at once
open "finetune://set-volumes?app=com.spotify.client&volume=80&app=com.hnc.Discord&volume=40"

# Mute multiple apps at once
open "finetune://set-mute?app=com.spotify.client&muted=true&app=com.apple.Music&muted=true"

# Step Discord volume down
open "finetune://step-volume?app=com.hnc.Discord&direction=down"

# Route an app to a specific device
open "finetune://set-device?app=com.spotify.client&device=YOUR_DEVICE_UID"

# Reset everything
open "finetune://reset"

Use Cases Copy Chapter

Meeting mode — Mute everything except your video call app:

open "finetune://set-mute?app=com.spotify.client&muted=true&app=com.apple.Music&muted=true"

Focus playlist — Set music to a low background level and silence notifications:

open "finetune://set-volumes?app=com.spotify.client&volume=30&app=com.apple.systemuiserver&volume=0"

Gaming setup — Boost a game and lower Discord:

open "finetune://set-volumes?app=com.game.example&volume=400&app=com.hnc.Discord&volume=40"

These commands work in Terminal, shell scripts, Automator, Raycast script commands, macOS Shortcuts (using "Open URL"), and any other tool that can open URLs.

Finding Bundle IDs Copy Chapter

App names shown in FineTune map to bundle IDs. Common ones:

To find any app's bundle ID:

osascript -e 'id of app "App Name"'

Finding Device UIDs Copy Chapter

In FineTune, click the pencil icon to enter edit mode, tap the info button on a device row to open the device inspector, then click the copy button next to the UID to put it on the clipboard.

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~5966 tokens
• Canonical Reference: https://codewiki.google/github.com/ronitsingh10/FineTune