🎵 Linux Bluetooth Audio Enhancer

Adaptive Bluetooth Audio System for Linux | Адаптивная система Bluetooth-аудио для Linux

Language / Язык: 🇺🇸 English | 🇷🇺 Русский

Features • Installation • Usage • Configuration • Documentation

🇺🇸 English

✨ Features

🎯 Core Capabilities

🔄 Automatic Profile Switching - Smart system switches between HSP/HFP (for microphone) and A2DP (for high-quality music)
🎤 Microphone Functionality Preserved - Microphone is always available for transcription when needed
🎵 Maximum Playback Quality - Automatic switching to A2DP with SBC-XQ codec (stereo, 48kHz+) when listening to music
🚀 Production-ready - Reliable system with auto-start, error handling, and logging
🎚️ Bass Enhancement - Built-in support for low-frequency boost for deeper sound

🎧 What You Get

Mode	Profile	Quality	Usage
Microphone active	`headset-head-unit-msbc`	Mono, 16kHz	Transcription, calls
Music playing	`a2dp-sink-sbc_xq`	Stereo, 48kHz+	Music listening
Default	`headset-head-unit-msbc`	Mono, 16kHz	Microphone ready

🛠️ Technologies

PipeWire - Modern audio server for Linux
BlueZ - Official Bluetooth stack for Linux
PulseAudio API - Compatibility through PipeWire
Systemd - Service management and auto-start
Bash - Automation scripts

📦 Installation

Requirements

Linux (any distribution)
PipeWire (usually pre-installed in modern distributions)
BlueZ (Bluetooth stack)
Bash 4.0+
Bluetooth headphones with A2DP and HSP/HFP profile support

Compatibility

✅ Tested on: Major V (00:25:D1:40:96:05)
✅ Compatible with: Any Bluetooth headphones supporting:

A2DP profile (for high-quality playback)
HSP/HFP profile (for microphone functionality)

The system automatically detects available profiles of your device and uses optimal settings.

Quick Installation

# Clone the repository
git clone https://github.com/yourusername/linux-bluetooth-audio-enhancer.git
cd linux-bluetooth-audio-enhancer

# Run installation (for your device)
chmod +x install.sh
./install.sh

# Or specify your device MAC address
MAC_ADDRESS="AA:BB:CC:DD:EE:FF" ./install.sh

What Installation Does

✅ Copies monitoring script to ~/.local/bin/
✅ Creates PipeWire configuration for maximum quality
✅ Sets up systemd user service for auto-start
✅ Applies settings and starts the service

🎮 Usage

Automatic Operation

After installation, the system works automatically:

On system boot - Service starts automatically
When headphones connect - System detects device and starts monitoring
When music plays - Automatically switches to A2DP for high quality
When microphone is used - Automatically switches back to HSP/HFP

Manual Control

# Check status
systemctl --user status bluetooth-profile-manager.service

# View logs (systemd)
journalctl --user -u bluetooth-profile-manager.service -f

# View script logs
tail -f ~/.local/share/bluetooth-profile-manager.log

# Restart service
systemctl --user restart bluetooth-profile-manager.service

# Stop service
systemctl --user stop bluetooth-profile-manager.service

⚙️ Configuration

Device MAC Address Setup

By default, the system is configured for device 00:25:D1:40:96:05 (Major V - tested).

Method 1: During Installation (Recommended)

MAC_ADDRESS="AA:BB:CC:DD:EE:FF" ./install.sh

Method 2: After Installation

Edit the service file:

nano ~/.config/systemd/user/bluetooth-profile-manager.service

Change the line:

Environment="MAC_ADDRESS=AA:BB:CC:DD:EE:FF"

Then restart the service:

systemctl --user daemon-reload
systemctl --user restart bluetooth-profile-manager.service

Method 3: Via Environment Variable

export MAC_ADDRESS="AA:BB:CC:DD:EE:FF"
systemctl --user restart bluetooth-profile-manager.service

Spotify Optimization

For maximum sound quality in Spotify:

./scripts/optimize-spotify.sh

This will configure:

Maximum streaming quality (veryhigh)
Built-in Spotify equalizer for deep bass
PipeWire optimization for Spotify

More details: docs/SPOTIFY.md

Bass Enhancement

For deeper bass:

./scripts/setup-bass.sh

This will create an EasyEffects preset for low-frequency boost.

More details: docs/AUDIO_ENHANCEMENT.md

📚 Documentation

Project Structure

linux-bluetooth-audio-enhancer/
├── README.md                    # Main documentation
├── install.sh                   # Installation script
├── CONTRIBUTING.md              # Contributor guide
├── .gitignore                  # Git ignored files
├── scripts/                    # Project scripts
│   ├── bluetooth-profile-manager.sh    # Main monitoring script
│   ├── optimize-spotify.sh             # Spotify optimization
│   ├── configure-spotify-equalizer.sh  # Spotify equalizer setup
│   └── setup-bass.sh                   # Bass enhancement
└── docs/                       # Documentation
    ├── SPOTIFY.md              # Spotify optimization guide
    ├── AUDIO_ENHANCEMENT.md    # Audio quality enhancement
    └── CHANGELOG.md            # Change history

Detailed Documentation

SPOTIFY.md - Complete guide to Spotify optimization for maximum quality
AUDIO_ENHANCEMENT.md - Sound enhancement, bass setup, EasyEffects usage
CHANGELOG.md - Complete system change history
CONTRIBUTING.md - How to contribute to the project

🔍 How It Works

Profile Switching Logic

┌─────────────────────────────────────┐
│  Monitoring every second            │
└──────────────┬──────────────────────┘
               │
       ┌───────▼────────┐
       │ Microphone     │
       │ active?        │
       └───┬────────┬───┘
           │        │
          YES      NO
           │        │
           │    ┌───▼──────────┐
           │    │ Playback      │
           │    │ active?       │
           │    └───┬──────┬───┘
           │        │      │
           │       YES    NO
           │        │      │
           ▼        ▼      ▼
    ┌──────────┐ ┌──────┐ ┌──────────┐
    │ HSP/HFP  │ │ A2DP │ │ HSP/HFP  │
    │(microphone)│ │(music)│ │(default) │
    └──────────┘ └──────┘ └──────────┘

Technical Details

Activity Monitoring - Script checks microphone and playback state via pactl
Debounce Mechanism - Switching occurs only after 2 seconds of stable state
Error Handling - On errors, system returns to safe profile (HSP/HFP)
Logging - All actions are logged for diagnostics

🐛 Troubleshooting

Problem: Service Won't Start

# Check logs
journalctl --user -u bluetooth-profile-manager.service -n 50

# Check if PipeWire is running
systemctl --user status pipewire-pulse.service

# Check device connection
bluetoothctl info 00:25:D1:40:96:05

Problem: Profile Won't Switch

# Check current profile
pactl list cards | grep -A 20 "bluez_card" | grep "Active Profile"

# Check script logs
tail -f ~/.local/share/bluetooth-profile-manager.log

# Manual switch for testing
pactl set-card-profile bluez_card.00_25_D1_40_96_05 a2dp-sink-sbc_xq

Problem: Microphone Unavailable

This is normal if device is in A2DP mode. System will automatically switch back when microphone is activated.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

See CONTRIBUTING.md for details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

PipeWire - Wonderful audio server
BlueZ - Bluetooth stack for Linux
EasyEffects - Excellent DSP processing tool

📊 Project Statistics

Version: 1.0.0
Status: Production-ready ✅
Supported Devices: Bluetooth headphones with A2DP and HSP/HFP support
Tested on: Major V (00:25:D1:40:96:05)

🇷🇺 Русский

✨ Основные возможности

🎯 Ключевые функции

🔄 Автоматическое переключение профилей - Умная система переключается между HSP/HFP (для микрофона) и A2DP (для высокого качества музыки)
🎤 Сохранение функциональности микрофона - Микрофон всегда доступен для транскрибации, когда нужен
🎵 Максимальное качество воспроизведения - Автоматическое переключение на A2DP с кодеком SBC-XQ (стерео, 48kHz+) при прослушивании музыки
🚀 Production-ready - Надежная система с автозапуском, обработкой ошибок и логированием
🎚️ Настройка баса - Встроенная поддержка усиления низких частот для более глубокого звучания

🎧 Что вы получаете

Режим	Профиль	Качество	Использование
Микрофон активен	`headset-head-unit-msbc`	Моно, 16kHz	Транскрибация, звонки
Музыка играет	`a2dp-sink-sbc_xq`	Стерео, 48kHz+	Прослушивание музыки
По умолчанию	`headset-head-unit-msbc`	Моно, 16kHz	Готовность микрофона

🛠️ Технологии

PipeWire - Современный аудио сервер для Linux
BlueZ - Официальный Bluetooth стек Linux
PulseAudio API - Совместимость через PipeWire
Systemd - Управление сервисами и автозапуск
Bash - Скрипты автоматизации

📦 Установка

Требования

Linux (любой дистрибутив)
PipeWire (обычно предустановлен в современных дистрибутивах)
BlueZ (Bluetooth стек)
Bash 4.0+
Bluetooth наушники с поддержкой A2DP и HSP/HFP профилей

Совместимость

✅ Протестировано на: Major V (00:25:D1:40:96:05)
✅ Совместимо с: Любыми Bluetooth наушниками, поддерживающими:

A2DP профиль (для высокого качества воспроизведения)
HSP/HFP профиль (для работы микрофона)

Система автоматически определяет доступные профили вашего устройства и использует оптимальные настройки.

Быстрая установка

# Клонировать репозиторий
git clone https://github.com/yourusername/linux-bluetooth-audio-enhancer.git
cd linux-bluetooth-audio-enhancer

# Запустить установку (для вашего устройства)
chmod +x install.sh
./install.sh

# Или указать MAC адрес вашего устройства
MAC_ADDRESS="AA:BB:CC:DD:EE:FF" ./install.sh

Что делает установка

✅ Копирует скрипт мониторинга в ~/.local/bin/
✅ Создает конфигурацию PipeWire для максимального качества
✅ Настраивает systemd user service для автозапуска
✅ Применяет настройки и запускает сервис

🎮 Использование

Автоматическая работа

После установки система работает автоматически:

При загрузке системы - Сервис запускается автоматически
При подключении наушников - Система определяет устройство и начинает мониторинг
При воспроизведении музыки - Автоматически переключается на A2DP для высокого качества
При использовании микрофона - Автоматически переключается обратно на HSP/HFP

Ручное управление

# Проверить статус
systemctl --user status bluetooth-profile-manager.service

# Просмотр логов (systemd)
journalctl --user -u bluetooth-profile-manager.service -f

# Просмотр логов скрипта
tail -f ~/.local/share/bluetooth-profile-manager.log

# Перезапустить сервис
systemctl --user restart bluetooth-profile-manager.service

# Остановить сервис
systemctl --user stop bluetooth-profile-manager.service

⚙️ Конфигурация

Настройка MAC-адреса устройства

По умолчанию система настроена для устройства 00:25:D1:40:96:05 (Major V - протестировано).

Способ 1: При установке (рекомендуется)

MAC_ADDRESS="AA:BB:CC:DD:EE:FF" ./install.sh

Способ 2: После установки

Отредактируйте файл сервиса:

nano ~/.config/systemd/user/bluetooth-profile-manager.service

Измените строку:

Environment="MAC_ADDRESS=AA:BB:CC:DD:EE:FF"

Затем перезапустите сервис:

systemctl --user daemon-reload
systemctl --user restart bluetooth-profile-manager.service

Способ 3: Через переменную окружения

export MAC_ADDRESS="AA:BB:CC:DD:EE:FF"
systemctl --user restart bluetooth-profile-manager.service

Оптимизация Spotify

Для максимального качества звука в Spotify:

./scripts/optimize-spotify.sh

Это настроит:

Максимальное качество стриминга (veryhigh)
Встроенный эквалайзер Spotify для глубокого баса
Оптимизацию PipeWire для Spotify

Подробнее: docs/SPOTIFY.md

Настройка баса

Для более глубокого баса:

./scripts/setup-bass.sh

Это создаст пресет EasyEffects для усиления низких частот.

Подробнее: docs/AUDIO_ENHANCEMENT.md

📚 Документация

Структура проекта

linux-bluetooth-audio-enhancer/
├── README.md                    # Основная документация
├── install.sh                   # Скрипт установки
├── CONTRIBUTING.md              # Руководство для контрибьюторов
├── .gitignore                  # Игнорируемые файлы Git
├── scripts/                    # Скрипты проекта
│   ├── bluetooth-profile-manager.sh    # Основной скрипт мониторинга
│   ├── optimize-spotify.sh             # Оптимизация Spotify
│   ├── configure-spotify-equalizer.sh  # Настройка эквалайзера Spotify
│   └── setup-bass.sh                   # Настройка баса
└── docs/                       # Документация
    ├── SPOTIFY.md              # Руководство по оптимизации Spotify
    ├── AUDIO_ENHANCEMENT.md    # Улучшение качества звука
    └── CHANGELOG.md            # История изменений

Подробная документация

SPOTIFY.md - Полное руководство по оптимизации Spotify для максимального качества
AUDIO_ENHANCEMENT.md - Улучшение звука, настройка баса, использование EasyEffects
CHANGELOG.md - История всех изменений системы
CONTRIBUTING.md - Как внести вклад в проект

🔍 Как это работает

Логика переключения профилей

┌─────────────────────────────────────┐
│  Мониторинг каждую секунду          │
└──────────────┬──────────────────────┘
               │
       ┌───────▼────────┐
       │ Микрофон       │
       │ активен?       │
       └───┬────────┬───┘
           │        │
          ДА       НЕТ
           │        │
           │    ┌───▼──────────┐
           │    │ Воспроизве-  │
           │    │ дение активно?│
           │    └───┬──────┬───┘
           │        │      │
           │       ДА     НЕТ
           │        │      │
           ▼        ▼      ▼
    ┌──────────┐ ┌──────┐ ┌──────────┐
    │ HSP/HFP  │ │ A2DP │ │ HSP/HFP  │
    │ (микрофон)│ │(музыка)│ │(по умолч.)│
    └──────────┘ └──────┘ └──────────┘

Технические детали

Мониторинг активности - Скрипт проверяет состояние микрофона и воспроизведения через pactl
Debounce механизм - Переключение происходит только после 2 секунд стабильного состояния
Обработка ошибок - При ошибках система возвращается к безопасному профилю (HSP/HFP)
Логирование - Все действия записываются в логи для диагностики

🐛 Устранение проблем

Проблема: Сервис не запускается

# Проверить логи
journalctl --user -u bluetooth-profile-manager.service -n 50

# Проверить, что PipeWire запущен
systemctl --user status pipewire-pulse.service

# Проверить подключение устройства
bluetoothctl info 00:25:D1:40:96:05

Проблема: Профиль не переключается

# Проверить текущий профиль
pactl list cards | grep -A 20 "bluez_card" | grep "Active Profile"

# Проверить логи скрипта
tail -f ~/.local/share/bluetooth-profile-manager.log

# Ручное переключение для теста
pactl set-card-profile bluez_card.00_25_D1_40_96_05 a2dp-sink-sbc_xq

Проблема: Микрофон недоступен

Это нормально, если устройство в режиме A2DP. Система автоматически переключится обратно при активации микрофона.

🤝 Вклад в проект

Мы приветствуем ваш вклад! Пожалуйста, не стесняйтесь отправлять Pull Request.

Подробнее: CONTRIBUTING.md

📝 Лицензия

Этот проект лицензирован под MIT License - см. файл LICENSE для деталей.

🙏 Благодарности

PipeWire - Замечательный аудио сервер
BlueZ - Bluetooth стек для Linux
EasyEffects - Отличный инструмент для DSP обработки

📊 Статистика проекта

Версия: 1.0.0
Статус: Production-ready ✅
Поддерживаемые устройства: Bluetooth наушники с поддержкой A2DP и HSP/HFP
Тестировано на: Major V (00:25:D1:40:96:05)

Made with ❤️ for Linux audio enthusiasts | Сделано с ❤️ для любителей качественного звука на Linux

⭐ If this project helped you, please give it a star! | ⭐ Если проект вам помог, поставьте звезду!

⬆ Back to Top | ⬆ Наверх

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

License

FUYOH666/linux-bluetooth-audio-enhancer

Folders and files

Latest commit

History

Repository files navigation