Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
executable file
·
847 lines (646 loc) · 20.3 KB

DOCUMENTATION.md

File metadata and controls

executable file
·
847 lines (646 loc) · 20.3 KB
Raw

SyncVold - Technical Documentation

Abstract

SyncVold is a macOS audio synchronization utility that enables simultaneous volume control across multiple audio output devices. Built with Swift and leveraging Core Audio APIs, it provides a menu bar application with advanced features including per-device volume offsets, media key integration, and persistent configuration management.

Table of Contents

  1. System Architecture
  2. Core Components
  3. Audio Engine
  4. User Interface
  5. Persistence Layer
  6. Media Key Integration
  7. Installation & Deployment
  8. API Reference
  9. Configuration
  10. Troubleshooting

System Architecture

Overview

SyncVold employs a modular architecture consisting of:

┌─────────────────────────────────────┐
│         User Interface              │
│    (SwiftUI + AppKit)               │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     Volume Controller               │
│  (Business Logic Layer)             │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     Core Audio Interface            │
│  (CoreAudioCtl)                     │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   macOS Core Audio Framework        │
└─────────────────────────────────────┘

Design Patterns

  • Singleton Pattern: CoreAudioCtl.shared for audio device management
  • Observer Pattern: SwiftUI's @Published properties for reactive UI updates
  • Delegate Pattern: NSApplicationDelegate for application lifecycle management
  • Strategy Pattern: Volume offset calculation per device

Core Components

1. CoreAudioCtl

Purpose: Low-level interface to macOS Core Audio framework.

Key Methods:

class CoreAudioCtl {
    static let shared: CoreAudioCtl
    
    func allDevices() -> [AudioDev]
    func defaultOutput() -> AudioDeviceID?
    func readVolume(device: AudioDeviceID) -> Float?
    func setVolume(device: AudioDeviceID, value: Float)
}

Implementation Details:

  • Uses AudioObjectPropertyAddress for property queries
  • Handles both stereo (L/R channels) and master volume control
  • Validates device output capability via stream configuration
  • Thread-safe singleton implementation

2. VolumeController

Purpose: Business logic layer managing synchronization state and operations.

Properties:

class VolumeController: ObservableObject {
    @Published var devices: [AudioDev]
    @Published var selectedDevices: Set<AudioDev>
    @Published var deviceOffsets: [String: Float]
    @Published var currentVolume: Float
    @Published var isRunning: Bool
    @Published var syncAllOutputs: Bool
    @Published var autoStartSync: Bool
    @Published var resumeLastState: Bool
    @Published var preciseMode: Bool
}

Core Algorithm:

Volume Application Algorithm:
─────────────────────────────
INPUT: masterVolume (0.0 - 1.0)

FOR EACH device IN selectedDevices:
    IF masterVolume ≤ 0.001 THEN
        // Safety mechanism
        SET device.volume = 0.0
    ELSE
        offset = deviceOffsets[device.uid] ?? 0.0
        adjustedVolume = CLAMP(masterVolume + offset, 0.0, 1.0)
        SET device.volume = adjustedVolume
    END IF
END FOR

3. AppDelegate

Purpose: Application lifecycle management and system integration.

Responsibilities:

  • Menu bar item management
  • Media key event tap setup
  • Login item configuration
  • Application termination protection

Key Features:

// Prevents accidental termination
func applicationShouldTerminate(_ sender: NSApplication) 
    -> NSApplication.TerminateReply {
    // Shows confirmation dialog
    return userConfirmed ? .terminateNow : .terminateCancel
}

// Keeps app running when window closes
func applicationShouldTerminateAfterLastWindowClosed(
    _ sender: NSApplication) -> Bool {
    NSApp.setActivationPolicy(.accessory)
    return false
}

Audio Engine

Device Discovery

func allDevices() -> [AudioDev] {
    var address = AudioObjectPropertyAddress(
        mSelector: kAudioHardwarePropertyDevices,
        mScope: kAudioObjectPropertyScopeGlobal,
        mElement: kAudioObjectPropertyElementMain
    )
    
    var size: UInt32 = 0
    AudioObjectGetPropertyDataSize(
        AudioObjectID(kAudioObjectSystemObject),
        &address, 0, nil, &size
    )
    
    let count = Int(size) / MemoryLayout<AudioObjectID>.size
    var deviceIDs = [AudioObjectID](repeating: 0, count: count)
    AudioObjectGetPropertyData(
        AudioObjectID(kAudioObjectSystemObject),
        &address, 0, nil, &size, &deviceIDs
    )
    
    return deviceIDs.compactMap { createAudioDev(from: $0) }
}

Volume Control

Read Volume:

func readVolume(device: AudioDeviceID) -> Float? {
    // Try master volume first
    if let master = readChannel(device, .main) { return master }
    
    // Fall back to L/R average
    let left = readChannel(device, 1)
    let right = readChannel(device, 2)
    
    if let l = left, let r = right { return (l + r) / 2 }
    return left ?? right
}

Set Volume:

func setVolume(device: AudioDeviceID, value: Float) {
    let clamped = max(0.0, min(1.0, value))
    
    if setChannel(device, .main, clamped) { return }
    
    // Fallback to L/R channels
    setChannel(device, 1, clamped)
    setChannel(device, 2, clamped)
}

Safety Mechanisms

  1. Zero-Volume Override:

    if masterVolume <= 0.001 {
    // Force all devices to 0
    forceAllToZero()
    return
}

  2. Value Clamping:

    adjustedVolume = max(0.0, min(1.0, baseVolume + offset))

  3. Device Validation:

    guard hasOutput(deviceID) else { return }

User Interface

Architecture

Built with SwiftUI for modern, reactive UI updates:

ContentView (SwiftUI)
├── Header Section
├── Options Panel
│   ├── Sync ALL toggle
│   ├── Auto-start toggle
│   ├── Resume state toggle
│   └── Precise mode toggle
├── Device List (ScrollView)
│   └── ForEach device
│       ├── Selection checkbox
│       ├── Device info
│       └── Offset slider (conditional)
├── Volume Control
│   ├── Master slider
│   └── Percentage display
├── Control Buttons
│   ├── Start/Stop sync
│   └── Refresh devices
├── Status Indicator
└── Credits Section

State Management

Uses SwiftUI's @StateObject and @Published for reactive updates:

struct ContentView: View {
    @StateObject private var controller = VolumeController()
    
    var body: some View {
        VStack {
            // UI automatically updates when controller properties change
            Slider(value: $controller.currentVolume)
                .onChange(of: controller.currentVolume) { newValue in
                    if controller.isRunning {
                        controller.applyVolume(newValue)
                    }
                }
        }
    }
}

Menu Bar Integration

statusItem = NSStatusBar.system.statusItem(
    withLength: NSStatusItem.squareLength
)

statusItem?.button?.image = NSImage(
    systemSymbolName: "speaker.wave.3.fill",
    accessibilityDescription: "SyncVold"
)

let menu = NSMenu()
menu.addItem(NSMenuItem(
    title: isRunning ? "🟢 Syncing" : "⚪️ Inactive",
    action: nil,
    keyEquivalent: ""
))

Persistence Layer

Data Model

struct AppSettings: Codable {
    var selectedDevices: [DeviceSettings]
    var syncAllOutputs: Bool
    var autoStartSync: Bool
    var startAtLogin: Bool
    var showWindowAtLaunch: Bool
    var masterVolume: Float
    var lastSyncState: Bool
    var preciseMode: Bool
    var resumeLastState: Bool
}

struct DeviceSettings: Codable {
    var uid: String
    var name: String
    var volumeOffset: Float
    var isEnabled: Bool
}

Storage Location

~/Library/Application Support/SyncVold/settings.json

Serialization

static func save() {
    guard let data = try? JSONEncoder().encode(self) else { return }
    try? data.write(to: settingsURL)
}

static func load() -> AppSettings {
    guard let data = try? Data(contentsOf: settingsURL),
          let settings = try? JSONDecoder().decode(
              AppSettings.self, from: data
          ) else {
        return AppSettings() // Default values
    }
    return settings
}

Auto-Save Triggers

Settings are automatically saved on:

  • Device selection change
  • Volume offset modification
  • Sync start/stop
  • Volume change via media keys
  • Option toggle changes
  • Window close
  • Application termination

Media Key Integration

Implementation

Uses CGEvent tap to intercept system-defined events:

func setupMediaKeyListener() {
    let eventType = CGEventType(rawValue: 14)! // System defined
    let eventMask = CGEventMask(1 << eventType.rawValue)
    
    guard let tap = CGEvent.tapCreate(
        tap: .cghidEventTap,
        place: .headInsertEventTap,
        options: .listenOnly,
        eventsOfInterest: eventMask,
        callback: mediaKeyCallback,
        userInfo: nil
    ) else {
        // Requires Accessibility permission
        return
    }
    
    let runLoopSource = CFMachPortCreateRunLoopSource(
        kCFAllocatorDefault, tap, 0
    )
    CFRunLoopAddSource(
        CFRunLoopGetCurrent(), 
        runLoopSource, 
        .commonModes
    )
    CGEvent.tapEnable(tap: tap, enable: true)
}

Event Processing

static func handleMediaKey(event: NSEvent) {
    let data = event.data1
    let keyCode = ((data & 0xFFFF0000) >> 16)
    let keyState = (((data & 0x0000FFFF) & 0xFF00) >> 8)
    
    guard keyState == 0xA else { return } // Key pressed
    guard let controller = globalVolumeController,
          controller.isRunning else { return }
    
    let step: Float = controller.preciseMode ? 0.01 : 0.05
    
    switch Int(keyCode) {
    case 0: // Volume Up
        let newVolume = min(controller.currentVolume + step, 1.0)
        controller.setVolume(newVolume)
        
    case 1: // Volume Down
        let newVolume = max(controller.currentVolume - step, 0.0)
        controller.setVolume(newVolume)
        
    case 7: // Mute
        controller.setVolume(0.0)
        
    default:
        break
    }
}

Permissions

Requires Accessibility permission:

  • System Settings → Privacy & Security → Accessibility
  • Add SyncVold and enable checkbox

Installation & Deployment

Build from Source

# Clone repository
git clone https://github.com/yourusername/syncvold.git
cd syncvold

# Build release version
swift build -c release

# Create app bundle
./create-app-bundle.sh

# Install to Applications
sudo cp -R .build/release/SyncVold.app /Applications/

Create DMG

# Generate distributable DMG
./create-dmg.sh

# Output: SyncVold-1.0.0.dmg

System Requirements

  • OS: macOS 13.0 (Ventura) or later
  • Architecture: Universal (Intel + Apple Silicon)
  • Frameworks:
    • CoreAudio.framework
    • AudioToolbox.framework
    • Cocoa.framework
    • CoreGraphics.framework
    • SwiftUI.framework

Installation Methods

Method 1: DMG (Recommended)

  1. Download SyncVold-1.0.0.dmg
  2. Open DMG
  3. Drag SyncVold.app to Applications folder
  4. Launch from Applications

Method 2: Direct Install

./build-and-install.sh

Method 3: Manual

cp -R .build/release/SyncVold.app /Applications/
open /Applications/SyncVold.app

API Reference

CoreAudioCtl

class CoreAudioCtl {
    /// Singleton instance
    static let shared: CoreAudioCtl
    
    /// Get all audio devices with output capability
    /// - Returns: Array of AudioDev structures
    func allDevices() -> [AudioDev]
    
    /// Get system default output device
    /// - Returns: Device ID or nil if not found
    func defaultOutput() -> AudioDeviceID?
    
    /// Read current volume of device
    /// - Parameter device: Audio device ID
    /// - Returns: Volume level (0.0-1.0) or nil
    func readVolume(device: AudioDeviceID) -> Float?
    
    /// Set volume for device
    /// - Parameters:
    ///   - device: Audio device ID
    ///   - value: Volume level (0.0-1.0), will be clamped
    func setVolume(device: AudioDeviceID, value: Float)
}

VolumeController

class VolumeController: ObservableObject {
    /// All discovered audio devices
    @Published var devices: [AudioDev]
    
    /// Currently selected devices for sync
    @Published var selectedDevices: Set<AudioDev>
    
    /// Per-device volume offset (-0.3 to +0.3)
    @Published var deviceOffsets: [String: Float]
    
    /// Master volume level (0.0-1.0)
    @Published var currentVolume: Float
    
    /// Synchronization active state
    @Published var isRunning: Bool
    
    /// Start volume synchronization
    func start()
    
    /// Stop volume synchronization
    func stop()
    
    /// Apply volume to all selected devices
    /// - Parameter volume: Master volume level
    func applyVolume(_ volume: Float)
    
    /// Set volume (public API for media keys)
    /// - Parameter volume: New volume level
    func setVolume(_ volume: Float)
    
    /// Set offset for specific device
    /// - Parameters:
    ///   - device: Target audio device
    ///   - offset: Offset value (-1.0 to +1.0)
    func setDeviceOffset(_ device: AudioDev, offset: Float)
    
    /// Refresh device list from system
    func refreshDevices()
    
    /// Save current configuration to disk
    func saveSettings()
    
    /// Load configuration from disk
    func loadSettings()
}

Configuration

Settings File Format

{
  "selectedDevices": [
    {
      "uid": "AppleHDAEngineOutput:1B,0,1,3:1",
      "name": "Built-in Line Output",
      "volumeOffset": 0.1,
      "isEnabled": true
    }
  ],
  "syncAllOutputs": false,
  "autoStartSync": true,
  "startAtLogin": true,
  "showWindowAtLaunch": false,
  "masterVolume": 0.65,
  "lastSyncState": true,
  "preciseMode": false,
  "resumeLastState": true
}

Configuration Options

Option Type Default Description
selectedDevices Array [] List of devices to synchronize
syncAllOutputs Bool false Auto-select all audio outputs
autoStartSync Bool true Start sync on app launch
startAtLogin Bool true Launch app at system boot
showWindowAtLaunch Bool false Show settings window on startup
masterVolume Float 0.5 Last known volume level
lastSyncState Bool false Was sync active before quit
preciseMode Bool false Use ±1% instead of ±5% steps
resumeLastState Bool true Resume sync state on launch

Troubleshooting

Common Issues

1. Media keys not working

Symptom: Volume +/- keys don't control synced devices

Solution:

1. System Settings → Privacy & Security → Accessibility
2. Add SyncVold to list
3. Enable checkbox
4. Restart SyncVold

Technical Note: Requires CGEvent tap with Accessibility permission for system-defined events.

2. App won't start sync

Symptom: "Start Sync" button disabled

Solution:

  • Ensure at least one device is selected
  • Check devices with Refresh button
  • Verify devices have output capability

Technical Note: Check console for errors:

log stream --predicate 'processImagePath contains "SyncVold"' --level debug

3. Volume offset not persisting

Symptom: Offset values reset after restart

Solution:

  • Check file permissions on ~/Library/Application Support/SyncVold/
  • Verify settings.json is writable
  • Check disk space

Technical Note: Settings save on every change. If failing, check stderr:

Console.app → Filter: SyncVold

4. App crashes on launch

Symptom: App quits immediately after opening

Solution:

# Reset settings
rm -rf ~/Library/Application\ Support/SyncVold/

# Check crash logs
open ~/Library/Logs/DiagnosticReports/

Performance Considerations

Optimization Strategies

  1. Lazy Device Discovery: Only query devices when needed
  2. Throttled Updates: Coalesce rapid volume changes
  3. Efficient Audio Calls: Batch property updates when possible
  4. Memory Management: Weak references in closures to prevent cycles

Benchmarks

  • Device Discovery: ~5-10ms for 10 devices
  • Volume Set (single): ~1-2ms per device
  • Volume Set (batch): ~2-5ms for 3 devices
  • Media Key Response: <10ms from keypress to audio change

Security Considerations

Permissions

  • Accessibility: Required for media key interception
    • Allows reading system-wide keyboard events
    • Limited to media keys only in implementation

Data Privacy

  • All settings stored locally
  • No network communication
  • No telemetry or analytics
  • No personal data collection

Code Signing

For distribution:

codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name" \
  SyncVold.app

Future Enhancements

Planned Features

  1. Audio Routing: Route specific apps to specific devices
  2. Presets: Save/load device configurations
  3. Hotkeys: Custom keyboard shortcuts beyond media keys
  4. Advanced EQ: Per-device equalization
  5. Audio Matrix: Complex routing scenarios

API Extensions

// Proposed API additions
extension VolumeController {
    func createPreset(name: String) -> Preset
    func loadPreset(_ preset: Preset)
    func routeApplication(_ app: String, to device: AudioDev)
}

Contributing

Development Setup

git clone https://github.com/yourusername/syncvold.git
cd syncvold
swift build

Code Style

  • Follow Swift API Design Guidelines
  • Use SwiftLint for consistency
  • Document public APIs
  • Write unit tests for core logic

Pull Request Process

  1. Fork repository
  2. Create feature branch
  3. Implement changes with tests
  4. Submit PR with description
  5. Address review comments

License

MIT License - See LICENSE file for details

Credits

Author: Built for a specific use case

Philosophy:

Made for a buddy, paid in two packs. Parts of it may misbehave; that's a feature. Take it as-is. Complaints? Branch it, champ.

Professional Services: terabitlab.com

Efficient Moldovan engineering, wallet-friendly.

Appendix

A. Core Audio Property Keys

kAudioHardwarePropertyDevices           // Get all devices
kAudioHardwarePropertyDefaultOutputDevice // Default output
kAudioDevicePropertyVolumeScalar        // Volume (0.0-1.0)
kAudioDevicePropertyStreamConfiguration // Output channels
kAudioObjectPropertyName                // Device name
kAudioDevicePropertyDeviceUID           // Unique ID

B. Event Type Codes

CGEventType.systemDefined     // rawValue: 14
NX_KEYTYPE_SOUND_UP          // 0
NX_KEYTYPE_SOUND_DOWN        // 1
NX_KEYTYPE_MUTE              // 7

C. Build Configuration

// Package.swift
platforms: [.macOS(.v13)]
targets: [
    .executableTarget(
        name: "SyncVold",
        linkerSettings: [
            .linkedFramework("CoreAudio"),
            .linkedFramework("AudioToolbox"),
            .linkedFramework("Cocoa"),
            .linkedFramework("CoreGraphics"),
            .linkedFramework("SwiftUI")
        ]
    )
]

Document Version: 1.0.0
Last Updated: October 2025
Swift Version: 5.9+
Target OS: macOS 13.0+