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.

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¶

pip install coremusic

Or build from source:

git clone https://github.com/shakfu/coremusic.git
cd coremusic
make

Basic Audio File Operations¶

from coremusic.audio import AudioFile

# Object-oriented API (recommended)
with 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¶

from coremusic.audio import AudioFormat, AudioUnit

# Create and configure an AudioUnit
with AudioUnit.default_output() as unit:
    format = AudioFormat.pcm(sample_rate=44100.0, channels=2, bits=16)
    unit.set_stream_format(format, scope="input")
    unit.initialize()
    unit.start()
    # ... audio processing ...
    unit.stop()

MIDI Operations¶

from coremusic.midi import MIDIClient, get_destinations, note_on

# Create MIDI client
client = MIDIClient("My MIDI App")
try:
    output_port = client.create_output_port("Output")

    # Aim at an endpoint published by the system, or create a virtual one
    destinations = get_destinations()
    if destinations:
        destination = destinations[0]
    else:
        destination = client.create_virtual_destination("Synth")

    # Send MIDI data: Note On, middle C, full velocity
    output_port.send_data(destination, note_on("C4", 127))
finally:
    client.dispose()

Audio/MIDI Synchronization¶

from coremusic.audio import AudioClock

# Use AudioClock for precise timing
with 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()
    print(f"{seconds:.3f}s / {beats:.3f} beats / {samples:.0f} samples")

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

    clock.stop()

Music Theory¶

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

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

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

# Interval analysis
from coremusic.music.theory import Interval

interval = Interval.between(c4, Note("G", 4))
print(f"Interval: {interval.name}")  # Perfect Fifth

Command Line Interface¶

# 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 list
coremusic midi monitor
coremusic midi panic

# Render MIDI through an instrument plugin to audio
coremusic plugin render "DLSMusicDevice" song.mid -o rendered.wav

# Diagnose the installation
coremusic doctor

See CLI Guide for complete CLI documentation.