API Quickstart

A rapid introduction to coremusic's most commonly used APIs.

Import Patterns

# Main package - object-oriented API (recommended)

# Low-level functional API

# Constants (preferred over capi getter functions)
# Optional integrations
import coremusic.utils.scipy as spu  # SciPy integration (requires scipy)
from coremusic.constants import AudioFileProperty, AudioFormatID

Audio File Operations

Read Audio File

from coremusic.audio import AudioFile

# Context manager (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, 1024)

Get Audio Format

from coremusic.audio import AudioFile

with AudioFile("audio.wav") as audio:
    fmt = audio.format
    print(f"Format ID: {fmt.format_id}")           # 'lpcm'
    print(f"Sample rate: {fmt.sample_rate}")       # 44100.0
    print(f"Channels: {fmt.channels_per_frame}")   # 2
    print(f"Bits: {fmt.bits_per_channel}")         # 16

Extended Audio File (Format Conversion)

from coremusic.audio import AudioFormat, ExtendedAudioFile

with ExtendedAudioFile("input.wav") as ext_audio:
    # Set client format for automatic conversion
    ext_audio.client_format = AudioFormat.pcm(sample_rate=48000.0, channels=2)

    # Read converted data
    data, count = ext_audio.read(8192)

AudioUnit Operations

Create Default Output

from coremusic.audio import AudioFormat, AudioUnit

with AudioUnit.default_output() as unit:
    # Set the format you will feed the unit. The output scope is the device's
    # own format, so the client format goes on the input scope.
    audio_format = AudioFormat.pcm(44100.0, channels=2, bits=16)
    unit.set_stream_format(audio_format, scope="input")

    unit.initialize()

    # Start audio processing
    unit.start()
    # ... audio flows ...
    unit.stop()

Find and Create AudioUnit

from coremusic.audio import AudioComponent, AudioComponentDescription

# Create component description
desc = AudioComponentDescription(
    type='aufx',          # Effect
    subtype='dely',       # Delay
    manufacturer='appl',
)

# Find component
component = AudioComponent.find_next(desc)
if component:
    unit = component.create_instance()
    unit.initialize()
    # ... use the unit ...
    unit.dispose()

MIDI Operations

List MIDI Devices

from coremusic import capi

# Count devices
num_devices = capi.midi_get_number_of_devices()
num_sources = capi.midi_get_number_of_sources()
num_destinations = capi.midi_get_number_of_destinations()

print(f"Devices: {num_devices}")
print(f"Sources: {num_sources}")
print(f"Destinations: {num_destinations}")

Create MIDI Client

from coremusic.midi import MIDIClient

client = MIDIClient("My App")
try:
    # Create ports
    output_port = client.create_output_port("Output")
    input_port = client.create_input_port("Input")

    # Use ports...
finally:
    client.dispose()

Audio Queue Operations

Create Output Queue

from coremusic.audio import AudioFormat, AudioQueue

audio_format = AudioFormat.pcm(44100.0, channels=2, bits=16)

queue = AudioQueue.new_output(audio_format)
try:
    # Allocate buffer
    buffer = queue.allocate_buffer(4096)

    # Start playback
    queue.start()

    # ... fill buffer and enqueue ...

    queue.stop()
finally:
    queue.dispose()

Constants Usage

Using Enum Constants

from coremusic.constants import (
    AudioFileProperty,
    AudioFormatID,
    AudioUnitProperty,
    AudioUnitScope,
)

# Audio file properties
prop_id = AudioFileProperty.DATA_FORMAT
prop_id = AudioFileProperty.ESTIMATED_DURATION

# Audio format IDs
fmt_id = AudioFormatID.LINEAR_PCM
fmt_id = AudioFormatID.MPEG4_AAC

# AudioUnit properties
au_prop = AudioUnitProperty.STREAM_FORMAT
au_prop = AudioUnitProperty.SAMPLE_RATE

# AudioUnit scopes
scope = AudioUnitScope.INPUT
scope = AudioUnitScope.OUTPUT

Constants in API Calls

from coremusic import capi
from coremusic.constants import AudioFileProperty

# Use constant enum in functional API
file_id = capi.audio_file_open_url("audio.wav")
format_data = capi.audio_file_get_property(
    file_id,
    int(AudioFileProperty.DATA_FORMAT)  # Convert to int
)
capi.audio_file_close(file_id)

Async Operations

Async File Reading

import asyncio

from coremusic.audio import AsyncAudioFile


async def read_async():
    async with AsyncAudioFile("audio.wav") as audio:
        print(f"Duration: {audio.duration:.2f}s")

        # Stream chunks
        async for chunk in audio.read_chunks_async(chunk_size=4096):
            # Process chunk
            print(len(chunk))

asyncio.run(read_async())

Error Handling

Exception Hierarchy

from coremusic.audio import AudioFile
from coremusic.exceptions import (
    AudioConverterError,
    AudioDeviceError,
    AudioFileError,
    AudioQueueError,
    AudioUnitError,
    AUGraphError,
    CoreAudioError,
    MIDIError,
    MusicPlayerError,
)

try:
    with AudioFile("missing.wav") as audio:
        pass
except AudioFileError as e:
    print(f"Audio file error: {e}")
except CoreAudioError as e:
    print(f"CoreAudio error: {e}")

# Specific exception types:
# - AudioFileError
# - AudioQueueError
# - AudioUnitError
# - AudioConverterError
# - MIDIError
# - MusicPlayerError
# - AudioDeviceError
# - AUGraphError

NumPy Integration

Check Availability

from coremusic.audio import NUMPY_AVAILABLE, AudioFile

if NUMPY_AVAILABLE:
    import numpy as np

    with AudioFile("audio.wav") as audio:
        # Get NumPy dtype
        dtype = audio.format.to_numpy_dtype()

        # Read and convert
        data, count = audio.read_packets(0, 1024)
        samples = np.frombuffer(data, dtype=dtype)

Memory-Mapped Files

from coremusic.audio import MMapAudioFile

with MMapAudioFile("audio.wav") as mapped:
    # Fast random access without decoding the whole file
    chunk = mapped.read_frames(1000, 1000)  # 1000 frames from frame 1000

    # NumPy view over the mapped bytes
    audio_np = mapped.read_as_numpy(start_frame=0, num_frames=44100)
    print(audio_np.shape, mapped.frame_count)

Quick Reference Table

Class	Purpose
cm.AudioFile	Read audio files (WAV, AIFF, MP3, etc.)
cm.ExtendedAudioFile	Read with format conversion
cm.AudioFormat	Audio format description
cm.AudioUnit	Audio processing unit
cm.AudioQueue	Audio playback/recording queue
cm.AudioConverter	Convert between formats
cm.MIDIClient	MIDI client connection
cm.AudioPlayer	High-level audio playback
cm.AsyncAudioFile	Async file operations
cm.AsyncAudioQueue	Async queue operations

See Also

• Full API reference
• Complete getting started guide
• Step-by-step tutorials