Skip to content

Quick Start Guide

Get up and running with coremusic in 5 minutes.

Installation

# Install from PyPI
pip install coremusic

# Or with uv
uv add coremusic

Verify Installation

# Check CLI works
coremusic --version

# List audio devices
coremusic device list

# List MIDI devices
coremusic midi list

Your First Script

Create a file called hello_audio.py:

from coremusic.audio import AudioFile

# Open and inspect an audio file
with AudioFile("audio.wav") as audio:
    print(f"Duration: {audio.duration:.2f} seconds")
    print(f"Sample Rate: {audio.format.sample_rate} Hz")
    print(f"Channels: {audio.format.channels_per_frame}")
    print(f"Bit Depth: {audio.format.bits_per_channel}")

Run it:

python hello_audio.py

Common Tasks

Play Audio

Command Line:

coremusic audio play music.wav

Python:

import time

from coremusic.base import AudioPlayer

player = AudioPlayer()
player.load_file("audio.wav")
player.setup_output()
player.play()

while player.is_playing():
    time.sleep(0.1)

player.stop()

Record Audio

Command Line:

coremusic audio record -o recording.wav --duration 10

Python:

from coremusic.capi import AudioRecorder

recorder = AudioRecorder(sample_rate=44100.0, channels=1)
recorder.setup_input(duration=1.0)
recorder.start()

# Pump the CoreAudio run loop until the requested duration has been captured
while recorder.is_recording():
    recorder.run_loop(0.1)

recorder.stop()
recorder.save_to_file("recording.wav")
print(f"Recorded {recorder.get_recorded_duration():.2f}s")

Convert Audio Format

Command Line:

# Convert to mono WAV
coremusic convert file input.wav output.wav --channels 1

Python:

from coremusic.audio import AudioFormatPresets, convert_audio_file

# Convert stereo to mono
output_format = AudioFormatPresets.wav_44100_mono()
convert_audio_file("input.wav", "output.wav", output_format)

Apply Audio Effects

Command Line:

# Add reverb
coremusic plugin process AUReverb2 input.wav -o output.wav

Python:

from coremusic.audio import AudioEffectsChain

chain = AudioEffectsChain()
chain.open()

reverb = chain.add_effect_by_name("AUReverb2")
output = chain.add_output()
chain.connect(reverb, output)

chain.initialize()
chain.start()
# ... process audio through chain
chain.stop()
chain.dispose()

List Available Plugins

Command Line:

coremusic plugin list

Python:

from coremusic.audio import get_audiounit_names, list_available_audio_units

# List all AudioUnits
units = list_available_audio_units()
for unit in units[:10]:
    print(f"{unit['name']} ({unit['type']})")

# List effect names only
effects = get_audiounit_names(filter_type='aufx')
print(f"{len(effects)} effects installed")

Monitor MIDI Input

Command Line:

coremusic midi monitor

Python:

from coremusic.midi import get_sources

for i, source in enumerate(get_sources()):
    print(f"Source {i}: {source.name}")

Send MIDI Notes

import time

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

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

destinations = get_destinations()
dest = destinations[0] if destinations else client.create_virtual_destination("Synth")

# Send Note On (middle C, velocity 100)
port.send_data(dest, note_on("C4", 100))
time.sleep(0.5)

# Send Note Off
port.send_data(dest, note_off("C4"))

client.dispose()

API Patterns

from coremusic.audio import AudioFile

# Automatic resource cleanup
with AudioFile("audio.wav") as audio:
    data = audio.read_packets(0, 1000)
# File automatically closed

Error Handling

from coremusic.audio import AudioFile
from coremusic.exceptions import AudioFileError

try:
    with AudioFile("audio.wav") as audio:
        data = audio.read_packets(0, 1000)
except AudioFileError as e:
    print(f"Audio error: {e}")
except FileNotFoundError:
    print("File not found")

NumPy Integration

from coremusic.audio import NUMPY_AVAILABLE, AudioFile

if NUMPY_AVAILABLE:
    import numpy as np

    with AudioFile("audio.wav") as audio:
        # Read as NumPy array
        data = audio.read_as_numpy()
        print(f"Shape: {data.shape}")
        print(f"Peak: {np.max(np.abs(data))}")

CLI Command Reference

Audio Commands:
  coremusic audio play <file>              Play audio file
  coremusic audio record -o <file>         Record audio

Device Commands:
  coremusic device list                    List audio devices
  coremusic device info <name>             Device details

Plugin Commands:
  coremusic plugin list                    List AudioUnits
  coremusic plugin process <name> <file>   Apply effect

MIDI Commands:
  coremusic midi list                      List MIDI devices
  coremusic midi monitor             Monitor MIDI input

Analysis Commands:
  coremusic audio info <file>              Audio file info
  coremusic analyze loudness <file>        LUFS measurement

Next Steps

Getting Help

  • Check the API Reference for detailed documentation
  • See Tutorials for worked examples
  • Report issues at https://github.com/shakfu/coremusic/issues