BitPerfectCore

Bit-perfect audio playback engine for macOS

BitPerfectCore is a Swift framework that provides true bit-perfect audio playback on macOS using CoreAudio HAL (Hardware Abstraction Layer). It enables direct hardware access, sample rate matching, and zero audio processing for pristine sound reproduction.

Features

• 🎯 True bit-perfect playback via CoreAudio HAL
• 🔧 Exclusive mode audio device access (hog mode)
• 📊 Automatic sample rate matching to source material
• 🎵 Multi-format support - FLAC, ALAC, WAV, AIFF
• ⚡ Zero audio processing pipeline - direct to hardware
• 🎼 Gapless playback with automatic track transitions
• 📋 Playlist management with queue control
• 🔁 Repeat & shuffle modes for flexible playback
• 🍎 Native macOS integration using Swift and CoreAudio
• 🎛️ Audio device management and configuration
• 📊 Metadata extraction from audio files

Philosophy

BitPerfectCore is built on the principle that audio playback should be transparent. The goal is to reproduce the original recording exactly as intended by the artist and engineer, without any coloration, processing, or degradation.

Core principles:

• Bit-perfect reproduction (what goes in = what comes out)
• Direct hardware access (bypass system audio processing)
• Sample rate matching (no resampling)
• Minimal latency and overhead
• Professional-grade reliability

Status

🚀 Active Development - Core features complete

Completed Phases:

• ✅ Phase 1: Core Audio Foundation
• ✅ Phase 2: Bit-Perfect Engine
• ✅ Phase 3: Format Support (FLAC, ALAC, WAV, AIFF)
• ✅ Phase 4: Gapless Playback & Playlist Management

Current Focus: Testing, optimization, and production refinement

See ROADMAP.md for detailed development plans and CHANGELOG.md for version history.

Part of the Perfecta Ecosystem

BitPerfectCore is the audio engine that powers the Perfecta music player:

• Perfecta - The perfect music player for macOS
• BitPerfectCore - The audio engine (this repo)
• RoomTone - The visual companion app

Tagline: "Play me perfect"

Technical Overview

BitPerfectCore provides a high-level Swift API for bit-perfect audio playback while handling the complexity of CoreAudio HAL under the hood.

Key components:

• Audio Device Manager - Enumerate and configure audio devices
• Sample Rate Matcher - Automatically match device sample rate to source
• Bit-Perfect Engine - Direct audio rendering without processing
• Format Decoder - Support for multiple lossless formats
• Buffer Manager - Efficient audio buffer handling

Requirements

• macOS 10.15+ (Catalina)
• Xcode 15.0+
• Swift 5.9+
• Apple Silicon or Intel Mac

Installation

Swift Package Manager

Add BitPerfectCore to your project via SPM:

dependencies: [
    .package(url: "https://github.com/marioarce/BitPerfectCore.git", from: "0.1.0")
]

Usage

As a Library

import BitPerfectCore

// Initialize the audio engine
let engine = BitPerfectEngine()

// Configure for bit-perfect playback
try engine.configure(
    device: audioDevice,
    sampleRate: 96000,
    bitDepth: 24
)

// Play audio file
try engine.play(url: audioFileURL)

Command-Line Testing Tool

BitPerfectCore includes a CLI tool for testing and debugging:

# List all audio devices
swift run BitPerfectCLI devices

# Show device information
swift run BitPerfectCLI info "Built-in Output"

# Test sample rate configuration
swift run BitPerfectCLI test-samplerate 96000

# Show default device
swift run BitPerfectCLI default

See CLI_USAGE.md for complete documentation.

Documentation

• ARCHITECTURE.md - Technical architecture and design
• ROADMAP.md - Development roadmap and milestones
• CONTRIBUTING.md - Contribution guidelines

License

MIT License - see LICENSE file for details

Author

Mario Alberto Arce - Costa Rica 🇨🇷

Acknowledgments

Built with passion for music and audio fidelity. Part of the journey to create the perfect music listening experience on macOS.