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

Where the Examples Live¶

Every snippet in this documentation is a runnable program under examples/, arranged by the page that includes it. They are executed by the test suite, so a snippet that no longer runs fails the build rather than reaching you.

# Run one
python examples/tutorials/midi_basics/send_note.py

# Run all of them, as the test suite does
pytest tests/test_examples.py

Larger standalone programs live elsewhere in the repository:

demos/ - four end-to-end demos: an AudioUnit effect chain, MIDI rendered to WAV, a real-time tone, and a Link-synchronised sequencer. make demos runs them.
extras/ - utilities (audio inspector, converter) and experimental modules (a DAW-style timeline, generative algorithms) that are not part of the package.

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 sys

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


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:
        with AudioFile(filepath) as audio:
            print(f"{filepath}: {audio.duration:.2f}s")

    except 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 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()

Format conversion:

from coremusic.audio import AudioConverter, AudioFormat

# Define formats
src_fmt = AudioFormat.pcm(44100.0, channels=2, bits=16)
dst_fmt = AudioFormat.pcm(44100.0, channels=2, bits=32, is_float=True)

# One second of silence, as 16-bit stereo
input_data = bytes(44100 * 2 * 2)

# Convert. `convert()` handles depth and channel changes; a change of sample
# rate needs `convert_with_callback()`, which pulls input as the converter
# asks for it.
converter = AudioConverter(src_fmt, dst_fmt)
output = converter.convert(input_data)
print(f"{len(input_data)} bytes in, {len(output)} bytes out")

MIDI routing:

import time

from coremusic.midi import MIDIClient, get_destinations, get_sources

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

for source in get_sources():
    input_port.connect_source(source)

destinations = get_destinations()
destination = (
    destinations[0] if destinations else client.create_virtual_destination("Routed")
)

# Route MIDI data for a second. A real router would run until stopped.
deadline = time.monotonic() + 1.0
while time.monotonic() < deadline:
    if input_port.wait(0.1):
        for _host_time, midi_data in input_port.poll():
            output_port.send_data(destination, midi_data)

client.dispose()

Real-time processing:

from coremusic.audio import AudioFormat, AudioUnit

# Create and configure an AudioUnit
with AudioUnit.default_output() as unit:
    format = AudioFormat.pcm(sample_rate=44100.0, channels=2, bits=16)
    unit.set_stream_format(format, scope="input")
    unit.initialize()
    unit.start()
    # ... audio processing ...
    unit.stop()

Contributing Examples¶

We welcome example contributions! To add an example:

Create a standalone, working script
Add comprehensive docstrings
Include usage instructions
Handle errors gracefully
Add to the examples directory
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