Claude
52fa522d6d
New features:
- SerialManager for USB/Serial communication with hardware
- Support for 4 physical VU meter dials
- Flexible channel mapping: Audio L/R, Peak, Mono, CPU, RAM, Disk, Network
- Multiple protocols: Raw bytes, Text, JSON, VU-Server compatible
- Per-dial configuration: min/max values, inversion, smoothing
- Hardware panel in main view showing dial status
- Hardware settings sheet for configuration
- Auto-detection of USB serial devices
Protocol formats:
- Raw: [0xAA][D1][D2][D3][D4][0x55]
- Text: CH1:val;CH2:val;CH3:val;CH4:val\n
- JSON: {"dials":[d1,d2,d3,d4]}
- VU-Server: #0:val\n#1:val\n...
231 lines
6.9 KiB
Markdown
231 lines
6.9 KiB
Markdown
# Audio VU Meter for macOS
|
|
|
|
A native macOS SwiftUI application that displays real-time audio levels from BlackHole (or any audio input device) as a classic VU meter, along with system resource monitoring. **Now with physical VU meter hardware support!**
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
### Audio VU Meter
|
|
- **Real-time audio level monitoring** - Displays Left and Right channel levels
|
|
- **dB scale display** - Shows audio levels in decibels (-60 dB to 0 dB)
|
|
- **Peak hold indicators** - Visual peak markers with configurable hold time
|
|
- **BlackHole integration** - Automatically detects and selects BlackHole virtual audio device
|
|
- **Multi-device support** - Switch between any available audio input device
|
|
|
|
### System Resource Monitors
|
|
- **CPU Usage** - Real-time CPU utilization percentage
|
|
- **RAM Usage** - Memory consumption monitoring
|
|
- **Disk Activity** - Disk I/O activity indicator
|
|
- **Network Activity** - Network throughput monitoring
|
|
|
|
### Physical VU Meter Hardware Support
|
|
- **4 Physical Dials** - Support for up to 4 physical VU meter dials
|
|
- **Flexible Channel Mapping** - Assign any metric to any dial:
|
|
- Audio Left/Right channels
|
|
- Audio Peak or Mono (L+R)
|
|
- CPU, RAM, Disk, Network usage
|
|
- **Multiple Serial Protocols**:
|
|
- Raw Bytes: `[0xAA] [D1] [D2] [D3] [D4] [0x55]`
|
|
- Text Commands: `CH1:val;CH2:val;CH3:val;CH4:val\n`
|
|
- JSON: `{"dials":[d1,d2,d3,d4]}`
|
|
- VU-Server Compatible: `#0:val\n#1:val\n...`
|
|
- **Configurable per dial**: Min/max values, inversion, smoothing
|
|
- **Auto-detection** of USB serial devices
|
|
|
|
## Requirements
|
|
|
|
- macOS 13.0 (Ventura) or later
|
|
- Xcode 15.0 or later (for building)
|
|
- [BlackHole](https://existential.audio/blackhole/) virtual audio driver (recommended)
|
|
- USB/Serial VU meter hardware (optional)
|
|
|
|
## Installation
|
|
|
|
### Using BlackHole
|
|
|
|
1. Install BlackHole from [existential.audio/blackhole](https://existential.audio/blackhole/)
|
|
2. Configure BlackHole as a multi-output device in Audio MIDI Setup
|
|
3. Build and run Audio VU Meter
|
|
4. The app will automatically detect and select BlackHole
|
|
|
|
### Building from Source
|
|
|
|
1. Clone the repository
|
|
2. Open `AudioVUMeter.xcodeproj` in Xcode
|
|
3. Build and run (Cmd+R)
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd AudioVUMeter
|
|
open AudioVUMeter.xcodeproj
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Main Window
|
|
- **Audio Levels**: The vertical VU meters show Left (L) and Right (R) channel audio levels
|
|
- **dB Readings**: Numeric display of current audio levels in decibels
|
|
- **System Meters**: Circular gauges showing CPU, RAM, Disk, and Network usage
|
|
- **Hardware Output**: Shows status of connected physical VU meters
|
|
|
|
### Controls
|
|
- **Start/Stop**: Toggle audio capture on/off
|
|
- **Reset**: Clear peak hold indicators
|
|
- **Settings** (gear icon): Access device selection and preferences
|
|
- **Hardware** (cable icon): Configure physical VU meter connection
|
|
|
|
### Hardware Setup
|
|
|
|
1. Connect your USB/Serial VU meter hardware
|
|
2. Click the cable icon or go to Settings -> Hardware
|
|
3. Select your serial port from the dropdown
|
|
4. Choose the appropriate baud rate (default: 115200)
|
|
5. Select the communication protocol your hardware uses
|
|
6. Assign channels to each dial (Audio L, R, CPU, RAM, etc.)
|
|
7. Click "Connect"
|
|
|
|
### Settings
|
|
- **Input Device**: Select audio input source (BlackHole, microphone, etc.)
|
|
- **Reference Level**: Adjust the 0 dB reference point
|
|
- **Peak Hold Time**: Configure how long peak indicators remain visible
|
|
- **Hardware**: Serial port, protocol, and dial assignments
|
|
|
|
## Architecture
|
|
|
|
```
|
|
AudioVUMeter/
|
|
├── AudioVUMeterApp.swift # App entry point
|
|
├── ContentView.swift # Main UI layout
|
|
├── VUMeterView.swift # VU meter components
|
|
├── AudioEngine.swift # Core Audio capture engine
|
|
├── SystemMonitor.swift # System resource monitoring
|
|
├── SerialManager.swift # USB/Serial communication
|
|
├── HardwareView.swift # Hardware configuration UI
|
|
├── SettingsView.swift # Settings window
|
|
└── Assets.xcassets/ # App icons and colors
|
|
```
|
|
|
|
### Key Components
|
|
|
|
- **AudioEngine**: Uses AVAudioEngine to capture audio from the selected input device, calculates RMS levels, and converts to dB
|
|
- **SystemMonitor**: Uses Mach kernel APIs to retrieve CPU, memory, disk, and network statistics
|
|
- **SerialManager**: Handles USB/Serial communication with physical VU meter hardware
|
|
- **VUMeterView**: SwiftUI views for classic vertical VU meters with segment-based display
|
|
- **SystemMeterView**: Circular gauge components for system metrics
|
|
|
|
## Hardware Protocol Reference
|
|
|
|
### Raw Bytes Protocol
|
|
```
|
|
Start: 0xAA
|
|
Data: [Dial1] [Dial2] [Dial3] [Dial4] (0-255 each)
|
|
End: 0x55
|
|
```
|
|
|
|
### Text Command Protocol
|
|
```
|
|
CH1:128;CH2:64;CH3:200;CH4:32\n
|
|
```
|
|
|
|
### JSON Protocol
|
|
```json
|
|
{"dials":[128,64,200,32]}
|
|
```
|
|
|
|
### VU-Server Compatible Protocol
|
|
```
|
|
#0:50
|
|
#1:75
|
|
#2:30
|
|
#3:90
|
|
```
|
|
Values are percentages (0-100)
|
|
|
|
## BlackHole Setup Guide
|
|
|
|
1. **Install BlackHole**: Download and install from [existential.audio](https://existential.audio/blackhole/)
|
|
|
|
2. **Create Multi-Output Device**:
|
|
- Open Audio MIDI Setup (Applications -> Utilities)
|
|
- Click the `+` button -> Create Multi-Output Device
|
|
- Check both your speakers and BlackHole
|
|
- Set as default output
|
|
|
|
3. **Route Audio**:
|
|
- System audio will now go to both speakers and BlackHole
|
|
- Audio VU Meter captures from BlackHole input
|
|
|
|
## Compatible Hardware
|
|
|
|
This app is designed to work with:
|
|
- [VU Dials by Sasa Karanovic](https://github.com/SasaKaranovic/VU-Server)
|
|
- Arduino-based VU meters with serial interface
|
|
- Any USB/Serial device accepting the supported protocols
|
|
|
|
## API Reference
|
|
|
|
### AudioEngine
|
|
|
|
```swift
|
|
// Start/stop audio capture
|
|
audioEngine.start()
|
|
audioEngine.stop()
|
|
|
|
// Reset peak indicators
|
|
audioEngine.resetPeaks()
|
|
|
|
// Switch audio device
|
|
audioEngine.selectedDeviceID = deviceID
|
|
audioEngine.switchDevice()
|
|
|
|
// Access levels
|
|
audioEngine.leftLevel // 0.0 to 1.0
|
|
audioEngine.rightLevel // 0.0 to 1.0
|
|
audioEngine.leftLevelDB // -60 to 0 dB
|
|
audioEngine.rightLevelDB // -60 to 0 dB
|
|
```
|
|
|
|
### SystemMonitor
|
|
|
|
```swift
|
|
// Start/stop monitoring
|
|
systemMonitor.startMonitoring()
|
|
systemMonitor.stopMonitoring()
|
|
|
|
// Access metrics (0-100%)
|
|
systemMonitor.cpuUsage
|
|
systemMonitor.memoryUsage
|
|
systemMonitor.diskActivity
|
|
systemMonitor.networkActivity
|
|
```
|
|
|
|
### SerialManager
|
|
|
|
```swift
|
|
// Connection
|
|
serialManager.connect()
|
|
serialManager.disconnect()
|
|
|
|
// Configuration
|
|
serialManager.selectedPortPath = "/dev/cu.usbserial-XXX"
|
|
serialManager.baudRate = 115200
|
|
serialManager.selectedProtocol = .vuServer
|
|
|
|
// Dial assignment
|
|
serialManager.dialConfigs[0].dialChannel = .audioLeft
|
|
serialManager.dialConfigs[1].dialChannel = .audioRight
|
|
serialManager.dialConfigs[2].dialChannel = .cpu
|
|
serialManager.dialConfigs[3].dialChannel = .ram
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - See LICENSE file for details.
|
|
|
|
## Credits
|
|
|
|
Inspired by [VU-Server](https://github.com/SasaKaranovic/VU-Server) by Sasa Karanovic.
|