# CoreMusic Documentation

**CoreMusic** is a comprehensive Cython wrapper for Apple's CoreAudio and CoreMIDI ecosystem, providing both functional and object-oriented Python bindings for professional audio and MIDI development on macOS.

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)

## Key Features

- **Dual API Design**: Both functional (C-style) and object-oriented (Pythonic) APIs
- **Complete Framework Coverage**: CoreAudio, AudioToolbox, AudioUnit, and CoreMIDI
- **High Performance**: Cython-based with near-native C performance
- **Automatic Resource Management**: Context managers and automatic cleanup
- **Professional Audio Support**: Real-time processing, multi-channel audio, hardware control
- **Comprehensive MIDI**: MIDI 1.0/2.0 support, device management, advanced routing
- **Precise Timing & Sync**: CoreAudioClock for audio/MIDI synchronization and tempo control
- **Music Theory**: Notes, scales, chords, intervals, and harmonic analysis
- **Command Line Interface**: CLI for audio analysis, conversion, and MIDI operations

## Quick Start

### Installation

```bash
git clone https://github.com/yourusername/coremusic.git
cd coremusic
pip install cython
make
```

### Basic Audio File Operations

```python
import coremusic as cm

# Object-oriented API (recommended)
with cm.AudioFile("audio.wav") as audio:
    print(f"Duration: {audio.duration:.2f}s")
    print(f"Sample rate: {audio.format.sample_rate}Hz")
    data, count = audio.read_packets(0, 1000)
```

### AudioUnit Processing

```python
import coremusic as cm

# Create and configure an AudioUnit
with cm.AudioUnit.default_output() as unit:
    format = cm.AudioFormat(
        sample_rate=44100.0,
        format_id='lpcm',
        channels_per_frame=2,
        bits_per_channel=16
    )
    unit.set_stream_format(format)
    unit.start()
    # ... audio processing ...
    unit.stop()
```

### MIDI Operations

```python
import coremusic as cm

# Create MIDI client
client = cm.MIDIClient("My MIDI App")
try:
    output_port = client.create_output_port("Output")
    # Send MIDI data
    note_on = b'\x90\x60\x7F'  # Note On, Middle C
    output_port.send_data(destination, note_on)
finally:
    client.dispose()
```

### Audio/MIDI Synchronization

```python
import coremusic as cm
import time

# Use AudioClock for precise timing
with cm.AudioClock() as clock:
    clock.play_rate = 1.0  # Normal speed
    clock.start()

    # Get time in different formats
    seconds = clock.get_time_seconds()
    beats = clock.get_time_beats()
    samples = clock.get_time_samples()

    # Change speed (for tempo sync)
    clock.play_rate = 0.5  # Half speed

    clock.stop()
```

### Music Theory

```python
from coremusic.music.theory import Note, Scale, ScaleType, Chord, ChordType

# Create notes, scales, and chords
c4 = Note.from_name("C4")
c_major = Scale(c4, ScaleType.MAJOR)
cmaj7 = Chord(c4, ChordType.MAJOR_7)

# Get scale degrees and chord notes
print(f"C Major scale: {[n.name for n in c_major.notes]}")
print(f"CMaj7 chord: {[n.name for n in cmaj7.notes]}")

# Interval analysis
from coremusic.music.theory import Interval
interval = Interval.between(c4, Note.from_name("G4"))
print(f"Interval: {interval.name}")  # Perfect Fifth
```

### Command Line Interface

```bash
# Audio playback and recording
coremusic audio play song.wav --loop
coremusic audio record -o recording.wav -d 10

# Analyze audio
coremusic analyze levels song.wav
coremusic analyze tempo song.wav

# AudioUnit plugins
coremusic plugin list --type effect
coremusic plugin process "AUDelay" input.wav -o output.wav

# MIDI operations
coremusic midi devices
coremusic midi input monitor
coremusic midi output panic
```

See [CLI Guide](guides/cli.md) for complete CLI documentation.

## Documentation Contents
