Contributing to BitPerfectCore

Thank you for your interest in contributing to BitPerfectCore! This document provides guidelines and information for contributors.

Project Status

Current Phase: Active Development

BitPerfectCore is an open-source project actively working toward v1.0. We welcome community contributions as we refine the core architecture and expand format support.

Getting Started

Prerequisites

macOS 13.0+ (Ventura)
Xcode 15.0+
Swift 5.9+
Git
Familiarity with CoreAudio and audio programming

Development Setup

Clone the repository:

git clone https://github.com/marioarce/BitPerfectCore.git
cd BitPerfectCore

Open in Xcode:

open Package.swift

Build the project:

swift build

Run tests:

swift test

Development Workflow

Branch Strategy

main - Stable, production-ready code
develop - Integration branch for features
feature/* - Feature development branches
bugfix/* - Bug fix branches
hotfix/* - Critical fixes for production

Workflow Steps

Create a branch:

git checkout -b feature/your-feature-name

Make your changes:

Write clean, documented code
Follow Swift style guidelines
Add tests for new functionality

Commit your changes:

git add .
git commit -m "feat: add your feature description"

Push and create PR:

git push origin feature/your-feature-name

Coding Standards

Swift Style Guide

We follow the Swift API Design Guidelines with these additions:

Naming:

Use clear, descriptive names
Prefer clarity over brevity
Use camelCase for properties and methods
Use PascalCase for types

Example:

// Good
func configureAudioDevice(withSampleRate sampleRate: Double) throws

// Avoid
func cfgDev(sr: Double) throws

Code Organization:

Group related functionality with // MARK: -
Order: properties, initializers, public methods, private methods
Keep files focused and under 500 lines when possible

Documentation:

All public APIs must have documentation comments
Use DocC format for documentation
Include usage examples for complex APIs

Example:

/// Configures the audio device for bit-perfect playback.
///
/// This method sets the device sample rate and configures the audio
/// stream for exclusive access to ensure bit-perfect output.
///
/// - Parameters:
///   - device: The audio device to configure
///   - sampleRate: The desired sample rate in Hz
/// - Throws: `BitPerfectError.deviceNotAvailable` if the device cannot be accessed
/// - Returns: The configured audio stream
func configure(device: AudioDevice, sampleRate: Double) throws -> AudioStream

Code Quality

Requirements:

All code must compile without warnings
All tests must pass
New features must include unit tests
Code coverage should not decrease
No force unwrapping (!) in production code
Proper error handling (no try!)

Performance:

Audio thread must be lock-free
Minimize allocations in hot paths
Profile performance-critical code
Document performance characteristics

Testing

Test Requirements

Unit Tests: Test individual components in isolation
Integration Tests: Test component interactions
Performance Tests: Verify performance targets
Validation Tests: Verify bit-perfect output

Writing Tests

import XCTest
@testable import BitPerfectCore

final class AudioDeviceManagerTests: XCTestCase {
    var deviceManager: AudioDeviceManager!
    
    override func setUp() {
        super.setUp()
        deviceManager = AudioDeviceManager()
    }
    
    func testEnumerateDevices() throws {
        let devices = deviceManager.enumerateDevices()
        XCTAssertFalse(devices.isEmpty, "Should find at least one audio device")
    }
    
    func testDefaultDevice() throws {
        let device = deviceManager.defaultDevice()
        XCTAssertNotNil(device, "Should have a default audio device")
    }
}

Running Tests

# Run all tests
swift test

# Run specific test
swift test --filter AudioDeviceManagerTests

# Run with coverage
swift test --enable-code-coverage

Commit Message Format

We use Conventional Commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
perf: - Performance improvements
test: - Test additions or changes
chore: - Build process or auxiliary tool changes

Examples

feat(decoder): add FLAC decoder implementation

Implement FLAC decoder using libFLAC for lossless audio playback.
Includes support for all FLAC bit depths and sample rates.

Closes #42

fix(renderer): prevent buffer underrun on device change

Fixed race condition when switching audio devices that could
cause buffer underruns and audio glitches.

Pull Request Process

Before Submitting

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
Describe testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests pass

Review Process

Submit PR with clear description
Automated tests run
Code review by maintainer
Address feedback
Approval and merge

Areas for Contribution

High Priority

CoreAudio HAL integration
Audio format decoders (FLAC, ALAC, DSD)
Sample rate matching implementation
Buffer management optimization
Unit test coverage

Medium Priority

Metadata extraction
Gapless playback
Device hot-plug handling
Performance profiling
Documentation improvements

Future Enhancements

Multi-channel audio support
DSD native playback
Plugin architecture
Cross-platform support
Audio analysis tools

Communication

Channels

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Pull Requests: Code contributions

Issue Reporting

Bug Report Template:

**Description:**
Clear description of the bug

**Steps to Reproduce:**
1. Step one
2. Step two
3. ...

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- macOS version:
- Xcode version:
- BitPerfectCore version:
- Audio device:

**Additional Context:**
Any other relevant information

Feature Request Template:

**Feature Description:**
Clear description of the proposed feature

**Use Case:**
Why is this feature needed?

**Proposed Solution:**
How should it work?

**Alternatives Considered:**
Other approaches considered

**Additional Context:**
Any other relevant information

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of background or experience level.

Expected Behavior

Be respectful and considerate
Welcome newcomers and help them learn
Accept constructive criticism gracefully
Focus on what's best for the project
Show empathy toward others

Unacceptable Behavior

Harassment or discrimination
Trolling or insulting comments
Personal or political attacks
Publishing others' private information
Other unprofessional conduct

Enforcement

Violations may result in temporary or permanent ban from the project. Report issues to the maintainer.

License

By contributing to BitPerfectCore, you agree that your contributions will be licensed under the MIT License.

Recognition

Contributors will be recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Questions?

If you have questions about contributing:

Check existing documentation
Search closed issues
Open a new discussion on GitHub

Thank You!

Your contributions help make BitPerfectCore better for everyone. We appreciate your time and effort!

Maintainer: Mario Alberto Arce
Last Updated: June 2026
Project Status: Active Development (v0.5.0)

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History