# Import Guide

**Version:** 0.1.8

Complete guide to importing modules and classes from CoreMusic.

## Quick Start

### Most Common Imports

```python
# Main package - Object-Oriented API
import coremusic as cm

# All high-level classes available directly
player = cm.AudioPlayer()
file = cm.AudioFile("audio.wav")
sequence = cm.MusicSequence()

# Functional C API (for performance)
import coremusic.capi as capi
file_id = capi.audio_file_open_url("audio.wav")

# NumPy integration
import numpy as np
import coremusic as cm
```

## Hierarchical Package Structure

CoreMusic uses a hierarchical package structure for better organization:

```
coremusic/
├── __init__.py          # Main package (OO API)
├── capi.pyx            # Functional C API
├── objects.py          # OO wrappers
├── constants.py        # Constants and enums
├── os_status.py        # Error handling
│
├── audio/              # Audio subpackage
│   ├── __init__.py
│   ├── async_io.py     # Async audio I/O
│   ├── utilities.py    # Audio utilities
│   ├── slicing.py      # Audio slicing
│   ├── analysis.py     # Audio analysis
│   ├── visualization.py # Audio visualization
│   └── audiounit_host.py # AudioUnit hosting
│
├── midi/               # MIDI subpackage
│   ├── __init__.py
│   ├── link.py         # Link + MIDI integration
│   └── utilities.py    # MIDI utilities
│
├── utils/              # Utilities subpackage
│   ├── __init__.py
│   ├── scipy.py        # SciPy integration
│   └── fourcc.py       # FourCC utilities
│
└── link.py             # Ableton Link
```

## Import Patterns

### Main Package Imports

**Object-Oriented API (Recommended):**

```python
import coremusic as cm

# Audio file operations
audio = cm.AudioFile("audio.wav")
ext_audio = cm.ExtendedAudioFile("audio.mp3")

# Audio processing
queue = cm.AudioQueue.create_output(format)
unit = cm.AudioUnit.default_output()
converter = cm.AudioConverter()

# MIDI and music
player = cm.MusicPlayer()
sequence = cm.MusicSequence()
track = sequence.new_track()

# Hardware
device = cm.AudioDevice.get_default_output_device()
client = cm.MIDIClient("MyApp")

# Utilities
player = cm.AudioPlayer("song.wav")
```

**Functional C API (For Performance):**

```python
import coremusic.capi as capi

# Direct C function calls
file_id = capi.audio_file_open_url("audio.wav")
format = capi.audio_file_get_property(file_id, property_id)
data, count = capi.audio_file_read_packets(file_id, 0, 1024)
capi.audio_file_close(file_id)

# Constants
property_id = capi.get_audio_file_property_data_format()
format_id = capi.fourchar_to_int('lpcm')
```

### Audio Subpackage Imports

**Async I/O:**

```python
# New hierarchical import (recommended)
from coremusic.audio import AsyncAudioFile, AsyncAudioQueue

# Or
from coremusic.audio.async_io import AsyncAudioFile

# Backward compatible (still works)
from coremusic import AsyncAudioFile
```

**Audio Analysis:**

```python
from coremusic.audio.analysis import (
    AudioAnalyzer,
    LivePitchDetector,
    BeatInfo,
    PitchInfo
)

# Usage
analyzer = AudioAnalyzer("song.wav")
beats = analyzer.detect_beats()
```

**Audio Slicing:**

```python
from coremusic.audio.slicing import AudioSlicer

slicer = AudioSlicer("audio.wav")
slice_data = slicer.slice_time_range(0.0, 10.0)
```

**Audio Visualization:**

```python
from coremusic.audio.visualization import (
    WaveformPlotter,
    SpectrogramPlotter,
    FrequencySpectrumPlotter
)

plotter = WaveformPlotter("audio.wav")
plotter.plot()
```

**AudioUnit Hosting:**

```python
from coremusic.audio.audiounit_host import (
    AudioUnitHost,
    AudioUnitPlugin,
    AudioUnitParameter,
    AudioUnitPreset,
    AudioUnitChain,
    PresetManager
)

host = AudioUnitHost()
plugin = host.load_plugin("AUReverb")
```

### MIDI Subpackage Imports

```python
from coremusic.midi import (
    MIDISequence,
    MIDITrack,
    MIDINote,
    load_midi_file,
    save_midi_file,
    create_midi_message,
    parse_midi_message
)

# Load MIDI file
midi = load_midi_file("song.mid")
print(f"Tempo: {midi.tempo} BPM")
```

**Link + MIDI Integration:**

```python
from coremusic.midi.link import (
    LinkMIDIClock,
    LinkMIDISequencer
)

# Or backward compatible
from coremusic import link_midi
clock = link_midi.LinkMIDIClock()
```

### Utils Subpackage Imports

**SciPy Integration:**

```python
from coremusic.utils.scipy import (
    audio_to_scipy,
    scipy_to_audio,
    apply_scipy_filter,
    resample_scipy
)

# Or
import coremusic.utils.scipy as spu
audio_array = spu.audio_to_scipy("audio.wav")
```

**FourCC Utilities:**

```python
from coremusic.utils.fourcc import (
    fourcc_to_string,
    string_to_fourcc,
    is_valid_fourcc
)

# These are also available from capi
from coremusic import capi
fourcc = capi.fourchar_to_int('lpcm')
string = capi.int_to_fourchar(fourcc)
```

### Link Subpackage Imports

```python
from coremusic import link

# Create Link session
session = link.LinkSession()
session.enable(True)

# Access clock
clock = link.Clock()
micros = clock.micros()

# Session state
state = session.capture_app_session_state()
tempo = state.tempo
```

## Backward Compatibility

CoreMusic maintains full backward compatibility with pre-0.1.8 import patterns.

### Old Import Pattern (Still Works)

```python
# These old imports still work
from coremusic import AsyncAudioFile      # Still works
from coremusic import link_midi           # Still works
from coremusic import AudioAnalyzer       # Still works
```

### New Import Pattern (Recommended)

```python
# New hierarchical imports (preferred)
from coremusic.audio import AsyncAudioFile
from coremusic.midi import link as link_midi
from coremusic.audio.analysis import AudioAnalyzer
```

### Why Use New Imports?

1. **Clearer organization** - Know where functionality lives
2. **Better IDE support** - More accurate autocompletion
3. **Faster imports** - Only load what you need
4. **Future-proof** - Aligned with package structure

## Complete Import Reference

### Core Classes (coremusic.*)

```python
import coremusic as cm

# Base
cm.CoreAudioObject

# Exceptions
cm.CoreAudioError
cm.AudioFileError
cm.AudioQueueError
cm.AudioUnitError
cm.AudioConverterError
cm.MIDIError
cm.MusicPlayerError
cm.AudioDeviceError
cm.AUGraphError

# Audio Format
cm.AudioFormat

# Audio File Framework
cm.AudioFile
cm.AudioFileStream
cm.ExtendedAudioFile

# Audio Converter
cm.AudioConverter

# Audio Queue
cm.AudioBuffer
cm.AudioQueue

# AudioUnit Framework
cm.AudioComponentDescription
cm.AudioComponent
cm.AudioUnit

# MIDI Framework
cm.MIDIClient
cm.MIDIPort
cm.MIDIInputPort
cm.MIDIOutputPort

# Music Player Framework
cm.MusicPlayer
cm.MusicSequence
cm.MusicTrack

# Audio Device
cm.AudioDevice
cm.AudioDeviceManager

# AUGraph
cm.AUGraph

# Audio Clock
cm.AudioClock
cm.ClockTimeFormat

# Audio Player
cm.AudioPlayer
```

### Functional API (coremusic.capi.*)

```python
import coremusic.capi as capi

# All C functions available via capi module
# Examples:
capi.audio_file_open_url()
capi.audio_queue_new_output()
capi.audio_unit_initialize()
capi.midi_client_create()
capi.new_music_player()

# FourCC utilities
capi.fourchar_to_int()
capi.int_to_fourchar()

# Constants (get_* functions)
capi.get_audio_file_property_data_format()
capi.get_audio_unit_property_stream_format()
# ... hundreds of constants
```

### Audio Subpackage (coremusic.audio.*)

```python
from coremusic.audio import (
    # Async I/O
    AsyncAudioFile,
    AsyncAudioQueue,

    # Utilities
    load_audio_file_async,
    create_output_queue_async,
    resample_audio,
    convert_audio_format,

    # Analysis
    AudioAnalyzer,
    LivePitchDetector,
    BeatInfo,
    PitchInfo,

    # Slicing
    AudioSlicer,

    # Visualization
    WaveformPlotter,
    SpectrogramPlotter,
    FrequencySpectrumPlotter,

    # AudioUnit Hosting
    AudioUnitHost,
    AudioUnitPlugin,
    AudioUnitParameter,
    AudioUnitPreset,
    AudioUnitChain,
    PresetManager,
    PluginAudioFormat,
    AudioFormatConverter,
)
```

### MIDI Subpackage (coremusic.midi.*)

```python
from coremusic.midi import (
    # MIDI Utilities
    MIDISequence,
    MIDITrack,
    MIDINote,
    load_midi_file,
    save_midi_file,
    create_midi_message,
    parse_midi_message,
    midi_note_to_name,
    midi_name_to_note,
    transpose_notes,

    # Link Integration
    link,  # Link + MIDI submodule
)

from coremusic.midi.link import (
    LinkMIDIClock,
    LinkMIDISequencer,
)
```

### Utils Subpackage (coremusic.utils.*)

```python
from coremusic.utils import (
    # SciPy integration
    scipy,

    # FourCC utilities
    fourcc,
)

from coremusic.utils.scipy import (
    audio_to_scipy,
    scipy_to_audio,
    apply_scipy_filter,
    resample_scipy,
)

from coremusic.utils.fourcc import (
    fourcc_to_string,
    string_to_fourcc,
    is_valid_fourcc,
)
```

### Link Subpackage (coremusic.link.*)

```python
from coremusic import link

# Link classes
link.LinkSession
link.SessionState
link.Clock

# Or direct import
from coremusic.link import LinkSession, SessionState, Clock
```

## Import Best Practices

### DO: Use Hierarchical Imports

```python
# Good: Clear and explicit
from coremusic.audio.analysis import AudioAnalyzer
from coremusic.midi import load_midi_file
from coremusic import link

# Also good: Import submodule
from coremusic import audio
analyzer = audio.analysis.AudioAnalyzer("song.wav")
```

### DO: Use Aliases for Convenience

```python
# Good: Short, clear aliases
import coremusic as cm
import coremusic.capi as capi
import coremusic.utils.scipy as spu
from coremusic.audio import analysis as audio_analysis
```

### DO: Import Only What You Need

```python
# Good: Specific imports
from coremusic import AudioFile, AudioQueue
from coremusic.audio.analysis import AudioAnalyzer

# Avoid: Importing everything
# from coremusic import *  # Don't do this
```

### DON'T: Use Wildcard Imports

```python
# Bad: Pollutes namespace
from coremusic import *
from coremusic.audio import *

# Good: Be explicit
import coremusic as cm
from coremusic.audio import AsyncAudioFile
```

### DO: Group Imports Logically

```python
# Standard library
import time
from pathlib import Path

# Third-party
import numpy as np

# CoreMusic - main package
import coremusic as cm

# CoreMusic - subpackages
from coremusic.audio import AsyncAudioFile
from coremusic.midi import load_midi_file
from coremusic import link
```

## Import Examples by Use Case

### Basic Audio File Processing

```python
import coremusic as cm
import numpy as np

with cm.AudioFile("audio.wav") as audio:
    data, count = audio.read(audio.frame_count)
    samples = np.frombuffer(data, dtype=np.float32)
```

### Real-Time Audio

```python
import coremusic as cm
from coremusic.audio import AsyncAudioQueue

# Async approach
queue = AsyncAudioQueue.create_output(format)
await queue.start_async()
```

### MIDI Composition

```python
import coremusic as cm
from coremusic.midi import MIDINote

player = cm.MusicPlayer()
sequence = cm.MusicSequence()
track = sequence.new_track()
track.add_midi_note(0.0, 0, 60, 100)
```

### Audio Analysis

```python
from coremusic.audio.analysis import AudioAnalyzer

analyzer = AudioAnalyzer("song.wav")
analyzer.load_audio()
beats = analyzer.detect_beats()
pitch = analyzer.detect_pitch()
```

### Link Synchronization

```python
from coremusic import link

session = link.LinkSession()
session.enable(True)
state = session.capture_app_session_state()
tempo = state.tempo
```

## Type Hints and IDE Support

CoreMusic includes comprehensive type hints for better IDE support:

```python
import coremusic as cm
from typing import Optional, List

# IDE will show type hints
audio: cm.AudioFile = cm.AudioFile("audio.wav")
format: cm.AudioFormat = audio.format
duration: float = audio.duration

# Function signatures include type hints
def process_audio(
    file_path: str,
    output_path: str,
    gain: float = 1.0
) -> Optional[cm.AudioFile]:
    """Process audio with type hints"""
    pass
```

## Troubleshooting Imports

### ModuleNotFoundError

```python
# Error: ModuleNotFoundError: No module named 'coremusic'

# Solution: Install coremusic
# pip install coremusic
# or
# uv pip install coremusic
```

### ImportError for Submodule

```python
# Error: ImportError: cannot import name 'AsyncAudioFile'

# Check if using correct import path
from coremusic.audio import AsyncAudioFile  # Correct
from coremusic.audio.async_io import AsyncAudioFile  # Also correct
from coremusic import AsyncAudioFile  # Backward compatible
```

### Circular Import

```python
# If you get circular import errors, try:

# Instead of:
import coremusic
from coremusic import AudioFile

# Do:
import coremusic as cm
audio = cm.AudioFile("audio.wav")
```

## Quick Reference Card

```python
# === Core Package ===
import coremusic as cm                    # Main OO API
import coremusic.capi as capi             # Functional C API

# === Audio Subpackage ===
from coremusic.audio import (
    AsyncAudioFile,                       # Async file I/O
    AudioAnalyzer,                        # Audio analysis
    AudioSlicer,                          # Audio slicing
    WaveformPlotter,                      # Visualization
    AudioUnitHost,                        # AudioUnit hosting
)

# === MIDI Subpackage ===
from coremusic.midi import (
    load_midi_file,                       # MIDI file utilities
    MIDISequence,                         # MIDI data structures
    link,                                 # Link + MIDI
)

# === Utils Subpackage ===
from coremusic.utils import scipy, fourcc

# === Link Subpackage ===
from coremusic import link
session = link.LinkSession()
```

## See Also

- Use `help(cm.AudioFile)` in Python for API reference
- See `tests/demos/` directory for examples
- See full documentation at [Documentation Index](../index.md)

!!! note
    **Migration from Old Imports:**
    All old import patterns continue to work. Update at your convenience!
