Skip to content

Examples Gallery

Complete, working examples demonstrating coremusic capabilities.

Example Categories

Basic Examples

Essential examples for getting started:

  • Audio Player: Simple audio file playback
  • Audio Converter: Convert between audio formats
  • Audio Inspector: Display detailed file information
  • MIDI Monitor: Monitor MIDI input

Audio Processing

Audio processing and manipulation:

  • Real-time Processor: Process audio in real-time
  • Batch Converter: Convert multiple files
  • Audio Analyzer: Analyze audio characteristics
  • Waveform Generator: Generate audio waveforms

AudioUnit Examples

Working with AudioUnits:

  • AudioUnit Explorer: Discover available AudioUnits
  • Effect Chain: Chain multiple audio effects
  • Custom Processor: Create custom AudioUnit
  • Parameter Controller: Automate parameters

MIDI Examples

MIDI processing and routing:

  • MIDI Router: Route MIDI between devices
  • MIDI Transformer: Transform MIDI messages
  • Virtual Keyboard: Create virtual MIDI keyboard
  • MIDI Recorder: Record MIDI sequences

Advanced Examples

Advanced techniques and integration:

  • Multi-channel Processor: Handle surround audio
  • Low Latency Streamer: Minimal latency streaming
  • Audio Visualizer: Real-time visualization
  • SciPy Integration: Signal processing with SciPy

Running the Examples

All examples are standalone Python scripts that can be run directly:

# From the project root
python examples/audio_player.py audio.wav

# Or from the examples directory
cd examples
python audio_player.py ../tests/amen.wav

Prerequisites

All examples require:

  • coremusic installed and built
  • macOS with CoreAudio
  • Python 3.6+

Some examples have additional requirements:

  • NumPy: For audio analysis examples
  • SciPy: For signal processing examples
  • Matplotlib: For visualization examples

Install optional dependencies:

pip install numpy scipy matplotlib

Example Template

Use this template for creating new examples:

#!/usr/bin/env python3
"""
Example: [Example Name]

Description: [What this example demonstrates]

Usage: python example_name.py [arguments]
"""

import coremusic as cm
import sys

def main():
    """Main function."""
    # Argument parsing
    if len(sys.argv) < 2:
        print("Usage: python example_name.py <audio_file>")
        sys.exit(1)

    filepath = sys.argv[1]

    # Example implementation
    try:
        # Your code here
        pass

    except cm.AudioFileError as e:
        print(f"Audio file error: {e}")
        sys.exit(1)
    except Exception as e:
        print(f"Error: {e}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Quick Reference

Common Example Patterns

Simple audio playback:

import coremusic as cm

player = cm.AudioPlayer()
player.load_file("audio.wav")
player.setup_output()
player.start()

Format conversion:

import coremusic as cm

# Define formats
src_fmt = cm.AudioFormat(44100.0, 'lpcm', ...)
dst_fmt = cm.AudioFormat(48000.0, 'lpcm', ...)

# Convert
converter = cm.AudioConverter(src_fmt, dst_fmt)
output = converter.convert(input_data, frame_count)

MIDI routing:

import coremusic as cm

client = cm.MIDIClient("Router")
input_port = client.create_input_port("Input")
output_port = client.create_output_port("Output")

# Route MIDI data
output_port.send_data(destination, midi_data)

Real-time processing:

import coremusic as cm

with cm.AudioUnit.default_output() as unit:
    format = cm.AudioFormat(44100.0, 'lpcm', ...)
    unit.set_stream_format(format)
    unit.start()
    # Process audio
    unit.stop()

Contributing Examples

We welcome example contributions! To add an example:

  1. Create a standalone, working script
  2. Add comprehensive docstrings
  3. Include usage instructions
  4. Handle errors gracefully
  5. Add to the examples directory
  6. Update this documentation

Example Guidelines:

  • Clear purpose: Each example should demonstrate one concept
  • Self-contained: Minimize external dependencies
  • Well-commented: Explain non-obvious code
  • Error handling: Handle common errors
  • Usage help: Print usage if arguments are missing

See Also