CoreMusic: Python bindings for Apple CoreAudio

A zero-dependency music development toolkit for macOS providing Python access to Apple's CoreAudio and CoreMIDI frameworks via Cython. Offers both functional (C-style) and object-oriented (Pythonic) APIs with automatic resource management.

Features

Audio: File I/O (read WAV/AIFF/CAF/MP3/AAC/M4A/ALAC/FLAC; write WAV/AIFF/CAF plus AAC/M4A/ALAC/FLAC encoding), real-time processing, analysis (peak, RMS, tempo, key), buffer pool, memory-mapped I/O

MIDI: Device discovery, virtual devices, routing, transformation pipeline (transpose, quantize, humanize, harmonize)

Music Theory: 25+ scales, 35+ chords, Note/Interval/Scale/Chord classes, time signatures, rhythmic patterns

Installation

pip install coremusic

Requirements: macOS, Python 3.10+

Optional Dependencies

CoreMusic has zero runtime dependencies by default. Optional features require additional packages:

# Audio analysis (beat detection, pitch detection, key detection)
pip install coremusic[analysis]

# Visualization (waveform plots, spectrograms)
pip install coremusic[visualization]

# All optional features
pip install coremusic[all]

Check feature availability at runtime:

from coremusic.base import NUMPY_AVAILABLE
from coremusic.audio import AudioFile
from coremusic.audio.analysis import AudioAnalyzer
import coremusic.utils.scipy as spu

if NUMPY_AVAILABLE:
    # NumPy-based features available
    with AudioFile("song.wav") as audio:
        data = audio.read_as_numpy()

if spu.SCIPY_AVAILABLE:
    # SciPy-based analysis available
    analyzer = AudioAnalyzer("song.wav")
    tempo = analyzer.detect_beats().tempo

Building from Source

git clone https://github.com/shakfu/coremusic.git
cd coremusic
make        # Build
make test   # Run tests

Command Line Interface

% coremusic --help
usage: coremusic [-h] [--version] [--json] <command> ...

CoreMusic - Python bindings for Apple CoreAudio.

positional arguments:
  <command>
    audio     Audio file operations
    device    Audio device management
    plugin    AudioUnit plugin discovery
    analyze   Audio analysis and feature extraction
    convert   Convert audio files between formats
    midi      MIDI operations
    sequence  MIDI sequence operations
    doctor    Diagnose the installation and environment
    completion
              Generate shell completion scripts

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
  --json      Output in JSON format

Shell Completion

Enable tab completion for commands and options:

# Bash (add to ~/.bashrc)
eval "$(coremusic completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(coremusic completion zsh)"

# Fish (add to ~/.config/fish/config.fish)
coremusic completion fish | source

Examples

# Audio
coremusic audio play song.wav --loop
coremusic audio record -o recording.wav -d 10
coremusic analyze tempo song.wav
coremusic convert normalize input.wav output.wav --target -1.0

# Devices
coremusic device list
coremusic device volume "MacBook Pro Speakers" 0.5

# Plugins
coremusic plugin list --type effect
coremusic plugin list --name-only | grep -i reverb
coremusic plugin process "AUDelay" input.wav -o output.wav
coremusic plugin chain input.wav -p "AUDelay:Delay Time=0.5" -p "AUReverb2" -o out.wav
coremusic plugin render "DLSMusicDevice" song.mid -o rendered.wav

# MIDI
coremusic midi list
coremusic midi monitor                              # Human-readable MIDI input
coremusic midi receive                              # Display incoming MIDI
coremusic midi receive -o recording.mid             # Save to MIDI file
coremusic midi receive --plugin "DLSMusicDevice"    # Route to synth plugin
coremusic midi play song.mid
coremusic midi quantize input.mid -o quantized.mid --grid 1/16
coremusic midi panic

# Device monitoring
coremusic device monitor                            # Watch for device changes

# JSON output for scripting
coremusic --json plugin list --type instrument

Quick Start

One-Liner Convenience Functions

from coremusic.shortcuts import play, play_background, convert
from coremusic.shortcuts import analyze_tempo, analyze_key, get_info
from coremusic.shortcuts import list_devices, list_plugins

# Quick playback
play("song.wav")                       # Blocking playback
handle = play_background("song.wav")   # Non-blocking, returns control handle
handle.stop()                          # Stop when done

# Quick analysis
tempo = analyze_tempo("song.wav")      # Get BPM
key, mode = analyze_key("song.wav")    # Get musical key
info = get_info("song.wav")            # Get file metadata

# Quick conversion (.wav, .aiff, .caf, plus .m4a/.aac/.flac encoding)
convert("input.wav", "output.aiff")
convert("song.wav", "song.m4a", bitrate=192000)   # AAC at 192 kbps

# Render a MIDI file through an instrument plugin to audio
from coremusic.shortcuts import render_midi
render_midi("DLSMusicDevice", "song.mid", "song.wav")

# List resources
devices = list_devices()
plugins = list_plugins(type='effect')

Runnable demos

The demos/ directory has small, self-contained scripts: host an AudioUnit effect chain, render MIDI to WAV, play a real-time tone, and run an Ableton Link-synced step sequencer. See demos/README.md.

python demos/host_au_chain.py         # WAV -> effect chain -> WAV
python demos/render_midi_to_wav.py    # MIDI -> instrument -> WAV
python demos/output_stream_tone.py    # real-time sine tone
python demos/link_sequencer.py        # Link-synced step sequencer

Run all four in sequence, writing output to build/demos-output/, with:

make demos

Audio Files

from coremusic.audio import AudioFile

with AudioFile("audio.wav") as f:
    print(f"Duration: {f.duration:.2f}s, Rate: {f.format.sample_rate}Hz")
    data, count = f.read_packets(0, 1000)

Audio Playback

from coremusic.base import AudioPlayer

player = AudioPlayer()
player.load_file("audio.wav")
player.setup_output()
player.play()
player.set_looping(True)
# ... later
player.stop()

AudioUnit Plugins

import time

from coremusic.audio.audiounit_host import AudioUnitHost

# Discover and use plugins
host = AudioUnitHost()
effects = host.discover_plugins(type='effect')

with host.load_plugin("DLSMusicDevice", type='instrument') as synth:
    synth.note_on(channel=0, note=60, velocity=100)
    time.sleep(1.0)
    synth.note_off(channel=0, note=60)

MIDI

from coremusic.midi import MIDIClient, get_destinations, note_off, note_on

client = MIDIClient("My App")
output_port = client.create_output_port("Output")

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

# A note may be a MIDI number, a name, or a Note
output_port.send_data(destination, note_on("C4", 127))
output_port.send_data(destination, note_off("C4"))
client.dispose()

Receiving works the same way, from the other side:

from coremusic.midi import MIDIClient, get_sources

client = MIDIClient("My App")
input_port = client.create_input_port("Input")
for source in get_sources():
    input_port.connect_source(source)

while input_port.wait(0.1):
    for host_time, data in input_port.poll():
        print(host_time, data.hex())

client.dispose()

MIDI Transformation

from coremusic.midi.utilities import MIDISequence
from coremusic.midi.transform import Pipeline, Transpose, Quantize, Humanize

seq = MIDISequence.load("input.mid")
pipeline = Pipeline([
    Transpose(semitones=5),
    Quantize(grid=0.125, strength=0.8),
    Humanize(timing=0.02, velocity=10),
])
pipeline.apply(seq).save("output.mid")

Music Theory

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

c4 = Note.from_midi(60)  # Middle C
c_major = Scale(c4, ScaleType.MAJOR)
cmaj7 = Chord(c4, ChordType.MAJOR_7)

Rhythm and Meter

from coremusic.music.theory import TimeSignature, NoteValue, Duration, RhythmPattern

ts = TimeSignature(4, 4)
dotted_quarter = Duration(NoteValue.QUARTER, dots=1)
triplet = Duration.triplet(NoteValue.EIGHTH)

pattern = RhythmPattern.straight_eighths(8)
onset_times = pattern.scale_to_tempo(120)  # At 120 BPM

Ableton Link

from coremusic import link

with link.LinkSession(bpm=120.0) as session:
    state = session.capture_app_session_state()
    current_time = session.clock.micros()
    beat = state.beat_at_time(current_time, quantum=4.0)
    print(f"Beat: {beat:.2f}, Tempo: {state.tempo:.1f} BPM")

API Overview

Object-Oriented API (Recommended)

Pythonic wrappers with automatic resource management:

• Context managers (with statements) for automatic cleanup

• Type-safe classes instead of integer IDs

• Properties, iteration, operators

• IDE autocompletion and type hints

from coremusic.audio import AudioFile, AudioFormat
from coremusic.midi import MIDIClient
from coremusic.constants import AudioFileProperty, AudioFormatID

Functional API (Advanced)

Direct access to CoreAudio C functions for maximum control:

• Direct mapping to CoreAudio C APIs

• Fine-grained resource management

• Familiar for CoreAudio developers

import coremusic.capi as capi

audio_file = capi.audio_file_open_url("audio.wav")
format_data = capi.audio_file_get_property(audio_file, capi.get_audio_file_property_data_format())
capi.audio_file_close(audio_file)

Both APIs interoperate - OO objects expose underlying IDs when needed.

Architecture

src/coremusic/
  __init__.py          # Package entry
  capi.pyx/pxd         # Cython bindings to CoreAudio/CoreMIDI
  base.py              # CoreAudioObject, AudioPlayer
  exceptions.py        # Exception hierarchy
  audio/               # AudioFile, AudioFormat, AudioUnit, AUGraph, devices,
                       #   analysis, buffer pool, streaming
  midi/                # MIDIClient, MIDIPort, MIDIEndpoint, MusicPlayer,
                       #   utilities, transforms, Link integration
  music/               # Theory (scales, chords)
  constants/           # Enumerated CoreAudio/CoreMIDI constants
  utils/               # Fourcc, batch, scipy helpers
  shortcuts.py         # One-call helpers (play, convert, render_midi)
  cli/                 # Command-line interface
  link.pyx             # Ableton Link bindings

Linked frameworks: CoreAudio, AudioToolbox, AudioUnit, CoreMIDI, CoreFoundation

Testing

make test           # Fast tests
make test-all       # All tests, including the documentation examples

Every code example in the documentation is a runnable program under examples/, included into the docs rather than copied. make test-all executes all of them, so a snippet that no longer runs fails the build. See examples/README.md.

Documentation

• CoreMusic Documentation Site

Getting Started

• Quick Start Guide: 5-minute introduction to coremusic

Tutorials

Step-by-step guides for common tasks:

• Audio Playback: Simple to advanced playback, looping, streaming, effects

• Audio Recording: Recording from input devices, monitoring, formats

• MIDI Basics: Devices, messages, sending/receiving MIDI

• Effects Processing: AudioUnit effects chains, parameters, presets

Reference

• CLI Reference: Full command-line interface documentation

• Link Integration Guide: Ableton Link with CoreAudio/CoreMIDI

Resources

• AudioToolbox Documentation

• AudioUnit Programming Guide

• Ableton Link

License

CoreMusic is licensed under the MIT License -- see LICENSE.

The optional coremusic.link module is a derivative work of Ableton Link and is licensed under the GNU General Public License v2.0 (GPLv2). See thirdparty/link/LICENSE.md and thirdparty/link/GNU-GPL-v2.0.md for details.